define-module

Purpose
Defines a module to the Module Manager Facility.

Package   :module-manager

Module   :module-manager

Arguments and values

Errors
The :requires module option specifies a fully expanded required-module order that contains a circularity.
The :requires module option specifies a fully expanded required-module order that conflicts with the fully expanded required-module order in a previously defined module.

Detailed syntax

Terms

Description
The module-options :requires, :directory, :files, and :patches can be specified in any order, but at most one of each is allowed.

If a :directory module option is not specified, an implicit root directory for the module (at the *load-truename* of the file containing the define-module form) is used. If the :directory module option specifies a keyword naming another module, the directory specification of the named module is used as the base (root or relative) directory for the module that is being defined. If both a module and a root or relative directory definition have the same name, the directory definition takes precedence over the module directory specification.

The :requires module option specifies, in order, the modules that must be loaded before this module. The fully expanded required-module order determined from the specified :requires module option must be consistent with all previously defined modules.

The :files module option specifies, in order, the files that are compiled (when appropriate) and loaded for this module. Similarly, the :patches module option specifies, in order, the patch files that are compiled (when appropriate) and loaded for this module. The combination of the :requires, :files, and :patches module options specifies a total ordering of all the files that must be compiled and loaded for this module (the files associated with each of the required modules followed by the files specified for this module followed by the patch files associated with each of the required modules followed by the patch files specified for this module).In order to maintain an invariant patch ordering, patches should be added sequentially to the main (last loaded) module of an application. The source files for patches should be placed in a subdirectory named patches in the module's source-file directory.

File-options have the following effects:

The documentation string associated with a module can be accessed and set by using Common Lisp's documentation generic function with the module's module-name and the doc-type module.

See also
    define-relative-directory
    define-root-directory
    describe-module
    describe-patches
    compile-module
    continue-patch
    get-patch-description
    finish-patch
    load-module
    load-module-file
    patch
    patch-loaded-p
    start-patch
    with-system-name
    with-module-redefinitions

Examples
Define a root directory and module for :my-app:

  (define-root-directory :my-app-root 
    (make-pathname :directory "~/my-app"))

  (define-module :my-app
    "My simple application module"
    (:requires :gbbopen-user)
    (:directory :my-app-root)
    (:files "preamble"
            ("macros" :forces-recompile)
            "classes"
            "my-app"
            "epilogue"))

Define a module for :my-app rooted relative to the file containing the define-module form:

  (define-module :my-app
    "My simple application module"
    (:requires :gbbopen-user)
    (:files "preamble"
            ("macros" :forces-recompile)
            "classes"
            "my-app"
            "epilogue"))

Retrieve and then modify the documentation string of module :my-app:

  > (documentation ':my-app 'module)
  "My simple application module"
  > (setf (documentation ':my-app 'module) "My way cool application module")
  "My way cool application module"
  > (documentation ':my-app 'module)
  "My way cool application module"
  >

define-module