From 1121a16286eb316135c72812aa69f52292562d43 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Tue, 25 Feb 2014 08:27:10 -0600 Subject: [PATCH] Interim commit. Partial restructuring of introductory material. Node structure is still messed up. --- doc/asdf.texinfo | 109 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 74 insertions(+), 35 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 81d3cfe1..4674d53f 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -198,7 +198,7 @@ If you want to download software from version control instead of tarballs, so you may more easily modify it, we recommend clbuild. -@node Loading ASDF, Configuring ASDF, Introduction, Top +@node Loading ASDF, Using ASDF, Introduction, Top @comment node-name, next, previous, up @chapter Loading ASDF @vindex *central-registry* @@ -430,32 +430,67 @@ for example by loading it from the startup script or dumping a custom core @chapter Configuring ASDF +For standard use cases, ASDF should work pretty much out of the box. We +recommend you skim the sections on configuring ASDF to find your systems +to choose the method of installing Lisp software that works best for +you. Then skip directly to @xref{Using ASDF}; that will probably be +enough. You are unlikely to have to worry about the way ASDF stores +object files, and resetting the ASDF configuration is usually only +needed in corner cases. + + +@menu +* Configuring ASDF to find your systems :: +* Configuring ASDF to find your systems --- old style :: +* Configuring where ASDF stores object files :: +* Resetting the ASDF configuration :: +@end menu + +@node Configuring ASDF to find your systems, Configuring ASDF to find your systems --- old style, Loading ASDF, Loading ASDF @section Configuring ASDF to find your systems -So it may compile and load your systems, ASDF must be configured to find +In order to compile and load your systems, ASDF must be configured to find the @file{.asd} files that contain system definitions. -Since ASDF 2, the preferred way to configure where ASDF finds your systems is -the @code{source-registry} facility, -fully described in its own chapter of this manual. -@xref{Controlling where ASDF searches for systems}. +There are a number of different techniques for setting yourself up with +ASDF, starting from easiest to the most complex: -The default location for a user to install Common Lisp software is under +@itemize @bullet + +@item +Put all of your systems in subdirectories of @file{~/.local/share/common-lisp/source/}. If you install software there (it can be a symlink), you don't need further configuration. -If you're installing software yourself at a location that isn't standard, -you have to tell ASDF where you installed it. See below. + +@item If you're using some tool to install software (e.g. Quicklisp), the authors of that tool should already have configured ASDF. +@item +If you have more specific desires about how to lay out your software on +disk, the preferred way to configure where ASDF finds your systems is +the @code{source-registry} facility, +fully described in its own chapter of this manual. +@xref{Controlling where ASDF searches for systems}. Here is a quick +recipe for getting started: + The simplest way to add a path to your search path, 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, -and with the type @file{conf}, -for instance @file{42-asd-link-farm.conf} +and with the type @file{conf}@footnote{By requiring the @file{.conf} +extension, and ignoring other files, ASDF allows you to have disabled files, +editor backups, etc. in the same directory with your active +configuration files. + +ASDF will also ignore files whose names start with a @file{.} character. + +It is customary to start the filename with two digits, to control the +sorting of the @code{conf} files in the source registry directory, and +thus the order in which the directories will be scanned.}, +for instance @file{42-asd-link-farm.conf}, containing the line: @kbd{(:directory "/home/luser/.asd-link-farm/")} @@ -465,20 +500,9 @@ to be recursively scanned for @file{.asd} files, instead use: @kbd{(:tree "/home/luser/lisp/")} -Note that your Operating System distribution or your system administrator -may already have configured system-managed libraries for you. - -@c FIXME: clarify. -The required @file{.conf} extension allows you to have disabled files -or editor backups (ending in @file{~}), and works portably -(for instance, it is a pain to allow both empty and non-empty extension on CLISP). -Excluded are files the name of which start with a @file{.} character. -It is customary to start the filename with two digits -that specify the order in which the directories will be scanned. - ASDF will automatically read your configuration the first time you try to find a system. -You can reset the source-registry configuration with: +If necessary, you can reset the source-registry configuration with: @lisp (asdf:clear-source-registry) @@ -487,14 +511,28 @@ You can reset the source-registry configuration with: @c FIXME: too specific. Push this down to discussion of dumping an @c image? -And you probably should do so before you dump your Lisp image, -if the configuration may change -between the machine where you save it at the time you save it -and the machine you resume it at the time you resume it. -Actually, you should use @code{(asdf:clear-configuration)} -before you dump your Lisp image, which includes the above. +@c And you probably should do so before you dump your Lisp image, +@c if the configuration may change +@c between the machine where you save it at the time you save it +@c and the machine you resume it at the time you resume it. +@c Actually, you should use @code{(asdf:clear-configuration)} +@c before you dump your Lisp image, which includes the above. + +@item +In earlier versions of ASDF, the system source registry was configured +using a global variable, @code{asdf:*central-registry*}. For more +details about this, see the following section, @ref{Configuring ASDF to +find your systems --- old style}. Unless you need to understand this, +skip directly to @ref{Configuring where ASDF stores object files}. + +@end itemize + +Note that your Operating System distribution or your system administrator +may already have configured system-managed libraries for you. + +@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Loading ASDF @section Configuring ASDF to find your systems --- old style The old way to configure ASDF to find your systems is by @@ -580,6 +618,7 @@ but it is supported for old users, and for users who want to programmatically control what directories are added to the ASDF search path. +@node Configuring where ASDF stores object files, Resetting the ASDF configuration, Configuring ASDF to find your systems --- old style, Loading ASDF @section Configuring where ASDF stores object files @findex clear-output-translations @@ -659,11 +698,11 @@ ASDF-Binary-Locations is now not needed anymore and should not be used. cl-launch 3.000 and common-lisp-controller 7.2 have been updated to just delegate this functionality to ASDF. -@node Using ASDF, Defining systems with defsystem, Configuring ASDF, Top +@node Using ASDF, Resetting the ASDF configuration, Configuring where ASDF stores object files, Loading ASDF @comment node-name, next, previous, up - -@section Resetting Configuration +@node Resetting the ASDF configuration, , Configuring where ASDF stores object files, Loading ASDF +@section Resetting the ASDF configuration When you dump and restore an image, or when you tweak your configuration, you may want to reset the ASDF configuration. @@ -688,7 +727,7 @@ For compatibility with all Lisp implementations, however, you might want instead your build script to explicitly call @code{(asdf:clear-configuration)} at an appropriate moment before dumping. - +@node Using ASDF, Defining systems with defsystem, Loading ASDF, Top @chapter Using ASDF @section Loading a system @@ -1490,7 +1529,7 @@ and has many options that prove useful in this context, such as @code{:use-reexport} and @code{:mix-reexport} that allow for ``inheritance'' of symbols being exported. -@node The object model of ASDF, Operations, Defining systems with defsystem, Top +@node The object model of ASDF, Controlling where ASDF searches for systems, Defining systems with defsystem, Top @comment node-name, next, previous, up @chapter The object model of ASDF @@ -1582,7 +1621,7 @@ but instead do something global on the system. * Functions:: @end menu -@node Operations, Predefined operations of ASDF, The object model of ASDF, The object model of ASDF +@node Operations, Components, The object model of ASDF, The object model of ASDF @comment node-name, next, previous, up @section Operations @cindex operation -- GitLab