From 9aba99254a0506204427b484b451657759765d28 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@real-time.com> Date: Mon, 5 Oct 2009 09:43:16 -0500 Subject: [PATCH] Mostly completed the getting started/using ASDF component. --- asdf.texinfo | 154 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 114 insertions(+), 40 deletions(-) diff --git a/asdf.texinfo b/asdf.texinfo index 8dd39531..f879ebd5 100644 --- a/asdf.texinfo +++ b/asdf.texinfo @@ -64,15 +64,15 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. @insertcopying @menu -* Introduction:: +* Introduction:: * Using asdf to load systems:: * Defining systems with defsystem:: * The object model of asdf:: +* Controlling where ASDF saves compiled files:: +* Special variables:: * Error handling:: -* Controlling where ASDF saves compiled files:: -* Special variables:: * Compilation error and warning handling:: -* Miscellaneous additional functionality:: +* Miscellaneous additional functionality:: * Getting the latest version:: * TODO list:: * missing bits in implementation:: @@ -84,11 +84,16 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. @detailmenu --- The Detailed Node Listing --- +Using ASDF + +@c * Installing ASDF:: + Defining systems with defsystem * The defsystem form:: * A more involved example:: * The defsystem grammar:: +* Other code in .asd files:: The object model of asdf @@ -137,23 +142,37 @@ and how to extend ASDF. @node Using asdf to load systems, Defining systems with defsystem, Introduction, Top @comment node-name, next, previous, up -@chapter Using asdf to load systems -@cindex system directory designator +@chapter Using ASDF @vindex *central-registry* +@findex load-system +@findex compile-system +@findex test-system +@cindex system directory designator +@findex operate +@findex oos -This chapter describes how to use asdf to compile and load ready-made -Lisp programs and libraries. +@c @menu +@c * Installing ASDF:: +@c @end menu + +@section Installing ASDF + +Many Lisp implementations include a copy of ASDF. You can +usually load this copy using Common-Lisp's @code{require} +function: -@section Downloading asdf +@kbd{(require 'asdf)} -Some Lisp implementations (such as SBCL and OpenMCL) come with asdf -included already, so you don't need to download it separately.1 -Consult your Lisp system's documentation. If you need to download -asdf and install it by hand, the canonical source is the cCLan CVS -repository at -@url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/}. +Consult your Lisp implementation's documentation for details. If ASDF +doesn't come bundled with your Lisp or if you want to make +sure that you have the most recent version, then you'll want +to download it from the @url{http://common-lisp.net/project/asdf/,asdf-home} website. -@section Setting up asdf +@section Loading ASDF + +If your CL implementation does @emph{not} provide ASDF through the +@code{require} feature, then you need to download ASDF and load it +yourself. The single file @file{asdf.lisp} is all you need to use asdf normally. Once you load it in a running Lisp, you're ready to use asdf. For @@ -162,6 +181,41 @@ start your Lisp implementation, for example by loading it from the startup script or dumping a custom core -- check your Lisp implementation's manual for details. +@section Setting up a system to be loaded + +To compile and load a system, you need to ensure that its +system definition can be found in one of the directories in +@code{*central-registry*}@footnote{It is possible to customize the +system definition file search. That's considered advanced use, and +covered later: search forward for +@code{*system-definition-search-functions*}. @xref{Defining systems +with defsystem}.}. + +There are two ways that you can make a system definition findable +through @code{*central-registry*}. One is to simply insert into +@code{*central-registry*} an entry that specifies the pathname of for +the directory containing the system definition file (a file whose name +is of the form @code{*.asd}). +For example, if we had a +system @var{foo} that is stored in a directory +@file{/home/me/src/foo/}, containing @file{/home/me/src/foo/}, we could +make the foo system asdf-operable by doing @kbd{(push +"/home/me/src/foo/" asdf:*central-registry*)}. + +ASDF will also properly handle the case where the +@code{*central-registry*} points to a directory containing a +@emph{symbolic link} to the system definition file. + +For example, if @code{#p"/home/me/cl/systems/"} (note the trailing +slash) is a member of @code{*central-registry*}, you could set up the +system @var{foo} for loading with asdf with the following +commands at the shell: + +@example +$ cd /home/me/cl/systems/ +$ ln -s ~/src/foo/foo.asd . +@end example + The variable @code{asdf:*central-registry*} is a list of ``system directory designators''@footnote{When we say ``directory'' here, we mean ``designator for a pathname with a supplied DIRECTORY @@ -178,44 +232,64 @@ to a directory to look in. You might want to set or augment asdf:*central-registry*)) @end lisp -@section Setting up a system to be loaded - -To compile and load a system, you need to ensure that a symbolic link to its -system definition is in one of the directories in -@code{*central-registry*}@footnote{It is possible to customize the -system definition file search. That's considered advanced use, and -covered later: search forward for -@code{*system-definition-search-functions*}. @xref{Defining systems -with defsystem}.}. - -For example, if @code{#p"/home/me/cl/systems/"} (note the trailing -slash) is a member of @code{*central-registry*}, you would set up a -system @var{foo} that is stored in a directory -@file{/home/me/src/foo/} for loading with asdf with the following -commands at the shell (this has to be done only once): - -@example -$ cd /home/me/cl/systems/ -$ ln -s ~/src/foo/foo.asd . -@end example - @section Loading a system +@c{FIXME: Add Gary's material about loading system definitions by hand.} +@c{FIXME: Introduce ASDF-binary-locations.} + The system @var{foo} is loaded (and compiled, if necessary) by evaluating the following form in your Lisp implementation: @example -(asdf:operate 'asdf:load-op '@var{foo}) +(asdf:load-system '@var{foo}) @end example +(In older versions of ASDF, you may need to use @code{asdf:oos}, instead.) + Output from asdf and asdf extensions are supposed to be sent to the CL stream @code{*standard-output*}, and so rebinding that stream around calls to @code{asdf:operate} should redirect all output from asdf operations. +ASDF provides three commands for the most common system +operations: @code{load-system}, @code{compile-system} or @code{test-system}. + +Because ASDF is an extensible system for defining +@emph{operations} on @emph{components} also provides a generic +function: @code{operate} (which is usually abbreviated by +@code{oos}). You'll use @code{oos} whenever you want to do something +beyond compiling, loading and testing. + +Reminder: before ASDF can operate on a system, however, it must be able +to find and load that system's definition. + +@section Summary + +To use ASDF: + +@itemize +@item +load @file{asdf.lisp} into your Lisp image, either through +@code{require} or @code{load}. + +@item +make sure ASDF can find system definitions by loading them +yourself or setting up @code{*central-registry*}. + +@item +use @code{operate} (or shorthand @code{oos}) +to tell ASDF what you'd like to do to what systems. +For simple operations, you can use @code{load-system}, @code{compile-system} or @code{test-system} +instead. + +@end itemize + +@section Moving on + That's all you need to know to use asdf to load systems written by others. The rest of this manual deals with writing system -definitions for Lisp software you write yourself. +definitions for Lisp software you write yourself, including how to +extend ASDF to define new operation and component types. @node Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top @comment node-name, next, previous, up @@ -229,7 +303,7 @@ software. * The defsystem form:: * A more involved example:: * The defsystem grammar:: -* Other code in .asd files:: +* Other code in .asd files:: @end menu @node The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem -- GitLab