Next: , Previous: Backward Compatibility, Up: Controlling where ASDF searches for systems


8.5 Configuration DSL

Here is the grammar of the s-expression (SEXP) DSL for source-registry configuration:

     ;; A configuration is a single SEXP starting with the keyword
     ;; :source-registry followed by a list of directives.
     CONFIGURATION := (:source-registry DIRECTIVE ...)
     
     ;; A directive is one of the following:
     DIRECTIVE :=
         ;; INHERITANCE DIRECTIVE:
         ;; Your configuration expression MUST contain
         ;; exactly one of the following:
         :inherit-configuration |
         ;; splices inherited configuration (often specified last) or
         :ignore-inherited-configuration |
         ;; drop inherited configuration (specified anywhere)
     
         ;; forward compatibility directive (since ASDF 2.011.4), useful when
         ;; you want to use new configuration features but have to bootstrap
         ;; the newer required ASDF from an older release that doesn't
         ;; support said features:
         :ignore-invalid-entries |
     
         ;; add a single directory to be scanned (no recursion)
         (:directory DIRECTORY-PATHNAME-DESIGNATOR) |
     
         ;; add a directory hierarchy, recursing but
         ;; excluding specified patterns
         (:tree DIRECTORY-PATHNAME-DESIGNATOR) |
     
         ;; override the defaults for exclusion patterns
         (:exclude EXCLUSION-PATTERN ...) |
         ;; augment the defaults for exclusion patterns
         (:also-exclude EXCLUSION-PATTERN ...) |
         ;; Note that the scope of a an exclude pattern specification is
         ;; the rest of the current configuration expression or file.
     
         ;; splice the parsed contents of another config file
         (:include REGULAR-FILE-PATHNAME-DESIGNATOR) |
     
         ;; This directive specifies that some default must be spliced.
         :default-registry
     
     REGULAR-FILE-PATHNAME-DESIGNATOR
         := PATHNAME-DESIGNATOR ; interpreted as a file
     DIRECTORY-PATHNAME-DESIGNATOR
         := PATHNAME-DESIGNATOR ; interpreted as a directory
     
     PATHNAME-DESIGNATOR :=
         NIL | ;; Special: skip this entry.
         ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL
     
     EXCLUSION-PATTERN := a string without wildcards, that will be matched
         exactly against the name of a any subdirectory in the directory
         component of a path. e.g. "_darcs" will match
         #p"/foo/bar/_darcs/src/bar.asd"

Pathnames are designated using another DSL, shared with the output-translations configuration DSL below. The DSL is resolved by the function asdf::resolve-location, to be documented and exported at some point in the future.

     ABSOLUTE-COMPONENT-DESIGNATOR :=
         (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
         STRING |
         ;; namestring (better be absolute or bust, directory assumed where
         ;; applicable).  In output-translations, directory is assumed and
         ;; **/*.*.* added if it's last.  On MCL, a MacOSX-style POSIX
         ;; namestring (for MacOS9 style, use #p"..."); Note that none of the
         ;; above applies to strings used in *central-registry*, which
         ;; doesn't use this DSL: they are processed as normal namestrings.
         ;; however, you can compute what you put in the *central-registry*
         ;; based on the results of say
         ;; (asdf::resolve-location "/Users/fare/cl/cl-foo/")
         PATHNAME |
         ;; pathname (better be an absolute path, or bust)
         ;; In output-translations, unless followed by relative components,
         ;; it better have appropriate wildcards, as in **/*.*.*
         :HOME | ; designates the user-homedir-pathname ~/
         :USER-CACHE | ; designates the default location for the user cache
         :HERE |
         ;; designates the location of the configuration file
         ;; (or *default-pathname-defaults*, if invoked interactively)
         :ROOT
         ;; magic, for output-translations source only: paths that are relative
         ;; to the root of the source host and device
     
     They keyword :SYSTEM-CACHE is not accepted in ASDF 3.1 and beyond: it
     was a security hazard.
     
     RELATIVE-COMPONENT-DESIGNATOR :=
         (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) |
         STRING |
           ;; relative directory pathname as interpreted by
           ;; parse-unix-namestring.
           ;; In output translations, if last component, **/*.*.* is added
         PATHNAME | ; pathname; unless last component, directory is assumed.
         :IMPLEMENTATION |
            ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64
         :IMPLEMENTATION-TYPE |
            ;; a directory based on lisp-implementation-type only, e.g. sbcl
         :DEFAULT-DIRECTORY |
            ;; a relativized version of the default directory
         :*/ | ;; any direct subdirectory (since ASDF 2.011.4)
         :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4)
         :*.*.* | ;; any file (since ASDF 2.011.4)
     
     The keywords :UID and :USERNAME are no longer supported.

For instance, as a simple case, my ~/.config/common-lisp/source-registry.conf, which is the default place ASDF looks for this configuration, once contained:

     (:source-registry
       (:tree (:home "cl")) ;; will expand to e.g. "/home/joeluser/cl/"
       :inherit-configuration)