11.3 Miscellaneous Functions

These functions are exported by ASDF for your convenience.

Function: system-relative-pathname system name &key type

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 パス名指定子.

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"

Function: system-source-directory system-designator

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.

Function: clear-system system-designator

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.⁵²

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.

Function: register-preloaded-system name &rest keys &key version &allow-other-keys

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.

Function: register-immutable-system name &rest keys

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.

Function: run-shell-command control-string &rest args

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).