Next: , Previous: , Up: Using ASDF   [Contents][Index]


5.2 Convenience Functions

ASDF provides three commands for the most common system operations: load-system, compile-system, and test-system.

ASDF also provides require-system, a variant of load-system that skips loading systems that are already loaded. This is sometimes useful, for example, in order to avoid re-loading libraries that come pre-loaded into your lisp implementation.

ASDF also provides make, a way of allowing system developers to choose a default operation for their systems. For example, a developer who has created a system intended to format a specific document, might make document-formatting the default operation invoked by make, instead of loading. If the system developer doesn’t specify in the system definition, the default operation will be loading.

Because ASDF is an extensible system for defining operations on components, it also provides a generic function operate, so you may arbitrarily operate on your systems beyond the default operations. (At the interactive REPL, users often use its shorter alias oos, which stands for operate-on-system, a name inherited from mk-defsystem.) You’ll use operate whenever you want to do something beyond compiling, loading and testing.

Function: load-system system &rest keys &key force force-not verbose version &allow-other-keys

Apply operate with the operation from *load-system-operation* the system, and any provided keyword arguments. *load-system-operation* by default is load-op; it would be load-bundle-op by default on ECL, if only an implementation bug were fixed. Calling load-system is the regular, recommended way to load a system into the current image.

Function: compile-system system &rest keys &key force force-not verbose version &allow-other-keys

Apply operate with the operation compile-op, the system, and any provided keyword arguments. This will make sure all the files in the system are compiled, but not necessarily load any of them in the current image; on most systems, it will not load all compiled files in the current image. This function exists for symmetry with load-system but is not recommended unless you are writing build scripts and know what you’re doing. But then, you might be interested in program-op rather than compile-op.

Function: test-system system &rest keys &key force force-not verbose version &allow-other-keys

Apply operate with the operation test-op, the system, and any provided keyword arguments. See test-op.

Function: make system &rest keys &key &allow-other-keys

Do “The Right Thing” with your system. Starting with ASDF 3.1, this function make is also available. The default behaviour is to load the system as if by load-system; but system authors can override this default in their system definition they may specify an alternate operation as the intended use of their system, with a :build-operation option in the defsystem form (see build-operation), and an intended output pathname for that operation with :build-pathname. This function is experimental and largely untested. Use at your own risk.

Function: require-system system &rest keys &key &allow-other-keys

require-system skips any update to systems that have already been loaded, in the spirit of cl:require. It does it by calling load-system with a keyword option excluding already loaded systems.8. On actively maintained free software implementations (namely recent versions of ABCL, Clozure CL, CMUCL, ECL, GNU CLISP, MKCL and SBCL), once ASDF itself is loaded, cl:require too can load ASDF systems, by falling back on require-system for module names not recognized by the implementation. (Note however that require-system does not fall back on cl:require; that would introduce an “interesting” potential infinite loop to break somehow.)

cl:require and require-system are appropriate to load code that is not being modified during the current programming session. cl:require will notably load the implementation-provided extension modules; require-system won’t, unless they are also defined as systems somehow, which SBCL and MKCL do. require-system may also be used to load any number of ASDF systems that the user isn’t either developing or debugging, for which a previously installed version is deemed to be satisfactory; cl:require on the above-mentioned implementations will delegate to require-system and may load them as well. But for code that you are actively developing, debugging, or otherwise modifying, you should use load-system, so ASDF will pick on your modifications and transitively re-build the modified files and everything that depends on them (that the requested system itself depends on — ASDF itself never builds anything unless it’s an explicitly requested system or the dependencies thereof).


Footnotes

(8)

For the curious, the option is :force-not (already-loaded-systems).


Next: , Previous: , Up: Using ASDF   [Contents][Index]