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