Here are a few examples. (defsystem mysys (:compile-load ("OZ:<GEORGE>PROG1.LISP" "OZ:<GEORGE2>PROG2.LISP"))) (defsystem zmail (:name "ZMail") (:pathname-default "SYS: ZMAIL;") (:package zwei) (:module defs "DEFS") (:module mult "MULT" :package tv) (:module main ("TOP" "COMNDS" "MAIL" "USER" "WINDOW" "FILTER" mult "COMETH")) (:compile-load defs) (:compile-load main (:fasload defs))) (defsystem bar (:module reader-macros "BAR:BAR;RDMAC") (:module other-macros "BAR:BAR;MACROS") (:module main-program "BAR:BAR;MAIN") (:compile-load reader-macros) (:compile-load other-macros (:fasload reader-macros)) (:compile-load main-program (:fasload reader-macros other-macros)))

The first example defines a new system called mysys, which consists of two files, stored on a Tops-20 host names OZ, both of which are to be compiled and loaded. The second example is somewhat more complicated. What all the options mean is described below, but the primary difference is that there is a file DEFS which must be loaded before the rest of the files (main) can be compiled. Also, the files are stored on logical host SYS and directory ZMAIL.

The last example has two levels of dependency. reader-macros must be compiled and loaded before other-macros can be compiled. Both reader-macros and other-macros must then be loaded before main-program can be compiled. All the source files are stored on host BAR, presumably a logical host defined specifically for this system. It is desirable to use a logical host for the files of a system if there is a chance that people at more than one site will be using it; the logical host allows the identical defsystem to be valid at all sites. See for more on logical hosts and logical pathnames.

Note that The defsystem options other than transformations are:

:name	Specifies a ``pretty'' version of the name for the system, for use in printing.
:short-name	Specified an abbreviated name used in constructing disk label comments and in patch file names for some file systems.
:component-systems	Specifies the names of other systems used to make up this system. Performing an operation on a system with component systems is equivalent to performing the same operation on all the individual systems. The format is (:component-systems names...).
:package	Specifies the package in which transformations are performed. A package specified here overrides one in the -*- line of the file in question.
:pathname-default	Gives a local default within the definition of the system for strings to be parsed into pathnames. Typically this specifies the directory, when all the files of a system are on the same directory.
:warnings-pathname-default	Gives a default for the file to use to store compiler warnings in, when make-system is used with the :batch option.
:patchable	Makes the system be a patchable system (see ). An optional argument specifies the directory to put patch files in. The default is the :pathname-default of the system.
:initial-status	Specifies what the status of the system should be when make-system is used to create a new major version. The default is :experimental. See for further details.
:not-in-disk-label	Make a patchable system not appear in the disk label comment. This should probably never be specified for a user system. It is used by patchable systems internal to the main Lisp system, to avoid cluttering up the label.
:default-binary-file-type	Specifies the file type to use for compiled Lisp files. The value you specify should be a string. If you do not specify this, the standard file type :qfasl is used.
:module	Allows assigning a name to a set of files within the system. This name can then be used instead of repeating the filenames. The format is (:module name files options...). files is usually a list of filenames (strings). In general, it is a module-specification, which can be any of the following: a string This is a file name. a symbol This is a module name. It stands for all of the files which are in that module of this system. an external module component This is a list of the form (system-name module-names...), to specify modules in another system. It stands for all of the files which are in all of those modules. a list of module components A module component is any of the above, or the following: a list of file names This is used in the case where the names of the input and output files of a transformation are not related according to the standard naming conventions, for example when a QFASL file has a different name or resides on a different directory than the source file. The file names in the list are used from left to right, thus the first name is the source file. Each file name after the first in the list is defaulted from the previous one in the list. To avoid syntactic ambiguity, this is allowed as a module component but not as a module specification. The currently defined options for the :module clause are :package Overrides any package specified for the whole system for transformations performed on just this module. In the second defsystem example above, there are three modules. Each of the first two has only one file, and the third one (main) is made up both of files and another module. To take examples of the other possibilities, (:module prog (("SYS: GEORGE; PROG" "SYS: GEORG2; PROG"))) (:module foo (defs (zmail defs))) The prog module consists of one file, but it lives in two directories, GEORGE and GEORG2. If this were a Lisp program, that would mean that the file SYS: GEORGE; PROG LISP would be compiled into SYS: GEORG2; PROG QFASL. The foo module consists of two other modules the defs module in the same system, and the defs module in the zmail system. It is not generally useful to compile files that belong to other systems; thus this foo module would not normally be the subject of a transformation. However, dependencies (defined below) use modules and need to be able to refer to (depend on) modules of other systems.

Transformations are of two types, simple and complex. A simple transformation is a single operation on a file, such as compiling it or loading it. A complex transformation takes the output from one transformation and performs another transformation on it, such as loading the results of compilation.

The general format of a simple transformation is (name input dependencies condition). input is usually a module specification or another transformation whose output is used. The transformation name is to be performed on all the files in the module, or all the output files of the other transformation.

dependencies and condition are optional.

dependencies is a transformation specification, either a list (transformation-name module-names...) or a list of such lists. A module-name is either a symbol that is the name of a module in the current system, or a list (system-name module-names...). A dependency declares that all of the indicated transformations must be performed on the indicated modules before the current transformation itself can take place. Thus in the zmail example above, the defs module must have the :fasload transformation performed on it before the :compile transformation can be performed on main.

The dependency has to be a tranformation that is explicitly specified as a transformation in the system definition, not just an action that might be performed by anything. That is, if you have a dependency (:fasload foo), it means that (fasload foo) is a tranformation of your system and you depend on that tranformation; it does not simply mean that you depend on foo's being loaded. Furthermore, it doesn't work if (:fasload foo) is an implicit piece of another tranformation. For example, the following works: (defsystem foo (:module foo "FOO") (:module bar "BAR") (:compile-load (foo bar))) but this doesn't work: (defsystem foo (:module foo "FOO") (:module bar "BAR") (:module blort "BLORT") (:compile-load (foo bar)) (:compile-load blort (:fasload foo))) because foo's :fasload is not mentioned explicitly (i.e. at top level) but is only implicit in the (:compile-load (foo bar)). One must instead write: (defsystem foo (:module foo "FOO") (:module bar "BAR") (:module blort "BLORT") (:compile-load foo) (:compile-load bar) (:compile-load blort (:fasload foo)))

condition is a predicate which specifies when the transformation should take place. Generally it defaults according to the type of the transformation. Conditions are discussed further on .

The defined simple transformations are:

:fasload	Calls the fasload function to load the indicated files, which must be QFASL files whose pathnames have canonical type :qfasl (see ). The condition defaults to si:file-newer-than-installed-p, which is t if a newer version of the file exists on the file computer than was read into the current environment.
:readfile	Calls the readfile function to read in the indicated files, whose names must have canonical type :lisp. Use this for files that are not to be compiled. condition defaults to si:file-newer-than-installed-p.
:compile	Calls the compile-file function to compile the indicated files, whose names must have canonical type :lisp. condition defaults to si:file-newer-than-file-p, which returns t if the source file has been written more recently than the binary file.

A special simple transformation is

:do-components

(:do-components dependencies) inside a system with component systems causes the dependencies to be done before anything in the component systems. This is useful when you have a module of macro files used by all of the component systems.

The defined complex transformations are

:compile-load	(:compile-load input compile-dependencies load-dependencies compile-condition load-condition) is the same as (:fasload (:compile input compile-dependencies compile-condition) load-dependencies load-condition). This is the most commonly-used transformation. Everything after input is optional.
:compile-load-init	See .

As was explained above, each filename in an input specification can in fact be a list of strings when the source file of a program differs from the binary file in more than just the file type. In fact, every filename is treated as if it were an infinite list of filenames with the last filename, or in the case of a single string the only filename, repeated forever at the end. Each simple transformation takes some number of input filename arguments and some number of output filename arguments. As transformations are performed, these arguments are taken from the front of the filename list. The input arguments are actually removed and the output arguments left as input arguments to the next higher transformation. To make this clearer, consider the prog module above having the :compile-load transformation performed on it. This means that prog is given as the input to the :compile transformation and the output from this transformation is given as the input to the :fasload transformation. The :compile transformation takes one input filename argument, the name of a Lisp source file, and one output filename argument, the name of the QFASL file. The :fasload transformation takes one input filename argument, the name of a QFASL file, and no output filename arguments. So, for the first and only file in the prog module, the filename argument list looks like ("SYS: GEORGE; PROG" "SYS: GEORG2; PROG" "SYS: GEORG2; PROG" ...). The :compile transformation is given arguments of "SYS: GEORGE; PROG" and "SYS: GEORG2; PROG" and the filename argument list which it outputs as the input to the :fasload transformation is ("SYS: GEORG2; PROG" "SYS: GEORG2; PROG" ...). The :fasload transformation then is given its one argument of "SYS: GEORG2; PROG".

Note that dependencies are not transitive or inherited. For example, if module a depends on macros defined in module b, and therefore needs b to be loaded in order to compile, and b has a similar dependency on c, c need not be loaded for compilation of a. Transformations with these dependencies would be written (:compile-load a (:fasload b)) (:compile-load b (:fasload c)) To say that compilation of a depends on both b and c, you would instead write (:compile-load a (:fasload b c)) (:compile-load b (:fasload c)) If in addition a depended on c (but not b) during loading (perhaps a contains defvars whose initial values depend on functions or special variables defined in c) you would write the transformations (:compile-load a (:fasload b c) (:fasload c)) (:compile-load b (:fasload c))

These are the keywords recognized by the make-system function and what they do.

:noconfirm make-system	Assumes a yes answer for all questions that would otherwise be asked of the user.
:selective make-system	Asks the user whether or not to perform each transformation that appears to be needed for each file.
:silent make-system	Avoids printing out each transformation as it is performed.
:reload make-system	Bypasses the specified conditions for performing a transformation. Thus files are compiled even if they haven't changed and loaded even if they aren't newer than the installed version.
:noload make-system	Does not load any files except those required by dependencies. For use in conjunction with the :compile option.
:compile make-system	Compiles files also if need be. The default is to load but not compile.
:recompile make-system	This is equivalent to a combination of :compile and :reload: it specifies compilation of all files, even those whose sources have not changed since last compiled.
:no-increment-patch make-system	When given along with the :compile option, disables the automatic incrementing of the major system version that would otherwise take place. See .
:increment-patch make-system	Increments a patchable system's major version without doing any compilations. See .
:no-reload-system-declaration make-system	Turns off the check for whether the file containing the defsystem has been changed. Then the file is loaded only if it has never been loaded before.
:batch make-system	Allows a large compilation to be done unattended. It acts like :noconfirm with regard to questions, turns off more-processing and fdefine-warnings (see inhibit-fdefine-warnings, ), and saves the compiler warnings in an editor buffer and a file (it asks you for the name).
:defaulted-batch make-system	This is like :batch except that it uses the default for the pathname to store warnings in and does not ask the user to type a pathname.
:print-only make-system	Just prints out what transformations would be performed; does not actually do any compiling or loading.
:noop make-system	Is ignored. This is useful mainly for programs that call make-system, so that such programs can include forms like (make-system 'mysys (if compile-p :compile :noop))

make-system keywords are defined as functions on the si:make-system-keyword property of the keyword. The functions are called with no arguments. Some of the relevant variables they can use are

The following simple example adds a new keyword to make-system called :just-warn, which means that fdefine warnings (see ) regarding functions being overwritten should be printed out, but the user should not be queried. (si:define-make-system-special-variable inhibit-fdefine-warnings inhibit-fdefine-warnings nil) (defun (:just-warn si:make-system-keyword) () (setq inhibit-fdefine-warnings :just-warn)) (See the description of the inhibit-fdefine-warnings variable, on .)

make-system keywords can do something directly when called, or they can have their effect by pushing a form to be evaluated onto si:*make-system-forms-to-be-evaled-after* or one of the other two similar lists. In general, the only useful thing to do is to set some special variable defined by si:define-make-system-special-variable. In addition to the ones mentioned above, user-defined transformations may have their behavior controlled by new special variables, which can be set by new keywords. If you want to get at the list of transformations to be performed, for example, the right way is to set si:*file-transformation-function* to a new function, which then can call si:do-file-transformations with a possibly modified list. That is how the :print-only keyword works.

Options to defsystem are defined as macros on the si:defsystem-macro property of the option keyword. Such a macro can expand into an existing option or transformation, or it can have side effects and return nil. There are several variables they can use; the only one of general interest is

Complex transformations are defined as normal macro expansions, for example, (defmacro (:compile-load si:defsystem-macro) (input &optional com-dep load-dep com-cond load-cond) `(:fasload (:compile ,input ,com-dep ,com-cond) ,load-dep ,load-cond))

It is sometimes useful to specify a transformation upon which something else can depend, but which is performed not by default, but rather only when requested because of that dependency. The transformation nevertheless occupies a specific place in the hierarchy. The :skip defsystem macro allows specifying a transformation of this type. For example, suppose there is a special compiler for the read table which is not ordinarily loaded into the system. The compiled version should still be kept up to date, and it needs to be loaded if ever the read table needs to be recompiled. (defsystem reader (:pathname-default "SYS: IO;") (:package system-internals) (:module defs "RDDEFS") (:module reader "READ") (:module read-table-compiler "RTC") (:module read-table "RDTBL") (:compile-load defs) (:compile-load reader (:fasload defs)) (:skip :fasload (:compile read-table-compiler)) (:rtc-compile-load read-table (:fasload read-table-compiler))) Assume that there is a complex transformation :rtc-compile-load, which is like :compile-load except that is is built on a transformation called something like :rtc-compile, which uses the read table compiler rather than the Lisp compiler. In the above system, then, if the :rtc-compile transformation is to be performed, the :fasload transformation must be done on read-table-compiler first, that is the read table compiler must be loaded if the read table is to be recompiled. If you say (make-system 'reader :compile), then the :compile transformation is done on the read-table-compiler module despite the :skip, compiling the read table compiler if need be. If you say (make-system 'reader), the reader and the read table are loaded, but the :skip keeps this from happening to the read table compiler.

So far nothing has been said about what can be given as a condition for a transformation except for the default functions, which check for conditions such as a source file being newer than the binary. In general, any function that takes the same arguments as the transformation function (e.g. compile-file) and returns t if the transformation needs to be performed, can be in this place as a symbol, including for example a closure. To take an example, suppose there is a file that contains compile-flavor-methods for a system and that should therefore be recompiled if any of the flavor method definitions change. In this case, the condition function for compiling that file should return t if either the source of that file itself or any of the files that define the flavors have changed. This is what the :compile-load-init complex transformation is for. It is defined like this: (defmacro (:compile-load-init si:defsystem-macro) (input add-dep &optional com-dep load-dep &aux function) (setq function (let-closed ((*additional-dependent-modules* add-dep)) 'compile-load-init-condition)) `(:fasload (:compile ,input ,com-dep ,function) ,load-dep)) (defun compile-load-init-condition (source-file qfasl-file) (or (si:file-newer-than-file-p source-file qfasl-file) (local-declare ((special *additional-dependent-modules*)) (si:other-files-newer-than-file-p *additional-dependent-modules* qfasl-file))))

The condition function generated when this macro is used returns t either if si:file-newer-than-file-p would with those arguments, or if any of the other files in add-dep, which presumably is a module specification, are newer than the QFASL file. Thus the file (or module) to which the :compile-load-init transformation applies will be compiled if it or any of the source files it depends on has been changed, and will be loaded under the normal conditions. In most (but not all cases), com-dep is a :fasload transformation of the same files as add-dep specifies, so that all the files this one depends on will be loaded before compiling it.

In Common Lisp, a module is a name given to a group of files of code. Modules are not like systems because nothing records what the ``contents'' of any particular module may be. Instead, one of the files which defines the module contains a provide form which says, when that file is loaded, ``Module foo is now present.'' Other files may say, using require, ``I want to use module foo.''

Normally the require form also specifies the files to load if foo has not been provide'd already. This is where the information of which files are in a module is stored. If the require does not have file names in it, the module name foo is used in an implementation-dependent manner to find files to load. The Lisp Machine does this by using it as a system name in make-system.