— 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 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"

— 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

A system with name name, created by make-instance with extra keys keys (e.g. :version), is registered as preloaded. That is, its code has 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.

— Function: register-immutable-system name &rest keys

A system with name name, created by make-instance with extra keys keys (e.g. :version), is registered as immutable. That is, its code has already been loaded into the current image, and if at some point some other system :depends-on it, it is considered as already provided, and no attempt will be made to search for an updated version from the source-registry or any other method. There will be no search for an .asd file, and no missing-component error.

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