From e25aef0a2273486b14ca6f9d0d2457e579818f17 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@real-time.com> Date: Sat, 13 Mar 2010 16:15:48 -0600 Subject: [PATCH] README.source-registry now subsumed into asdf.texinfo. --- README.source-registry | 315 ----------------------------------------- 1 file changed, 315 deletions(-) delete mode 100644 README.source-registry diff --git a/README.source-registry b/README.source-registry deleted file mode 100644 index c17028b0..00000000 --- a/README.source-registry +++ /dev/null @@ -1,315 +0,0 @@ -=========================== -Common Lisp Source Registry -=========================== - -This file specifies how build systems such as ASDF and XCVB -may be configured with respect to filesystem paths -where to search for Common Lisp source code. - -Configurations -============== - -Configurations specify paths where to find system files. - - 1- An application may explicitly initialize the source-registry - configuration using the `Configuration API`_ below, - in which case this takes precedence. - It may itself compute this configuration from the command-line, - from a script, from its own configuration file, etc. - - 2- The source registry will be configured from - the environment variable ``CL_SOURCE_REGISTRY`` if it exists. - - 3- The source registry will be configured from - user configuration file - ``~/.config/common-lisp/source-registry.conf`` - if it exists. - - 4- The source registry will be configured from - user configuration directory - ``~/.config/common-lisp/source-registry.conf.d/`` - if it exists. - - 5- The source registry will be configured from - system configuration file - ``/etc/common-lisp/source-registry.conf`` - if it exists. - - 6- The source registry will be configured from - system configuration directory - ``/etc/common-lisp/source-registry.conf.d/`` - if it exists. - - 7- The source registry will be configured from a default configuration, - which allows for implementation-specific software to be searched. - (See below `Backward Compatibility`_). - -Each of these configuration is specified as a SEXP -in a trival domain-specific language (defined below). -Additionally, a more shell-friendly syntax is available -for the environment variable (defined yet below). - -Each of these configurations is only used if the previous -configuration explicitly or implicitly specifies that it -includes its inherited configuration. - -Additionally, some implementation-specific directories -may be automatically prepended to whatever directories are specified -in configuration files, no matter if the last one inherits or not. - - - -Backward Compatibility -====================== - -For backward compatibility, ASDF will fall back to its old ways -of searching for ``.asd`` files in the directories specified in -``asdf:*central-registry*`` -if it fails to find a configuration for the source registry, or -if it fails to find a requested system in the configured source registry. -This new mechanism will therefore not affect you if you don't use it, -but will take precedence over the old mechanism if you do use it. - -Moreover, when using SBCL, now as before, ASDF will first look -for a matching system in the implementation-specific ``contrib`` directory. -This allows for some magic implementation-provided systems -to be loaded specially in a version that matches your implementation. - - -Configuration DSL -================= - -Here is the grammar of the SEXP DSL for source-registry configuration: - -;; A configuration is single SEXP starting with keyword :source-registry -;; followed by a list of directives. -CONFIGURATION := (:source-registry DIRECTIVE ...) - -;; A directive is one of the following: -DIRECTIVE := - ;; 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 default defaults for exclusion patterns - (:exclude PATTERN ...) | - - ;; 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 - -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" - - -Configuration Directories -========================= - -Configuration directories consist in files each contains -a list of directives without any enclosing ``(:source-registry ...)`` form. -The files will be sorted by namestring as if by #'string< and -the lists of directives of these files with be concatenated in order. -An implicit ``:inherit-configuration`` will be included -at the end of the list. - -This allows for packaging software that has file granularity -(e.g. Debian's ``dpkg`` or some future version of ``clbuild``) -to easily include configuration information about distributed software. - -Directories may be included by specifying a directory pathname -or namestring in an ``:include`` directive, e.g.:: - (:include "/foo/bar/") - - -Shell-friendly syntax for configuration -======================================= - -When considering environment variable ``CL_SOURCE_REGISTRY`` -ASDF will skip to next configuration if it's an empty string. -It will ``READ`` the string as a SEXP in the DSL -if it begins with a paren ``(`` -and it will be interpreted much like ``TEXINPUTS`` -as ``:`` (colon) separated list of paths, where - - * each entry is a directory to add to the search path. - - * if the entry ends with a double slash ``//`` - then it instead indicates a tree in the subdirectories - of which to recurse. - - * if the entry is the empty string (which may only appear once), - then it indicates that the inherited configuration should be - spliced there. - - -Search Algorithm -================ - -In case that isn't clear, the semantics of the configuration is that -when searching for a system of a given name, -directives are processed in order. - -When looking in a directory, if the system is found, the search succeeds, -otherwise it continues. - -When looking in a tree, if one system is found, the search succeeds. -If multiple systems are found, the consequences are unspecified: -the search may succeed with any of the found systems, -or an error may be raised. -ASDF currently returns the first system found, -XCVB currently raised an error. -If none is found, the search continues. - -Exclude statements specify patterns of subdirectories the systems of which -to ignore. Typically you don't want to use copies of files kept by such -version control systems as Darcs. - -Include statements cause the search to recurse with the path specifications -from the file specified. - -An inherit-configuration statement cause the search to recurse with the path -specifications from the next configuration -(see section Configurations_ above). - - -Caching Results -=============== - -The implementation is allowed to either eagerly compute the information -from the configurations and file system, or to lazily re-compute it -every time, or to cache any part of it as it goes. -To explicitly flush any information cached by the system, use the API below. - - -Configuration API -================= - -The specified functions are exported from your build system's package. -Thus for ASDF the corresponding functions are in package ASDF, -and for XCVB the corresponding functions are in package XCVB. - -(initialize-source-registry) - will read the configuration and initialize all internal variables. - -(clear-source-registry) - undoes any source registry configuration - and clears any cache for the search algorithm. - You might want to call that before you - dump an image that would be resumed with a different configuration, - and return an empty configuration. - Note that this does not include clearing information about - systems defined in the current image, only about - where to look for systems not yet defined. - -(ensure-source-registry) - checks whether a source registry has been initialized. - If not, initialize it. - This function will be called before any attempt to find a system - in the source registry. - If your application wants to override the provided defaults, - it will have to use the below function process-source-registry. - -(process-source-registry X &key inherit collect) - If X is a CONS, parse it as a SEXP in the configuration DSL, - and extend or override inheritted configuration. - If X is a STRING, first parse it into a SEXP - as for the CL_SOURCE_REGISTRY - environment variable (see above) then process it. - If X is a PATHNAME, read the file as a single SEXP and process it. - The inheritted configuration is provided in keyword argument inherit, - itself a list of functions that take inherit - and collect keyword arguments - and defaulting to a list of functions - that implements the default behavior. - - -Future -====== - -If this mechanism is successful, in the future, we may declare -``asdf:*central-registry*`` obsolete and eventually remove it. -Any hook into implementation-specific search mechanisms will by then -have been integrated in the ``:default-configuration`` which everyone -should either explicitly use or implicit inherit. Some shell syntax -for it should probably be added somehow. - -But we're not there yet. For now, let's see how practical this new -source-registry is. - - -Rejected ideas -============== - -Alternatives I considered and rejected included: - -1- Keep asdf:*central-registry* as the master with its current semantics, - and somehow the configuration parser expands the new configuration - language into a expanded series of directories of subdirectories to - lookup, pre-recursing through specified hierarchies. This is kludgy, - and leaves little space of future cleanups and extensions. - -2- Keep asdf:*central-registry* remains the master but extend its semantics - in completely new ways, so that new kinds of entries may be implemented - as a recursive search, etc. This seems somewhat backwards. - -3- Completely remove asdf:*central-registry* - and break backwards compatibility. - Hopefully this will happen in a few years after everyone migrate to - a better ASDF and/or to XCVB, but it would be very bad to do it now. - -4- Replace asdf:*central-registry* by a symbol-macro with appropriate magic - when you dereference it or setf it. Only the new variable with new - semantics is handled by the new search procedure. - - -I've been suggested the below features, but have rejected them, -for the sake of keeping ASDF no more complex than strictly necessary. - -* More syntactic sugar: synonyms for the configuration directives, such as - (:add-directory X) for (:directory X), or (:add-directory-hierarchy X) - or (:add-directory X :recurse t) for (:tree X). - -* The possibility to register individual files instead of directories. - -* Integrate Xach Beane's tilde expander into the parser, - or something similar that is shell-friendly or shell-compatible. - I'd rather keep ASDF minimal. But maybe this precisely keeps it - minimal by removing the need for evaluated entries that ASDF has? - i.e. uses of USER-HOMEDIR-PATHNAME and $SBCL_HOME - Hopefully, these are already superseded by the :default-registry - -* Using the shell-unfriendly syntax /** instead of // to specify recursion - down a filesystem tree in the environment variable. - It isn't that Lisp friendly either. - -TODO -==== - -* Integrate into the rest of the documentation. -* Add examples -* Add proper defaults. -* Get inspired by the XDG base directory specification? - http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html - - -Credits -======= - -Thanks a lot to Stelian Ionescu for the initial idea. - -Thanks to Rommel Martinez for the initial implementation attempt. - -All bad design ideas and implementation bugs are to mine, not theirs. -But so are good design ideas and elegant implementation tricks. - - -- Francois-Rene Rideau <fare@tunes.org>, Mon, 22 Feb 2010 00:07:33 -0500 -- GitLab