Skip to content
Snippets Groups Projects
asdf.texinfo 250 KiB
Newer Older
@item compile all its files
@item load the files into a running lisp environment
@item copy its source files somewhere else
@end itemize

Operations can be invoked directly, or examined
to see what their effects would be without performing them.
There are a bunch of methods specialised on operation and component type
that actually do the grunt work.
Operations are invoked on systems via @code{operate} (@pxref{operate}).
ASDF contains a number of pre-defined @t{operation} classes for common,
and even fairly uncommon tasks that you might want to do with it.
In addition, ASDF contains ``abstract'' @t{operation} classes that
programmers can use as building blocks to define ASDF extensions.  We
discuss these in turn below.

@c The operation object contains whatever state is relevant for this purpose
@c (perhaps a list of visited nodes, for example)
@c but primarily is a nice thing to specialise operation methods on
@c and easier than having them all be @code{EQL} methods.

@menu
* Predefined operations of ASDF::
* Creating new operations::
@end menu

Operations are invoked on systems via @code{operate}.
@deffn {Generic function} @code{operate} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @code{force} @code{force-not} @code{verbose} @AallowOtherKeys
@deffnx {Generic function} @code{oos} @var{operation} @var{component} @Arest{} @var{initargs} @Akey{} @AallowOtherKeys{}
@code{operate} invokes @var{operation} on @var{system}.
@code{oos} is a synonym for @code{operate} (it stands for operate-on-system).
@var{operation} is a symbol that is passed,
along with the supplied @var{initargs},
to @code{make-operation} (which will call @code{make-instance})
to create the operation object.
@var{component} is a component designator,
usually a string or symbol that designates a system,
sometimes a list of strings or symbols that designate a subcomponent of a system.
The @var{initargs} are passed to the @code{make-instance} call
when creating the operation object.
@c We probably want to deprecate that, because
@c (1) there is a mix of flags for operate, for the operation-class, for the plan-class, etc.
@c (2) flags to operations have never been well-supported, anyway.
@c The future solution probably involves having an explicit :operation-options keyword or some such
@c (if operation options are not wholly eliminated), a separate :plan-options, etc.
Note that dependencies may cause the operation
to invoke other operations on the system or its components:
the new operations will be created
with the same @var{initargs} as the original one.
If @var{force} is @code{:all}, then all systems
are forced to be recompiled even if not modified since last compilation.
If @var{force} is @code{t}, then only the system being loaded
is forced to be recompiled even if not modified since last compilation,
but other systems are not affected.
If @var{force} is a list, then it specifies a list of systems that
are forced to be recompiled even if not modified since last compilation.
If @var{force-not} is @code{:all}, then all systems
are forced not to be recompiled even if modified since last compilation.
If @var{force-not} is @code{t}, then all systems but the system being loaded
are forced not to be recompiled even if modified since last compilation
(note: this was changed in ASDF 3.1.2).
If @var{force-not} is a list, then it specifies a list of systems that
are forced not to be recompiled even if modified since last compilation.
@findex register-immutable-system
@cindex immutable systems
Both @var{force} and @var{force-not} apply to systems that are dependencies and were already compiled.
@var{force-not} takes precedences over @var{force},
as it should, really, but unhappily only since ASDF 3.1.2.
Moreover, systems which have been registered as immutable by @code{register-immutable-system} (since ASDF 3.1.5)
are always considered @var{forced-not}, and even their @file{.asd} are not refreshed from the filesystem.
@xref{Miscellaneous Functions}.
@findex traverse
To see what @code{operate} would do, you can use:
@example
(asdf:traverse operation-class system-name)
@end example

@node Predefined operations of ASDF, Creating new operations, Operations, Operations
@comment  node-name,  next,  previous,  up
@subsection Predefined operations of ASDF
@c FIXME: All these deffn's should be replaced with deftyp.  Also, we
@c should set up an appropriate index.
All the operations described in this section are in the @code{asdf} package.
They are invoked via the @code{operate} generic function.
(asdf:operate 'asdf:@var{operation-name} :@var{system-name} @{@var{operation-options ...}@})
This operation compiles the specified component.
A @code{cl-source-file} will be @code{compile-file}'d.
All the children and dependencies of a system or module
will be recursively compiled by @code{compile-op}.

@code{compile-op} depends on @code{prepare-op} which
itself depends on a @code{load-op} of all of a component's dependencies,
as well as of its parent's dependencies.
When @code{operate} is called on @code{compile-op},
all these dependencies will be loaded as well as compiled;
yet, some parts of the system main remain unloaded,
because nothing depends on them.
Use @code{load-op} to load a system.
This operation loads the compiled code for a specified component.
A @code{cl-source-file} will have its compiled fasl @code{load}ed,
which fasl is the output of @code{compile-op} that @code{load-op} depends on.
@code{load-op} will recursively load all the children of a system or module.

@code{load-op} also depends on @code{prepare-op} which
itself depends on a @code{load-op} of all of a component's dependencies,
as well as of its parent's dependencies.
This operation ensures that the dependencies of a component
and its recursive parents are loaded (as per @code{load-op}),
as a prerequisite before @code{compile-op} and @code{load-op} operations
may be performed on a given component.
@deffn Operation @code{load-source-op}, @code{prepare-source-op}

@code{load-source-op} will load the source for the files in a module
rather than the compiled fasl output.
It has a @code{prepare-source-op} analog to @code{prepare-op},
that ensures the dependencies are themselves loaded via @code{load-source-op}.

@deffn Operation @code{test-op}

This operation will perform some tests on the module.
The default method will do nothing.
The default dependency is to require
@code{load-op} to be performed on the module first.
Its @code{operation-done-p} method returns @code{nil},
which means that the operation is @emph{never} done
we assume that if you invoke the @code{test-op},
you want to test the system, even if you have already done so.

The results of this operation are not defined by ASDF.
It has proven difficult to define how the test operation
should signal its results to the user
in a way that is compatible with all of the various test libraries
and test techniques in use in the community, and
given the fact that ASDF operations do not return a value indicating
success or failure.
For those willing to go to the effort, we suggest defining conditions to
signal when a @code{test-op} fails, and storing in those conditions
information that describes which tests fail.

People typically define a separate test @emph{system} to hold the tests.
Doing this avoids unnecessarily adding a test framework as a dependency
on a library.  For example, one might have
  :in-order-to ((test-op (test-op "foo/test")))
 ...)

(defsystem "foo/test"
  :depends-on ("foo" "fiveam") ; fiveam is a test framework library
Then one defines @code{perform} methods on
@code{test-op} such as the following:
@lisp
(defsystem "foo/test"
  :depends-on ("foo" "fiveam") ; fiveam is a test framework library
  :perform (test-op (o s)
                    (uiop:symbol-call :fiveam '#:run!
                       (uiop:find-symbol* '#:foo-test-suite
Robert P. Goldman's avatar
Robert P. Goldman committed
@end deffn

@deffn Operation @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op}, @code{lib-op}, @code{monolithic-lib-op}, @code{dll-op}, @code{monolithic-dll-op}, @code{image-op}, @code{program-op}

These are ``bundle'' operations, that can create a single-file ``bundle''
for all the contents of each system in an application,
or for the entire application.

@code{compile-bundle-op} will create a single fasl file for each of the systems needed,
grouping all its many fasls in one,
so you can deliver each system as a single fasl
@code{monolithic-compile-bundle-op} will create a single fasl file for the target system
and all its dependencies,
so you can deliver your entire application as a single fasl.
@code{load-bundle-op} will load the output of @code{compile-bundle-op}.
Note that if it the output is not up-to-date,
@code{compile-bundle-op} may load the intermediate fasls as a side-effect.
Bundling fasls together matters a lot on ECL,
where the dynamic linking involved in loading tens of individual fasls
can be noticeably more expensive than loading a single one.

NB: @code{compile-bundle-op}, @code{monolithic-compile-bundle-op}, @code{load-bundle-op}, @code{monolithic-load-bundle-op}, @code{deliver-asd-op}, @code{monolithic-deliver-asd-op} were respectively called
@code{fasl-op}, @code{monolithic-fasl-op}, @code{load-fasl-op}, @code{monolithic-load-fasl-op}, @code{binary-op}, @code{monolithic-binary-op} before ASDF 3.1.
The old names still exist for backward compatibility,
though they poorly label what is going on.
Once you have created a fasl with @code{compile-bundle-op},
you can use @code{precompiled-system} to deliver it in a way
that is compatible with clients having dependencies on your system,
whether it is distributed as source or as a single binary;
the @file{.asd} file to be delivered with the fasl will look like this:
@example
(defsystem :mysystem :class :precompiled-system
  :fasl (some expression that will evaluate to a pathname))
@end example
Or you can use @code{deliver-asd-op} to let ASDF create such a system for you
as well as the @code{compile-bundle-op} output,
or @code{monolithic-deliver-asd-op}.
This allows you to deliver code for your systems or applications
as a single file.
Of course, if you want to test the result in the current image,
@emph{before} you try to use any newly created @file{.asd} files,
you should not forget to @code{(asdf:clear-configuration)}
or at least @code{(asdf:clear-source-registry)},
so it re-populates the source-registry from the filesystem.

The @code{program-op} operation will create an executable program
from the specified system and its dependencies.
You can use UIOP for its pre-image-dump hooks, its post-image-restore hooks,
and its access to command-line arguments.
And you can specify an entry point @code{my-app:main}
by specifying in your @code{defsystem}
the option @code{:entry-point "my-app:main"}.
Depending on your implementation,
running @code{(asdf:operate 'asdf:program-op :my-app)}
may quit the current Lisp image upon completion.
See the example in
@file{test/hello-world-example.asd} and @file{test/hello.lisp},
as built and tested by
@file{test/test-program.script} and @file{test/make-hello-world.lisp}.
@code{image-op} will dump an image that may not be standalone
and does not start its own function,
but follows the usual execution convention of the underlying Lisp,
just with more code pre-loaded,
for use as an intermediate build result or with a wrapper invocation script.

There is also @code{lib-op}
for building a linkable @file{.a} file (Windows: @file{.lib})
from all linkable object dependencies (FFI files, and on ECL, Lisp files too),
and its monolithic equivalent @code{monolithic-lib-op}.
And there is also @code{dll-op}
(respectively its monolithic equivalent @code{monolithic-lib-op})
for building a linkable @file{.so} file
(Windows: @file{.dll}, MacOS X: @file{.dynlib})
to create a single dynamic library
for all the extra FFI code to be linked into each of your systems
(respectively your entire application).

All these ``bundle'' operations are available since ASDF 3
on all actively supported Lisp implementations,
but may be unavailable on unmaintained legacy implementations.
This functionality was previously available for select implementations,
as part of a separate system @code{asdf-bundle},
itself descended from the ECL-only @code{asdf-ecl}.

The pathname of the output of bundle operations
is subject to output-translation as usual,
unless the operation is equal to
the @code{:build-operation} argument to @code{defsystem}.
This behaviour is not very satisfactory and may change in the future.
Maybe you have suggestions on how to better configure it?
@deffn Operation @code{concatenate-source-op}, @code{monolithic-concatenate-source-op}, @code{load-concatenated-source-op}, @code{compile-concatenated-source-op}, @code{load-compiled-concatenated-source-op}, @code{monolithic-load-concatenated-source-op}, @code{monolithic-compile-concatenated-source-op}, @code{monolithic-load-compiled-concatenated-source-op}

These operations, as their respective names indicate,
will concatenate all the @code{cl-source-file} source files in a system
(or in a system and all its dependencies, if monolithic),
in the order defined by dependencies,
then load the result, or compile and then load the result.

These operations are useful to deliver a system or application
as a single source file,
and for testing that said file loads properly, or compiles and then loads properly.
ASDF itself is delivered as a single source file this way,
using @code{monolithic-concatenate-source-op},
prepending a prelude and the @code{uiop} library
before the @code{asdf/defsystem} system itself.
@end deffn

@node  Creating new operations,  , Predefined operations of ASDF, Operations
@comment  node-name,  next,  previous,  up
@subsection Creating new operations

ASDF was designed to be extensible in an object-oriented fashion.
To teach ASDF new tricks, a programmer can implement the behaviour he wants
by creating a subclass of @code{operation}.
ASDF's pre-defined operations are in no way ``privileged'',
but it is requested that developers never use the @code{asdf} package
for operations they develop themselves.
The rationale for this rule is that we don't want to establish a
``global asdf operation name registry'',
but also want to avoid name clashes.
Your operation @emph{must} usually provide methods
for one or more of the following generic functions:
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex perform
@item @code{perform}
Unless your operation, like @code{prepare-op},
is for dependency propagation only,
the most important function for which to define a method
is usually @code{perform},
which will be called to perform the operation on a specified component,
after all dependencies have been performed.

The @code{perform} method must call @code{input-files} and @code{output-files} (see below)
to locate its inputs and outputs,
because the user is allowed to override the method
or tweak the output-translation mechanism.
Perform should only use the primary value returned by @code{output-files}.
If one and only one output file is expected,
it can call @code{output-file} that checks that this is the case
and returns the first and only list element.
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex output-files
@item @code{output-files}
If your perform method has any output,
you must define a method for this function.
for ASDF to determine where the outputs of performing operation lie.

Your method may return two values, a list of pathnames, and a boolean.
If the boolean is @code{nil} (or you fail to return multiple values),
then enclosing @code{:around} methods may translate these pathnames,
e.g. to ensure object files are somehow stored
in some implementation-dependent cache.
If the boolean is @code{t} then the pathnames are marked
not be translated by the enclosing @code{:around} method.
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex component-depends-on
@item @code{component-depends-on}
If the action of performing the operation on a component has dependencies,
you must define a method on @code{component-depends-on}.

Your method will take as specialized arguments
an operation and a component which together identify an action,
and return a list of entries describing actions that this action depends on.
The format of entries is described below.

It is @emph{strongly} advised that
you should always append the results of @code{(call-next-method)}
to the results of your method,
or ``interesting'' failures will likely occur,
unless you're a true specialist of ASDF internals.
It is unhappily too late to compatibly use the @code{append} method combination,
but conceptually that's the protocol that is being manually implemented.

Each entry returned by @code{component-depends-on} is itself a list.

The first element of an entry is an operation designator:
either an operation object designating itself, or
a symbol that names an operation class
(that ASDF will instantiate using @code{make-operation}).
For instance, @code{load-op}, @code{compile-op} and @code{prepare-op}
are common such names, denoting the respective operations.

@c FIXME COERCE-NAME is referenced, but not defined.
@findex coerce-name
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex find-component
The rest of each entry is a list of component designators:
either a component object designating itself,
or an identifier to be used with @code{find-component}.
@code{find-component} will be called with the current component's parent as parent,
and the identifier as second argument.
The identifier is typically a string,
a symbol (to be downcased as per @code{coerce-name}),
or a list of strings or symbols.
In particular, the empty list @code{nil} denotes the parent itself.

@end itemize

An operation @emph{may} provide methods for the following generic functions:

@itemize

@item @code{input-files}
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex input-files
A method for this function is often not needed,
since ASDF has a pretty clever default @code{input-files} mechanism.
You only need create a method if there are multiple ultimate input
files.
Most operations inherit from @code{selfward-operation}, which
appropriately sets the input-files to include the source file itself.

@c FIXME: Add documentation of built-in operation types.

@defun input-files operation component
Return a list of pathnames that represent the input to @var{operation}
performed on @var{component}.
@end defun
Robert P. Goldman's avatar
Robert P. Goldman committed
@findex operation-done-p
You only need to define a method on that function
if you can detect conditions that invalidate previous runs of the operation,
even though no filesystem timestamp has changed,
in which case you return @code{nil} (the default is @code{t}).
For instance, the method for @code{test-op} always returns @code{nil},
so that tests are always run afresh.
Of course, the @code{test-op} for your system could depend
on a deterministically repeatable @code{test-report-op},
and just read the results from the report files,
in which case you could have this method return @code{t}.
Operations that print output should send that output to the standard
CL stream @code{*standard-output*}, as the Lisp compiler and loader do.

@node Components, Dependencies, Operations, The object model of ASDF
@comment  node-name,  next,  previous,  up
@section Components
@cindex component
@cindex system
@cindex system designator
@vindex *system-definition-search-functions*

A @code{component} represents an individual source file or a group of source files,
and the things that get transformed into.
A @code{system} is a component at the top level of the component hierarchy,
that can be found via @code{find-system}.
A @code{source-file} is a component representing a single source-file
and the successive output files into which it is transformed.
A @code{module} is an intermediate component itself grouping several other components,
themselves source-files or further modules.

A @dfn{system designator} is a system itself,
or a string or symbol that behaves just like any other component name
(including with regard to the case conversion rules for component names).
A @dfn{component designator}, relative to a base component,
is either a component itself,
or a string or symbol,
or a list of designators.
@defun find-system system-designator @Aoptional{} (error-p t)
Given a system designator, @code{find-system} finds and returns a system.
If no system is found, an error of type
@code{missing-component} is thrown,
or @code{nil} is returned if @code{error-p} is false.

To find and update systems, @code{find-system} funcalls each element
in the @code{*system-definition-search-functions*} list,
expecting a pathname to be returned, or a system object,
from which a pathname may be extracted, and that will be registered.
The resulting pathname (if any) is loaded
if one of the following conditions is true:
@item
there is no system of that name in memory
@item
the pathname is different from that which was previously loaded
@item
the file's @code{last-modified} time exceeds the @code{last-modified} time
of the system in memory
Robert P. Goldman's avatar
Robert P. Goldman committed
@cindex ASDF-USER package
When system definitions are loaded from @file{.asd} files,
they are implicitly loaded into the @code{ASDF-USER} package,
which uses @code{ASDF}, @code{UIOP} and @code{UIOP/COMMON-LISP}@footnote{
Note that between releases 2.27 and 3.0.3, only @code{UIOP/PACKAGE},
not all of @code{UIOP}, was used; if you want your code to work
with releases earlier than 3.1.2, you may have to explicitly define a package
that uses @code{UIOP}, or use proper package prefix to your symbols, as in
@code{uiop:version<}.}
Programmers who do anything non-trivial in a @file{.asd} file,
such as defining new variables, functions or classes,
should include @code{defpackage} and @code{in-package} forms in this file,
so they will not overwrite each others' extensions.
Such forms might also help the files behave identically
if loaded manually with @code{cl:load} for development or debugging,
though we recommend you use the function @code{asdf::load-asd} instead,
which the @code{slime-asdf} contrib knows about.

The default value of @code{*system-definition-search-functions*}
The first function looks in each of the directories given
by evaluating members of @code{*central-registry*}
for a file whose name is the name of the system and whose type is @file{asd};
the first such file is returned,
whether or not it turns out to actually define the appropriate system.
The second function does something similar,
for the directories specified in the @code{source-registry},
but searches the filesystem only once and caches its results.
The third function makes the @code{package-inferred-system} extension work,
@pxref{The package-inferred-system extension}.

Because of the way these search functions are defined,
you should put the definition for a system
@var{foo} in a file named @file{foo.asd},
in a directory that is
in the central registry or
which can be found using the
source registry configuration.

@c FIXME: Move this discussion to the system definition grammar, or somewhere else.
@anchor{System names}
@cindex System names
@cindex Primary system name
@findex primary-system-name
It is often useful to define multiple systems in a same file,
but ASDF can only locate a system's definition file based on the system
name.
For this reason,
ASDF 3's system search algorithm has been extended to
allow a file @file{foo.asd} to contain
secondary systems named @var{foo/bar}, @var{foo/baz}, @var{foo/quux}, etc.,
in addition to the primary system named @var{foo}.
The first component of a system name,
separated by the slash character, @code{/},
is called the primary name of a system.
The primary name may be
extracted by function @code{asdf::primary-system-name};
when ASDF 3 is told to find a system whose name has a slash,
it will first attempt to load the corresponding primary system,
and will thus see any such definitions, and/or any
definition of a @code{package-inferred-system}.@footnote{
ASDF 2.26 and earlier versions
do not support this primary system name convention.
With these versions of ASDF
you must explicitly load @file{foo.asd}
before you can use system @var{foo/bar} defined therein,
e.g. using @code{(asdf:find-system "foo")}.
We do not support ASDF 2, and recommend that you should upgrade to ASDF 3.
}
If your file @file{foo.asd} also defines systems
that do not follow this convention, e.g., a system named @var{foo-test},
ASDF will not be able to automatically locate a definition for these systems,
and will only see their definition
if you explicitly find or load the primary system
using e.g. @code{(asdf:find-system "foo")} before you try to use them.
We strongly recommend against this practice,
though it is currently supported for backward compatibility.

@defun primary-system-name name

Internal (not exported) function, @code{asdf::primary-system-name}.
Returns the primary system name (the portion before
the slash, @code{/}, in a secondary system name) from @var{name}.

@end defun

Robert P. Goldman's avatar
Robert P. Goldman committed
@defun locate-system name

This function should typically @emph{not} be invoked directly.  It is
exported as part of the API only for programmers who wish to provide
their own @code{*system-definition-search-functions*}.

Given a system @var{name} designator,
try to locate where to load the system definition from.
@c (This does not include the loading of the system definition,
@c which is done by @code{find-system},
@c or the loading of the system itself, which is done by @code{load-system};
@c however, for systems the definition of which has already been loaded,
@c @code{locate-system} may return an object of class @code{system}.)
Robert P. Goldman's avatar
Robert P. Goldman committed
Returns five values: @var{foundp}, @var{found-system}, @var{pathname},
@var{previous}, and @var{previous-time}.
@var{foundp} is true when a system was found,
either a new as yet unregistered one, or a previously registered one.
The @var{found-system} return value
will be a @code{system} object, if a system definition is found in your
source registry.
@c This system may be registered (by @code{register-system}) or may not, if
@c it's preloaded code.  Fare writes:
@c In the case of preloaded code, as for "asdf", "uiop", etc.,
@c themselves, the system objects are not registered until after they are
@c initially located by sysdef-preloaded-system-search as a fallback when
@c no source code was found.
The system definition will @emph{not} be
loaded if it hasn't been loaded already.
Robert P. Goldman's avatar
Robert P. Goldman committed
@var{pathname} when not null is a path from which to load the system,
either associated with @var{found-system}, or with the @var{previous} system.
If @var{previous} is not null, it will be a @emph{previously loaded}
@code{system} object of the same name (note that the system
@emph{definition} is previously-loaded: the system itself may or may not be).
@var{previous-time} when not null is
the timestamp of the previous system definition file, at the
time when the @var{previous} system definition was loaded.

For example, if your current registry has @file{foo.asd} in
@file{/current/path/to/foo.asd},
but system @code{foo} was previously loaded from @file{/previous/path/to/foo.asd}
then @var{locate-system} will return the following values:
@enumerate
@item
@var{foundp} will be @code{T},
@item
@var{found-system} will be @code{NIL},
@item
@var{pathname} will be @code{#p"/current/path/to/foo.asd"},
@item
@var{previous} will be an object of type @code{SYSTEM} with
@code{system-source-file} slot value of
@code{#p"/previous/path/to/foo.asd"}
@item
@var{previous-time} will be the timestamp of
@code{#p"/previous/path/to/foo.asd"} at the time it was loaded.
@end enumerate
Robert P. Goldman's avatar
Robert P. Goldman committed
@end defun

@defun find-component base path

Given a @var{base} component (or designator for such),
and a @var{path}, find the component designated by the @var{path}
starting from the @var{base}.

If @var{path} is a component object, it designates itself,
independently from the base.

@findex coerce-name
If @var{path} is a string, or symbol denoting a string via @code{coerce-name},
then @var{base} is resolved to a component object,
which must be a system or module,
and the designated component is the child named by the @var{path}.

If @var{path} is a @code{cons} cell,
@code{find-component} with the base and the @code{car} of the @var{path},
and the resulting object is used as the base for a tail call
to @code{find-component} with the @code{car} of the @var{path}.

If @var{base} is a component object, it designates itself.

If @var{base} is null, then @var{path} is used as the base, with @code{nil} as the path.

If @var{base} is a string, or symbol denoting a string via @code{coerce-name},
it designates a system as per @code{find-system}.

If @var{base} is a @code{cons} cell, it designates the component found by
@code{find-component} with its @code{car} as base and @code{cdr} as path.
@end defun

* Common attributes of components::
* Pre-defined subclasses of component::
* Creating new component types::
@end menu

@node  Common attributes of components, Pre-defined subclasses of component, Components, Components
@comment  node-name,  next,  previous,  up
@subsection Common attributes of components

All components, regardless of type, have the following attributes.
All attributes except @code{name} are optional.

@subsubsection Name
A component name is a string or a symbol.
If a symbol, its name is taken and lowercased.  This translation is
performed by the exported function @code{coerce-name}.
Unless overridden by a @code{:pathname} attribute,
the name will be interpreted as a pathname specifier according
to a Unix-style syntax.
@xref{The defsystem grammar,,Pathname specifiers}.

@subsubsection Version identifier
@findex version-satisfies
@cindex :version
This optional attribute specifies a version for the current component.
The version should typically be a string of integers separated by dots,
for example @samp{1.0.11}.
For more information on version specifiers, see @ref{The defsystem grammar}.
A version may then be queried by the generic function @code{version-satisfies},
to see if @code{:version} dependencies are satisfied,
and when specifying dependencies, a constraint of minimal version to satisfy
can be specified using e.g. @code{(:version "mydepname" "1.0.11")}.
Note that in the wild, we typically see version numbering
only on components of type @code{system}.
Presumably it is much less useful within a given system,
wherein the library author is responsible to keep the various files in synch.
@subsubsection Required features
Traditionally defsystem users have used @code{#+} reader conditionals
to include or exclude specific per-implementation files.
For example, CFFI, the portable C foreign function interface contained
lines like:
@lisp
     #+sbcl       (:file "cffi-sbcl")
@end lisp
An unfortunate side effect of this approach is that no single
implementation can read the entire system.
This causes problems if, for example, one wished to design an @code{archive-op}
that would create an archive file containing all the sources, since
for example the file @code{cffi-sbcl.lisp} above would be invisible when
running the @code{archive-op} on any implementation other than SBCL.

Starting with ASDF 3,
components may therefore have an @code{:if-feature} option.
The value of this option should be
a feature expression using the same syntax as @code{#+} does.
If that feature expression evaluates to false, any reference to the component will be ignored
during compilation, loading and/or linking.
Since the expression is read by the normal reader,
you must explicitly prefix your symbols with @code{:} so they be read as keywords;
this is as contrasted with the @code{#+} syntax
that implicitly reads symbols in the keyword package by default.

For instance, @code{:if-feature (:and :x86 (:or :sbcl :cmu :scl))} specifies that
the given component is only to be compiled and loaded
when the implementation is SBCL, CMUCL or Scieneer CL on an x86 machine.
You cannot write it as @code{:if-feature (and x86 (or sbcl cmu scl))}
since the symbols would not be read as keywords.

@xref{if-feature-option}.

@subsubsection Dependencies

This attribute specifies dependencies of the component on its siblings.
It is optional but often necessary.

There is an excitingly complicated relationship between the initarg
and the method that you use to ask about dependencies

Dependencies are between (operation component) pairs.
In your initargs for the component, you can say

@lisp
:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
              (load-op (load-op "foo")))
@end lisp

This means the following things:
@itemize
@item
before performing compile-op on this component, we must perform
load-op on @var{a} and @var{b}, and compile-op on @var{c},
@item
before performing @code{load-op}, we have to load @var{foo}
@end itemize

The syntax is approximately

@verbatim
(this-op @{(other-op required-components)@}+)
simple-component-name := string
                      |  symbol

required-components := simple-component-name
                     | (required-components required-components)

component-name := simple-component-name
                | (:version simple-component-name minimum-version-object)
This is on a par with what ACL defsystem does.
mk-defsystem is less general: it has an implied dependency
  for all source file x, (load x) depends on (compile x)
@end verbatim

and using a @code{:depends-on} argument to say that @var{b} depends on
@var{a} @emph{actually} means that

@verbatim
  (compile b) depends on (load a)
@end verbatim

This is insufficient for e.g. the McCLIM system, which requires that
all the files are loaded before any of them can be compiled ]

End side note

In ASDF, the dependency information for a given component and operation
can be queried using @code{(component-depends-on operation component)},
which returns a list

@lisp
((load-op "a") (load-op "b") (compile-op "c") ...)
@end lisp

@code{component-depends-on} can be subclassed for more specific
component/operation types: these need to @code{(call-next-method)}
and append the answer to their dependency, unless
they have a good reason for completely overriding the default dependencies.
Robert P. Goldman's avatar
Robert P. Goldman committed
If it weren't for CLISP, we'd be using @code{LIST} method
combination to do this transparently.
But, we need to support CLISP.
If you have the time for some CLISP hacking,
I'm sure they'd welcome your fixes.
@c Doesn't CLISP now support LIST method combination?
A minimal version can be specified for a component you depend on
(typically another system), by specifying @code{(:version "other-system" "1.2.3")}
instead of simply @code{"other-system"} as the dependency.
See the discussion of the semantics of @code{:version}
in the defsystem grammar.

@c FIXME: Should have cross-reference to "Version specifiers" in the
@c defsystem grammar, but the cross-referencing is so broken by
@c insufficient node breakdown that I have not put one in.


@subsubsection pathname

This attribute is optional and if absent (which is the usual case),
the component name will be used.
@xref{The defsystem grammar,,Pathname specifiers},
for an explanation of how this attribute is interpreted.
Note that the @code{defsystem} macro (used to create a ``top-level'' system)
does additional processing to set the filesystem location of
the top component in that system.
This is detailed elsewhere. @xref{Defining systems with defsystem}.
To find the CL pathname corresponding to a component, use

@defun component-pathname component
Returns the pathname corresponding to @var{component}.  For components
such as source files, this will be a filename pathname.  For example:

@lisp
CL-USER> (asdf:component-pathname (asdf:find-system "xmls"))
#P"/Users/rpg/lisp/xmls/"
@end lisp

and

@lisp
CL-USER> (asdf:component-pathname
           (asdf:find-component
              (asdf:find-system "xmls") "xmls"))
#P"/Users/rpg/lisp/xmls/xmls.lisp"
@end lisp
@end defun




@subsubsection properties

This attribute is optional.

Packaging systems often require information about files or systems
in addition to that specified by ASDF's pre-defined component attributes.
Programs that create vendor packages out of ASDF systems therefore
have to create ``placeholder'' information to satisfy these systems.
Sometimes the creator of an ASDF system may know the additional
information and wish to provide it directly.

@code{(component-property component property-name)} and
associated @code{setf} method will allow
the programmatic update of this information.
Property names are compared as if by @code{EQL},
so use symbols or keywords or something.
* Pre-defined subclasses of component::
* Creating new component types::
@end menu

@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
@comment  node-name,  next,  previous,  up
@subsection Pre-defined subclasses of component

@deffn Component source-file

A source file is any file that the system does not know how to
generate from other components of the system.
Note that this is not necessarily the same thing as
``a file containing data that is typically fed to a compiler''.
If a file is generated by some pre-processor stage
(e.g. a @file{.h} file from @file{.h.in} by autoconf)
then it is not, by this definition, a source file.
Conversely, we might have a graphic file
that cannot be automatically regenerated,
or a proprietary shared library that we received as a binary:
these do count as source files for our purposes.

Subclasses of source-file exist for various languages.
@emph{FIXME: describe these.}
@end deffn

@deffn Component module

A module is a collection of sub-components.

A module component has the following extra initargs:

@itemize
@item
@code{:components} the components contained in this module

@item
@code{:default-component-class}
All children components which don't specify their class explicitly
are inferred to be of this type.
@code{:if-component-dep-fails}
This attribute was removed in ASDF 3. Do not use it.
Use @code{:if-feature} instead (@pxref{required-features}, and @pxref{if-feature-option}).
@code{:serial} When this attribute is set,
each subcomponent of this component is assumed to depend on all subcomponents
before it in the list given to @code{:components}, i.e.
all of them are loaded before a compile or load operation is performed on it.
The default operation knows how to traverse a module, so
most operations will not need to provide methods specialised on modules.

@code{module} may be subclassed to represent components such as
foreign-language linked libraries or archive files.
@end deffn

@deffn Component system

@code{system} is a subclass of @code{module}.

A system is a module with a few extra attributes for documentation
purposes; these are given elsewhere.
@xref{The defsystem grammar}.
Users can create new classes for their systems:
the default @code{defsystem} macro takes a @code{:class} keyword argument.
@end deffn

@node  Creating new component types,  , Pre-defined subclasses of component, Components
@comment  node-name,  next,  previous,  up
@subsection Creating new component types

New component types are defined by subclassing one of the existing
component classes and specializing methods on the new component class.

@c FIXME: this should perhaps be explained more throughly,
@c not only by example ...

As an example, suppose we have some implementation-dependent
functionality that we want to isolate
in one subdirectory per Lisp implementation our system supports.
We create a subclass of
@code{cl-source-file}:

@lisp
(defclass unportable-cl-source-file (cl-source-file)
Function @code{asdf:implementation-type} (exported since 2.014.14)
gives us the name of the subdirectory.
All that's left is to define how to calculate the pathname
of an @code{unportable-cl-source-file}.