— syntax: define-module module-name [options ...]

module-name is of the form (hierarchy file). One example of this is

          (define-module (ice-9 popen))

define-module makes this module available to Guile programs under the given module-name.

The options are keyword/value pairs which specify more about the defined module. The recognized options and their meaning is shown in the following table.

#:use-module interface-specification

Equivalent to a (use-modules interface-specification) (see Using Guile Modules).

#:use-syntax module

Use module when loading the currently defined module, and install it as the syntax transformer.

#:autoload module symbol-list

Load module when any of symbol-list are accessed. For example,

               (define-module (my mod)
                 #:autoload (srfi srfi-1) (partition delete-duplicates))
               ...
               (if something
                   (set! foo (delete-duplicates ...)))

When a module is autoloaded, all its bindings become available. symbol-list is just those that will first trigger the load.

An autoload is a good way to put off loading a big module until it's really needed, for instance for faster startup or if it will only be needed in certain circumstances.

@ can do a similar thing (see Using Guile Modules), but in that case an @ form must be written every time a binding from the module is used.

#:export list

Export all identifiers in list which must be a list of symbols or pairs of symbols. This is equivalent to (export list) in the module body.

#:re-export list

Re-export all identifiers in list which must be a list of symbols or pairs of symbols. The symbols in list must be imported by the current module from other modules. This is equivalent to re-export below.

#:export-syntax list

Export all identifiers in list which must be a list of symbols or pairs of symbols. The identifiers in list must refer to macros (see Macros) defined in the current module. This is equivalent to (export-syntax list) in the module body.

#:re-export-syntax list

Re-export all identifiers in list which must be a list of symbols or pairs of symbols. The symbols in list must refer to macros imported by the current module from other modules. This is equivalent to (re-export-syntax list) in the module body.

#:replace list

Export all identifiers in list (a list of symbols or pairs of symbols) and mark them as replacing bindings. In the module user's name space, this will have the effect of replacing any binding with the same name that is not also “replacing”. Normally a replacement results in an “override” warning message, #:replace avoids that.

In general, a module that exports a binding for which the (guile) module already has a definition should use #:replace instead of #:export. #:replace, in a sense, lets Guile know that the module purposefully replaces a core binding. It is important to note, however, that this binding replacement is confined to the name space of the module user. In other words, the value of the core binding in question remains unchanged for other modules.

Note that although it is often a good idea for the replaced binding to remain compatible with a binding in (guile), to avoid surprising the user, sometimes the bindings will be incompatible. For example, SRFI-19 exports its own version of current-time (see SRFI-19 Time) which is not compatible with the core current-time function (see Time). Guile assumes that a user importing a module knows what she is doing, and uses #:replace for this binding rather than #:export.

The #:duplicates (see below) provides fine-grain control about duplicate binding handling on the module-user side.

#:version list

Specify a version for the module in the form of list, a list of zero or more exact, nonnegative integers. The corresponding #:version option in the use-modules form allows callers to restrict the value of this option in various ways.

#:duplicates list

Tell Guile to handle duplicate bindings for the bindings imported by the current module according to the policy defined by list, a list of symbols. list must contain symbols representing a duplicate binding handling policy chosen among the following:

check

Raises an error when a binding is imported from more than one place.

warn

Issue a warning when a binding is imported from more than one place and leave the responsibility of actually handling the duplication to the next duplicate binding handler.

replace

When a new binding is imported that has the same name as a previously imported binding, then do the following:

1. If the old binding was said to be replacing (via the #:replace option above) and the new binding is not replacing, the keep the old binding.
2. If the old binding was not said to be replacing and the new binding is replacing, then replace the old binding with the new one.
3. If neither the old nor the new binding is replacing, then keep the old one.

warn-override-core

Issue a warning when a core binding is being overwritten and actually override the core binding with the new one.

first

In case of duplicate bindings, the firstly imported binding is always the one which is kept.

last

In case of duplicate bindings, the lastly imported binding is always the one which is kept.

noop

In case of duplicate bindings, leave the responsibility to the next duplicate handler.

If list contains more than one symbol, then the duplicate binding handlers which appear first will be used first when resolving a duplicate binding situation. As mentioned above, some resolution policies may explicitly leave the responsibility of handling the duplication to the next handler in list.

The default duplicate binding resolution policy is given by the default-duplicate-binding-handler procedure, and is

               (replace warn-override-core warn last)

#:no-backtrace

Tell Guile not to record information for procedure backtraces when executing the procedures in this module.

#:pure

Create a pure module, that is a module which does not contain any of the standard procedure bindings except for the syntax forms. This is useful if you want to create safe modules, that is modules which do not know anything about dangerous procedures.

— syntax: export variable ...

Add all variables (which must be symbols or pairs of symbols) to the list of exported bindings of the current module. If variable is a pair, its car gives the name of the variable as seen by the current module and its cdr specifies a name for the binding in the current module's public interface.

— syntax: define-public ...

Equivalent to (begin (define foo ...) (export foo)).

— syntax: re-export variable ...

Add all variables (which must be symbols or pairs of symbols) to the list of re-exported bindings of the current module. Pairs of symbols are handled as in export. Re-exported bindings must be imported by the current module from some other module.