@@ -143,7 +143,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
...
@@ -143,7 +143,7 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@c -------------------
@c -------------------
@node Introduction, Loading ASDF, Top, Top
@node Introduction, Quick start summary, Top, Top
@comment node-name, next, previous, up
@comment node-name, next, previous, up
@chapter Introduction
@chapter Introduction
@cindex ASDF-related features
@cindex ASDF-related features
...
@@ -197,8 +197,62 @@ which works great and is being actively maintained.
...
@@ -197,8 +197,62 @@ which works great and is being actively maintained.
If you want to download software from version control instead of tarballs,
If you want to download software from version control instead of tarballs,
so you may more easily modify it, we recommend clbuild.
so you may more easily modify it, we recommend clbuild.
@node Quick start summary, Loading ASDF, Introduction, Top
@chapter Quick start summary
@node Loading ASDF, Configuring ASDF, Introduction, Top
@itemize
@item To load an ASDF system:
@itemize
@item
Load ASDF itself into your Lisp image, either through
@code{(require "asdf")} (if it's supplied by your lisp implementation)
or else through
@code{(load "/path/to/asdf.lisp")}. For more details, @xref{Loading ASDF}.
@item
Make sure ASDF can find system definitions
through proper source-registry configuration. For more details,
@xref{Configuring ASDF to find your systems}.
The simplest way is simply to put all your lisp code in subdirectories of
@file{~/.local/share/common-lisp/source/}. Such code will automatically
be found.
@item
Load a system with @code{(asdf:load-system :system)}. @xref{Using ASDF}.
@end itemize
@item To make your own ASDF system:
@itemize
@item
As above, load and configure ASDF.
@item
Make a new directory for your system, @code{my-system/} in a location
where ASDF can find it (@pxref{Configuring ASDF to find your systems}).
@item
Create an ASDF system definition listing the dependencies of your
system, its components, and their interdependencies, and put it in
@file{my-system.asd}. This file must have the same name as your
system. @xref{Defining systems with defsystem}.
@item
Use @code{(asdf:load-system :my-system)} to make sure it's all working
properly. @xref{Using ASDF}.
@end itemize
@end itemize
@node Loading ASDF, Configuring ASDF, Quick start summary, Top
@comment node-name, next, previous, up
@comment node-name, next, previous, up
@chapter Loading ASDF
@chapter Loading ASDF
...
@@ -424,7 +478,7 @@ for example by loading it from the startup script or dumping a custom core
...
@@ -424,7 +478,7 @@ for example by loading it from the startup script or dumping a custom core
For standard use cases, ASDF should work pretty much out of the box. We
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
recommend you skim the sections on configuring ASDF to find your systems
to choose the method of installing Lisp software that works best for
and choose the method of installing Lisp software that works best for
you. Then skip directly to @xref{Using ASDF}; that will probably be
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
enough. You are unlikely to have to worry about the way ASDF stores
object files, and resetting the ASDF configuration is usually only
object files, and resetting the ASDF configuration is usually only
...
@@ -438,7 +492,7 @@ needed in corner cases.
...
@@ -438,7 +492,7 @@ needed in corner cases.
* Resetting the ASDF configuration ::
* Resetting the ASDF configuration ::
@end menu
@end menu
@node Configuring ASDF to find your systems, Configuring ASDF to find your systems --- old style, Configuring ASDF, Configuring ASDF
@node Configuring ASDF to find your systems, Configuring where ASDF stores object files, Configuring ASDF, Configuring ASDF
@section Configuring ASDF to find your systems
@section Configuring ASDF to find your systems
In order to 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
...
@@ -525,6 +579,9 @@ may already have configured system-managed libraries for you.
...
@@ -525,6 +579,9 @@ 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, Configuring ASDF
@node Configuring ASDF to find your systems --- old style, Configuring where ASDF stores object files, Configuring ASDF to find your systems, Configuring ASDF
@c FIXME: this section should be moved elsewhere. The novice user
@c should not be burdened with it. [2014/02/27:rpg]
@section Configuring ASDF to find your systems --- old style
@section Configuring ASDF to find your systems --- old style
The old way to configure ASDF to find your systems is by
The old way to configure ASDF to find your systems is by
...
@@ -540,65 +597,67 @@ your Common Lisp software system.
...
@@ -540,65 +597,67 @@ your Common Lisp software system.
The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
The @code{asdf:*central-registry*} is empty by default in ASDF 2 or ASDF 3,
but is still supported for compatibility with ASDF 1.
but is still supported for compatibility with ASDF 1.
When used, it takes precedence over the above source-registry@footnote{
When used, it takes precedence over the above source-registry.@footnote{
It is possible to further customize
It is possible to further customize
the system definition file search.
the system definition file search.
That's considered advanced use, and covered later:
That's considered advanced use, and covered later:
search forward for
search forward for
@code{*system-definition-search-functions*}.
@code{*system-definition-search-functions*}.
@xref{Defining systems with defsystem}.}.
@xref{Defining systems with defsystem}.}
For instance, if you wanted ASDF to find the @file{.asd} file
For example, let's say you want ASDF to find the @file{.asd} file
@file{/home/me/src/foo/foo.asd} your initialization script
@file{/home/me/src/foo/foo.asd}.
could after it loads ASDF with @code{(require "asdf")}
In your lisp initialization file, you could have the following:
Note the trailing slash: when searching for a system,
Note the trailing slash: when searching for a system,
ASDF will evaluate each entry of the central registry
ASDF will evaluate each entry of the central registry
and coerce the result to a pathname@footnote{
and coerce the result to a pathname.@footnote{
ASDF will indeed call @code{eval} on each entry.
ASDF will indeed call @code{eval} on each entry.
It will also skip entries that evaluate to @code{nil}.
It will skip entries that evaluate to @code{nil}.
Strings and pathname objects are self-evaluating,
Strings and pathname objects are self-evaluating,
in which case the @code{eval} step does nothing;
in which case the @code{eval} step does nothing;
but you may push arbitrary SEXP onto the central registry,
but you may push arbitrary s-expressions onto the central registry.
that will be evaluated to compute e.g. things that depend
These s-expressions may be evaluated to compute context-dependent
entries, e.g. things that depend
on the value of shell variables or the identity of the user.
on the value of shell variables or the identity of the user.
The variable @code{asdf:*central-registry*} is thus a list of
The variable @code{asdf:*central-registry*} is thus a list of
``system directory designators''.
``system directory designators''.
A @dfn{system directory designator} is a form
A @dfn{system directory designator} is a form
which will be evaluated whenever a system is to be found,
which will be evaluated whenever a system is to be found,
and must evaluate to a directory to look in.
and must evaluate to a directory to look in (or @code{NIL}).
By ``directory'' here, we mean
By ``directory'', we mean
``designator for a pathname with a supplied DIRECTORY component''.
``designator for a pathname with a non-empty DIRECTORY component''.
}
}
at which point the presence of the trailing directory name separator
The trailing directory name separator
is necessary to tell Lisp that you're discussing a directory
is necessary to tell Lisp that you're discussing a directory
rather than a file.
rather than a file. If you leave it out, ASDF is likely to look in
@code{/home/me/src/} instead of @code{/home/me/src/foo/} as you
intended, and fail to find your system definition.
Typically, however, there are a lot of @file{.asd} files, and
Typically there are a lot of @file{.asd} files, and
a common idiom was to have to put
a common idiom was to put
a bunch of @emph{symbolic links} to @file{.asd} files
@emph{symbolic links} to all of one's @file{.asd} files
in a common directory
in a common directory
and push @emph{that} directory (the ``link farm'')
and push @emph{that} directory (the ``link farm'')
to the
onto
@code{asdf:*central-registry*}
@code{asdf:*central-registry*},
instead of pushing each of the many involved directories
instead of pushing each individual system directory.
to the @code{asdf:*central-registry*}.
ASDF knows how to follow such @emph{symlinks}
ASDF knows to follow @emph{symlinks}
to the actual file location when resolving the paths of system components
to the actual location of the systems.@footnote{
(on Windows, you can use Windows shortcuts instead of POSIX symlinks;
On Windows, you can use Windows shortcuts instead of POSIX symlinks.
if you try aliases under MacOS, we are curious to hear about your experience).
if you try aliases under MacOS, we are curious to hear about your experience.}
For example, if @code{#p"/home/me/cl/systems/"} (note the trailing slash)
For example, if @code{#p"/home/me/cl/systems/"}
is a member of @code{*central-registry*}, you could set up the
is an element of @code{*central-registry*}, you could set up the
system @var{foo} for loading with asdf with the following
system @var{foo} as follows:
commands at the shell:
@example
@example
$ cd /home/me/cl/systems/
$ cd /home/me/cl/systems/
...
@@ -610,7 +669,7 @@ but it is supported for old users, and for users who want to programmatically
...
@@ -610,7 +669,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.
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, Configuring ASDF
@node Configuring where ASDF stores object files, , Configuring ASDF to find your systems, Configuring ASDF
@section Configuring where ASDF stores object files
@section Configuring where ASDF stores object files
@findex clear-output-translations
@findex clear-output-translations
...
@@ -618,79 +677,84 @@ ASDF lets you configure where object files will be stored.
...
@@ -618,79 +677,84 @@ ASDF lets you configure where object files will be stored.
Sensible defaults are provided and
Sensible defaults are provided and
you shouldn't normally have to worry about it.
you shouldn't normally have to worry about it.
This allows the same source code repository may be shared
This allows the same source code repository to be shared
between several versions of several Common Lisp implementations,
between several versions of several Common Lisp implementations,
between several users using different compilation options
between several users using different compilation options,
and without write privileges on shared source directories, etc.
with users who lack write privileges on shared source directories, etc.
This also allows to keep source directories uncluttered
This also keeps source directories from being cluttered
by plenty of object files.
with object/fasl files.
Starting with ASDF 2, the @code{asdf-output-translations} facility
Starting with ASDF 2, the @code{asdf-output-translations} facility
was added to ASDF itself, that controls where object files will be stored.
was added to ASDF itself. This facility controls where object files will be stored.
This facility is fully described in a chapter of this manual,
This facility is fully described in a chapter of this manual,
@ref{Controlling where ASDF saves compiled files}.
@ref{Controlling where ASDF saves compiled files}.
The simplest way to add a translation to your search path,
@c FIXME: possibly this should be moved elsewhere. It's redundant here,
say from @file{/foo/bar/baz/quux/}
@c and makes this section of the manual too long and daunting for the
to @file{/where/i/want/my/fasls/}
@c new user. [2014/02/27:rpg]
is to create the directory
@c The simplest way to add a translation to your search path,