Introduction

This document describes the defsystem system definition macro, a
portable "Make" facility for Common Lisp.

Support is provided for organizing systems into hierarchical layers of
modules, with matching directory structure. Moreover, the components
of the system may be listed in any order the user desires, because the
defsystem command reorganizes them according to the file-dependency
constraints specified by the user. Since it accomplishes this by
performing a topological sort of the constraint-graph, cyclical
dependencies are not supported (the graph must be a DAG).

Only two operations, compile and load, are currently defined. The
interface for defining new operations, however, is simple and extendible.

Though home-grown, the syntax was inspired by fond memories of the
defsystem facility on Symbolics 3600 series lisp machines. The
exhaustive lists of filename extensions for various lisps and the idea
to have one "operate-on-system" function instead of separate
"compile-system" and "load-system" functions were taken from Xerox
Corporation's PCL (Portable Common Loops) system.

The code for the defsystem facility and this documentation may be
found in /afs/cs.cmu.edu/user/mkant/Defsystem/defsystem.{text,lisp}

Written by Mark Kantrowitz, School of Computer Science, Carnegie
Mellon University, January 1990.

Please send bug reports, comments and suggestions to mkant@cs.cmu.edu.


Using the System

To use this system,
	1. If you want to have a central directory where system
	   definition files will be kept, modify the value of
	   *central-registry* in defsystem.lisp to be the pathname of
	   that directory.
	2. Save and load the file defsystem.lisp
	3. Load the file containing the defsystem form defining your
	   system. If the name of your system is foo, the file will 
	   be named "foo.system". [If you are going to load the system
	   and not compile it, you can use (require "foo") to load it
	   if the definition file is in either the current directory
	   or the central registry.]
	4. Use the function "operate-on-system" to do things to your
	   system. For example (operate-on-system "foo" 'load) will
	   load the system, while (operate-on-system "foo" 'compile)
	   will compile it.

	   
External Interface

The external interface to the defsystem facility are the defsystem
macro and the operate-on-system function. Defsystem is used to define
a new system and operate-on-system to compile it and load it. The
definition of require has been modified to mesh well with systems
defined using defsystem, and is fully backward-compatible.

In addition, the function afs-binary-directory has been provided for
immitating the behavior of the @sys feature of the Andrew File System
on systems not running AFS. The @sys feature allows soft links to
point to different directories depending on which platform is
accessing the files. A common setup would be to have the bin directory
soft linked to .bin/@sys and to have subdirectories of .bin
corresponding to each platform (.bin/vax_mach, .bin/unix,
.bin/pmax_mach, etc.). The afs-binary-directory function returns the
appropriate binary directory for use as the :binary-pathname argument
in the defsystem macro. For example, if we evaluate
(afs-binary-directory "foodir/") on a vax running the Mach operating
system, "foodir/.bin/vax_mach/" would be returned.


Defining Systems with Defsystem

A system is a set of components with associated properties. These
properties include the type, name, source and binary pathnames,
package, component-dependencies, initializations, and a set of
components.  

Components may be of three types: :system, :module, or :file.
Components of type :system have absolute pathnames and are used to
define a multi-system system. The toplevel system defined by the
defsystem macro is implicitly of type :system. Components of type
:module have pathnames that are relative to their containing system or
module, and may contain a set of files and modules. This enables one
to define subsystems, subsubsystems, submodules, and so on.

Foreign systems (systems defined using some other system definition
tool), may be included by providing separate compile and load forms
for them (using the :compile-form and :load-form keywords). These
forms will be run if and only if they are included in a module with no
components. [In some future version of the defsystem facility there
will be new component types corresponding to each possible operation.]
This is useful if it isn't possible to convert these systems to the
defsystem format all at once.

The name of a component may be a symbol or a string. For ease of
access the definition of a system (its component) is stored under the
system properties of the symbol corresponding to its uppercase name.
If the system name is a symbol, for all other purposes the name is
converted to a lowercase string (system names that are strings are
left alone). It is usually best to use the string version of a
system's name when defining or referring to it. A system defined as
'foo will have an internal name of "foo" and will be stored in the
file "foo.system". A system defined as "Foo" will have an internal
name of "Foo" and will be stored in the file "Foo.system".

The absolute (for components of type :system) and relative (for all
other components) pathnames of the binary and source files may be
specified using the :source-pathname and :binary-pathname keywords in
the component definition. The pathnames associated with a module
correspond to subdirectories of the containing module or system. If no
binary pathname is specified, the binaries are distributed among the
sources. If no source pathname is given for a component, it defaults
to the name of the component. Since the names are converted to
lowercase, pathnames must be provided for each component if the
operating system is case sensitive (unless the pathnames are all
lowercase). Similarly, if a module does not correspond to a
subdirectory, a null-string pathname ("") must be provided.

File types (e.g., "lisp" and "fasl") for source and binary files may
be specified using the :source-extension and :binary-extension
keywords. If these are not specified or given as nil, the makes a
reasonable choice of defaults based on the machine type and underlying
operating system. These file types are inherited by the components of
the system.

At system definition time, every relative directory is replaced with
the corresponding cumulative relative pathname with all the components
incorporated. 

One may also specify the package to be used and any initializations
and finalizations. Initializations (specified with the keyword
:initially-do) are evaluated before the system is loaded or compiled,
and finalizations (specified with the keyword :finally-do) are
evaluated after the system is finished loading or compiling. The
argument to the keyword is a form which is evaluated. Multiple forms
may be evaluated by wrapping a progn around the forms.

The components of a system, module or file are specified with the
:components keyword, and are defined in a manner analogous to the way
in which a system is defined. 

The dependencies of a system, module or file are specified with the
:depends-on keyword, followed by a list of the names of the components
the system, module or file depends on. The components referred to must
exist at the same level of the hierarchy as the referring component.
This enforces the modularity of the defined system. If module A
depends on a file contained within module B, then module A depends on
module B and should be specified as such. Any other use would make a
mockery of the concept of modularity. This requirement is not enforced
in the software, but any use contrary to it will produce unpredictable
results. 

Thus the only requirement in how the files are organized is that at
the level of each module or system, the dependency graph of the
components must be a DAG (directed ACYCLIC graph). If there are any
dependency cycles (i.e., module A uses definitions from module B, and
module B uses definitions from module A), the defsystem macro will not
be able to compute a total ordering of the files (a linear order in
which they should be compiled and loaded). Usually the defsystem will
detect such cycles and halt with an error.

If no dependencies are provided for the system, modules and files, it
may load them in any order. Currently, however, it loads them in
serial order. In a future version of defsystem this will probably
become a supported feature. [In other words, this feature hasn't been
tested to make sure that they files are not accidentally loaded in the
opposite order in some cases. It all depends on whether the definition
of topological-sort used is a stable sort or not.]

The basic algorithm used is to topologically sort the DAG at each
level of abstraction (system level, module level, submodule level,
etc.) to insure that the system's files are compiled and loaded in the
right order. This occurs at system definition time, rather than at
system use time, since it probably saves the user some time.


BNF for Components
 
The general format of a component's definition is:

<definition> ::= (<type> <name> [:host <host>] [:device <device>]
                                [:source-pathname <pathname>]
                                [:source-extension <extension>]
                                [:binary-pathname <pathname>]
                                [:binary-extension <extension>]
                                [:package <package>]
                                [:initially-do <form>]
                                [:finally-do <form>]
                                [:components (<definition>*)]
                                [:depends-on (<name>*)]
                                [:compile-form <form>]
                                [:load-form <form>]
                                [:author <string>]
                                [:licence <string>]
                                [:documentation <string>]
                  )
<type> ::= :system | :module | :file

The toplevel defsystem form substitutes defsystem for :system.


Using Systems with Operate-on-System

The function operate-on-system is used to compile or load a system, or
do any other operation on a system. At present only compile and load
operations are defined, but other operations such as edit, hardcopy,
or applying arbitrary functions (e.g., enscript, lpr) to every file in
the system could be added easily.

The syntax of operate-on-system is as follows:

operate-on-system system-name operation 
	&key force test verbose dribble load-source-instead-of-binary
	     load-source-if-no-binary bother-user-if-no-binary

	SYSTEM-NAME is the name of the system and may be a symbol or
	string.

	OPERATION is 'compile (or :compile) or 'load (or :load) or any
	new operation defined by the user.

	FORCE determines what files are operated on:
	:all (or T) specifies that all files in the system should be used
	:new-source compiles only those files whose sources are more
	recent than the binaries and loads the source if it is newer
	than the binaries. This allows you to load the most up to date
	version of the system.	
	:new-sources-and-dependents uses all files
	used by :new-source, plus any files that depend on the those
	files or their dependents (recursively).
	Force may also be a list of the specific modules or files to
	be used (plus their dependents).
	The default for 'load is :all and for 'compile is
	:new-source-and-dependents. 

	VERSION indicates which version of the system should be used.
	If nil, then the usual root directory is used. If a symbol,
	such as 'alpha, 'beta, 'omega, :alpha, or 'mark, it
	substitutes the appropriate (lowercase) subdirectory of the
	root directory for the root directory. If a string, it replaces
	the entire root directory with the given directory.

	VERBOSE is T to print out what it is doing (compiling, loading
	of modules and files) as it does it. (default nil)

	TEST is T to print out what it would do without actually doing it.
	If test is T it automatically sets verbose to T. (default nil)

	DRIBBLE should be the pathname of a dribble file if you want
	to keep a record of the compilation. (default nil)

	LOAD-SOURCE-INSTEAD-OF-BINARY is T to force the system to load
	source files instead of binary files. (default nil)
	
	LOAD-SOURCE-IF-NO-BINARY is T to have the system load source
	files if the binary file is missing. (default nil)

	BOTHER-USER-IF-NO-BINARY is T to have the system bother the 
	user about missing binaries before it goes ahead and loads
	them if load-source-if-no-binary is T. (default t) Times out
	in 60 seconds unless *use-timeouts* is set to nil.

An implicit assumption is that if we need to load a file for some
reason, then we should be able to compile it immediately before we
need to load it. This obviates the need to specify separate load and
compile dependencies in the modules.

Files which must not be compiled should be loaded in the
initializations or finalizations of a module by means of an explicit
load form.

Note that under this assumption, the example given in the PCL
defsystem becomes quite ludicrous. Those constraints are of the form:
    1. C must be loaded before A&B are loaded
    2. A&B must be loaded before C is compiled
When you add in the reasonable assumption that before you load C, you
must compile C, you get a cycle.

The only case is which this might not be true is in a system which
worked on the dependency graph of individual definitions. But we have
restricted ourselves to file dependencies and will stick with that.
(In situations where a file defining macros must have the sources
loaded before compiling them, most often it is because the macros are
used before they are defined, and hence assumed to be functions. This
can be fixed by organizing the macros better, or including them in a
separate file.)


Defining New Operations

To define a new operation, write a function with parameters component
and force that performs the operation. The function component-pathname
may be used to extract the source and binary pathnames from the
component. [Component-pathname takes parameters component and
file-type, where file-type is either :source or :binary, and returns
the appropriate pathname.] If the component has "changed" as a result
of the operation, T should be returned; otherwise nil. See the
definition of compile-file-operation and load-file-operation for
examples. 

Then install the definition using component-operation, which takes as
parameters the symbol which will be used to name the operation in
operate-on-system, and the name of the function. For example, here's
the definition of the 'compile and :compile operations:
	(component-operation :compile  'compile-and-load-operation)
	(component-operation 'compile  'compile-and-load-operation)

Eventually this system will include portable definitions of 'hardcopy
and 'edit.


Changes to Require

This defsystem interacts smoothly with the require and provide
facilities of Common Lisp. Operate-on-system automatically provides
the name of any system it loads, and uses the new definition of
require to load any dependencies of the toplevel system.

To facilitate this, three new optional arguments have been added to
require. Thus the new syntax of require is as follows:

require system-name &optional pathname definition-pname default-action version

If pathname is provided, the new require behaves just like the old
definition. Otherwise it first tries to find the definition of the
system-name (if it is not already defined it will load the definition
file if it is in the current-directory, the central-registry
directory, or the directory specified by definition-pname) and runs
operate-on-system on the system definition. If no definition is to be
found, it will evaluate the default-action if there is one. Otherwise
it will try running the old definition of require on just the system
name. If all else fails, it will print out a warning.


A Sample System Definition and Its Use

Here's a system definition for the files in the following directory
structure: 

	% du -a test
	1       test/fancy/macros.lisp
	1       test/fancy/primitives.lisp
	3       test/fancy
	1       test/macros.lisp
	1       test/primitives.lisp
	1       test/graphics/macros.lisp
	1       test/graphics/primitives.lisp
	3       test/graphics
	1       test/os/macros.lisp
	1       test/os/primitives.lisp
	3       test/os
	12      test


(defsystem test
  :source-pathname "/afs/cs.cmu.edu/user/mkant/Defsystem/test/"
  :source-extension "lisp"
  :binary-pathname nil
  :binary-extension nil
  :components ((:module basic
			:source-pathname ""
			:components ((:file "primitives")
				     (:file "macros"
					    :depends-on ("primitives"))))
	       (:module graphics
			:source-pathname "graphics"
			:components ((:file "macros"
					    :depends-on ("primitives"))
				     (:file "primitives"))
			:depends-on (basic))
	       (:module fancy-stuff
			:source-pathname "fancy"
			:components ((:file "macros"
					    :depends-on ("primitives"))
				     (:file "primitives"))
			:depends-on (graphics operating-system))
	       (:module operating-system
			:source-pathname "os"
			:components ((:file "primitives")
				     (:file "macros"
					    :depends-on ("primitives")))
			:depends-on (basic)))
  :depends-on nil)

<cl> (operate-on-system 'test 'compile :verbose t)

;  - Compiling system "test"
;    - Compiling module "basic"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/primitives.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/primitives.fasl"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/macros.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/macros.fasl"
;    - Compiling module "graphics"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/primitives.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/primitives.fasl"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/macros.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/macros.fasl"
;    - Compiling module "operating-system"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/primitives.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/primitives.fasl"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/macros.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/macros.fasl"
;    - Compiling module "fancy-stuff"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/primitives.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/primitives.fasl"
;      - Compiling source file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/macros.lisp"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/macros.fasl"
;  - Providing system test
NIL

<cl> (operate-on-system 'test 'load :verbose t)

;  - Loading system "test"
;    - Loading module "basic"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/primitives.fasl"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/macros.fasl"
;    - Loading module "graphics"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/primitives.fasl"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/graphics/macros.fasl"
;    - Loading module "operating-system"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/primitives.fasl"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/os/macros.fasl"
;    - Loading module "fancy-stuff"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/primitives.fasl"
;      - Loading binary file
;        "/afs/cs.cmu.edu/user/mkant/Defsystem/test/fancy/macros.fasl"
;  - Providing system test
NIL



Miscellaneous Notes
	
Macintosh pathnames are not fully supported at this time
because of irregularities in the Allegro Common Lisp definition of the
pathname functions. Thus system definitions will not be portable to
the Macintosh. To convert them, include the device in the toplevel
pathname and include trailing colons in the pathnames of each module.

We currently assume that compilation-load dependencies and if-changed
dependencies are identical. However, in some cases this might not be
true. For example, if we change a macro we have to recompile functions
that depend on it, but not if we change a function. Splitting these
apart (with appropriate defaulting) would be nice, but not worth doing
immediately since it may save only a couple of file recompilations,
while making the defsystem much more complex. And if someone has such
a large system that this matters, they've got more important problems.
