From 7177edafdb284772546806dcb3b3bc842994b407 Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <fare@tunes.org> Date: Wed, 16 Jun 2010 18:46:51 -0400 Subject: [PATCH] Improve configuration DSL documentation based on feedback from Xach. Clean up a test script. --- doc/asdf.texinfo | 66 +++++++++++++++++++++++++++++++---------------- test/test1.script | 1 - 2 files changed, 44 insertions(+), 23 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 75843ccd..dc687902 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -338,19 +338,19 @@ If you're using some tool to install software, the authors of that tool should already have configured ASDF. The simplest way to add a path to your search path, -say @file{/foo/bar/baz/quux/} +say @file{/home/luser/.asd-link-farm/} is to create the directory @file{~/.config/common-lisp/source-registry.conf.d/} and there create a file with any name of your choice but the type @file{conf}, -for instance @file{42-bazquux.conf} +for instance @file{42-asd-link-farm.conf} containing the line: -@kbd{(:directory "/foo/bar/baz/quux/")} +@kbd{(:directory "/home/luser/.asd-link-farm/")} -If you want all the subdirectories under @file{/foo/bar/baz/} +If you want all the subdirectories under @file{/home/luser/lisp/} to be recursively scanned for @file{.asd} files, instead use: -@kbd{(:tree "/foo/bar/baz/quux/")} +@kbd{(:tree "/home/luser/lisp/")} Note that your Operating System distribution or your system administrator may already have configured system-managed libraries for you. @@ -894,8 +894,9 @@ be forced upon you if you were specifying a string. @subsection Warning about logical pathnames @cindex logical pathnames -We recommend that you no use logical pathnames in your asdf system -definitions, but logical pathnames @emph{are} supported. +We recommend that you not use logical pathnames +in your asdf system definitions at this point, +but logical pathnames @emph{are} supported. To use logical pathnames, you will have to provide a pathname object as a @code{:pathname} specifier @@ -919,8 +920,9 @@ system that uses logical pathnames will be have differently under asdf-output-translations than other systems you use. If you wish to use logical pathnames you will have to configure the -translations yourself before they may be used. ASDF provides no -specific support for defining logical pathname translations. +translations yourself before they may be used. +ASDF currently provides no specific support +for defining logical pathname translations. @subsection Serial dependencies @@ -932,8 +934,8 @@ on all the children textually preceding it. This is done as if by @code{:depends-on}. @lisp -:components ((:file "a") (:file "b") (:file "c")) :serial t +:components ((:file "a") (:file "b") (:file "c")) @end lisp is equivalent to @@ -1732,6 +1734,12 @@ CONFIGURATION := (:source-registry DIRECTIVE ...) ;; A directive is one of the following: DIRECTIVE := + ;; INHERITANCE DIRECTIVE: + ;; Your configuration expression MUST contain + ;; exactly one of either of these: + :inherit-configuration | ; splices inherited configuration (often specified last) + :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere) + ;; add a single directory to be scanned (no recursion) (:directory DIRECTORY-PATHNAME-DESIGNATOR) | @@ -1746,11 +1754,6 @@ DIRECTIVE := ;; splice the parsed contents of another config file (:include REGULAR-FILE-PATHNAME-DESIGNATOR) | - ;; Your configuration expression MUST contain - ;; exactly one of either of these: - :inherit-configuration | ; splices contents of inherited configuration - :ignore-inherited-configuration | ; drop contents of inherited configuration - ;; This directive specifies that some default must be spliced. :default-registry @@ -1759,6 +1762,15 @@ PATTERN := a string without wildcards, that will be matched exactly of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"} @end example +For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf}, +which is the default place ASDF looks for this configuration, +once contained: +@example +(:source-registry + (:tree "/home/fare/cl/") + :inherit-configuration) +@end example + @section Configuration Directories @@ -1767,7 +1779,7 @@ a list of directives without any enclosing @code{(:source-registry ...)} form. The files will be sorted by namestring as if by @code{string<} and the lists of directives of these files with be concatenated in order. An implicit @code{:inherit-configuration} will be included -at the end of the list. +at the @emph{end} of the list. This allows for packaging software that has file granularity (e.g. Debian's @code{dpkg} or some future version of @code{clbuild}) @@ -1787,6 +1799,15 @@ or namestring in an @code{:include} directive, e.g.: (:include "/foo/bar/") @end example +Hence, to achieve the same effect as +my example @file{~/.config/common-lisp/source-registry.conf} above, +I could simply create a file +@file{~/.config/common-lisp/source-registry.conf.d/33-home-fare-cl.conf} +alone in its directory with the following contents: +@example +(:tree "/home/fare/cl/") +@end example + @section Shell-friendly syntax for configuration @@ -2136,13 +2157,14 @@ CONFIGURATION := (:output-translations DIRECTIVE ...) ;; A directive is one of the following: DIRECTIVE := - ;; include a configuration file or directory - (:include PATHNAME-DESIGNATOR) | - + ;; INHERITANCE DIRECTIVE: ;; Your configuration expression MUST contain ;; exactly one of either of these: - :inherit-configuration | ; splices contents of inherited configuration - :ignore-inherited-configuration | ; drop contents of inherited configuration + :inherit-configuration | ; splices inherited configuration (often specified last) + :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere) + + ;; include a configuration file or directory + (:include PATHNAME-DESIGNATOR) | ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.35-x86-64/ or something. :enable-user-cache | @@ -2258,7 +2280,7 @@ a list of directives without any enclosing The files will be sorted by namestring as if by @code{string<} and the lists of directives of these files with be concatenated in order. An implicit @code{:inherit-configuration} will be included -at the end of the list. +at the @emph{end} of the list. This allows for packaging software that has file granularity (e.g. Debian's @command{dpkg} or some future version of @command{clbuild}) diff --git a/test/test1.script b/test/test1.script index 3c4462ce..bc23f8b4 100644 --- a/test/test1.script +++ b/test/test1.script @@ -19,7 +19,6 @@ ;; now remove one output file and check that the other is _not_ recompiled - ;;(trace asdf::operation-done-p asdf::traverse) (asdf::run-shell-command "rm -f ~A" (namestring file2)) (asdf:operate 'asdf:load-op 'test1) (assert (= file1-date (file-write-date file1))) -- GitLab