Next: Some Utility Functions, Previous: Controlling source file character encoding, Up: Miscellaneous additional functionality [Contents][Index]
These functions are exported by ASDF for your convenience.
It’s often handy to locate a file relative to some system.
The system-relative-pathname function meets this need.
It takes two mandatory arguments system and name
and a keyword argument type:
system is name of a system, whereas name and optionally type
specify a relative pathname, interpreted like a component pathname specifier
by coerce-pathname. See Pathname specifiers.
It returns a pathname built from the location of the system’s source directory and the relative pathname. For example:
> (asdf:system-relative-pathname 'cl-ppcre "regex.data") #P"/repository/other/cl-ppcre/regex.data"
ASDF does not provide a turnkey solution for locating
data (or other miscellaneous) files
that are distributed together with the source code of a system.
Programmers can use system-source-directory to find such files.
Returns a pathname object.
The system-designator may be a string, symbol, or ASDF system object.
It is sometimes useful to force recompilation of a previously loaded system.
For these cases, (asdf:clear-system :foo)
will remove the system from the table of currently loaded systems:
the next time the system foo or one that depends on it is re-loaded,
foo will be loaded again.16
Note that this does not and cannot undo
the previous loading of the system.
Common Lisp has no provision for such an operation,
and its reliance on irreversible side-effects to global data structures
makes such a thing impossible in the general case.
If the software being re-loaded is not conceived with hot upgrade in mind,
re-loading may cause many errors, warnings or subtle silent problems,
as packages, generic function signatures, structures, types, macros, constants, etc.
are being redefined incompatibly.
It is up to the user to make sure that reloading is possible and has the desired effect.
In some cases, extreme measures such as recursively deleting packages,
unregistering symbols, defining methods on update-instance-for-redefined-class
and much more are necessary for reloading to happen smoothly.
ASDF itself goes to extensive effort to make a hot upgrade possible
with respect to its own code.
If you want, you can reuse some of its utilities such as
uiop:define-package and uiop:with-upgradability,
and get inspiration (or disinspiration)
from what it does in header.lisp and upgrade.lisp.
A system with name name,
created by make-instance with extra keys keys
(e.g. :version),
is registered as preloaded.
If version is t (default), then the version is copied from the defined system
of the same name (if registered) or else is nil
(this automatic copy of version is only available starting since ASDF 3.1.8).
A preloaded system is considered as having already been loaded into the current image,
and if at some point some other system :depends-on it yet no source code is found,
it is considered as already provided,
and ASDF will not raise a missing-component error.
This function is particularly useful if you distribute your code
as fasls with either compile-bundle-op or monolithic-compile-bundle-op,
and want to register systems so that dependencies will work uniformly
whether you’re using your software from source or from fasl.
Note that if the system was already defined or loaded from source code,
its build information will remain active until you call clear-system on it,
at which point a system without build information will be registered in its place.
A system with name name is registered as preloaded,
and additionally is marked as immutable:
that is, attempts to compile or load it will be succeed
without actually reading, creating or loading any file,
as if the system was passed as a force-not argument
to all calls to plan or operate.
There will be no search for an updated .asd file
to override the loaded version,
whether from the source-register or any other method.
If a version keyword argument is specified as t or left unspecified,
then the version is copied from the defined system
of the same name (if registered) or else is nil.
This automatic copy of version is available starting
since immutable systems have been available in ASDF 3.1.5.
This function, available since ASDF 3.1.5, is particularly useful if you distribute a large body of code as a precompiled image, and want to allow users to extend the image with further extension systems, but without making thousands of filesystem requests looking for inexistent (or worse, out of date) source code for all the systems that came bundled with the image but aren’t distributed as source code to regular users.
This function is obsolete and present only for the sake of backwards-compatibility: “If it’s not backwards, it’s not compatible”. We strongly discourage its use. Its current behaviour is only well-defined on Unix platforms (which include MacOS X and cygwin). On Windows, anything goes. The following documentation is only for the purpose of your migrating away from it in a way that preserves semantics.
Instead we recommend the use run-program, described in the next section, and
available as part of ASDF since ASDF 3.
run-shell-command takes as arguments a format control-string
and arguments to be passed to format after this control-string
to produce a string.
This string is a command that will be evaluated with a POSIX shell if possible;
yet, on Windows, some implementations will use CMD.EXE,
while others (like SBCL) will make an attempt at invoking a POSIX shell
(and fail if it is not present).
Alternatively, you could touch foo.asd or
remove the corresponding fasls from the output file cache.
Next: Some Utility Functions, Previous: Controlling source file character encoding, Up: Miscellaneous additional functionality [Contents][Index]