15. Libraries

A library description consists of the following parts:

• A single library declaration form. It specifies a name for the library, a set of modules which are exported by the library for use by other libraries, and a set of modules that are imported from other libraries for use by the library being defined. Library declaration forms are described below.
• The association of source code with the library. The mechanism by which this association is made is implementation-defined.
• The association of executable code with the library. The mechanism by which this association is made is implementation-defined. The mechanism by which the compiler is invoked to produce the executable code is implementation-defined.
• The association of library export information with the library. The mechanism by which this association is made is implementation-defined. The mechanism by which the compiler is invoked to produce the library export information is implementation-defined. The contents of library export information is implementation-dependent, but it comprises the information required to process the source code of some other library that imports the library.

The library export information is the only part of a Dylan library that is needed to allow some other library to import it. A library that exports some modules does not have any additional declarations whose purpose is to provide information to the compiler when it is processing the code of a library that imports those modules. Rather, any such information that might be needed is obtained in some implementation defined way while processing the source expressions of the exporting library and is retained in the library export information of the exporting library.

The syntax for library declarations matches the syntax for module definitions exactly, except of course that the word module is replaced with the word library, and that library declarations do not have create clauses.

Exporting a module from a library makes all of the variables exported by the module available for import by modules in other libraries. There are two ways in which a module may be exported from a library.

Importing a module into a library allows the module to be used by modules defined within the library. Importing a module into a library does not allow expressions in the library to be associated with the module. A module is imported into a library by including a library-use-clause in the library declaration that includes the module in the set of modules imported from the used library. By default, all exported modules from the used library are imported by the library being defined, under the same name they had in the used library.

When there are multiple use clauses using the same library, the set of imported modules is the union of those specified by all the use-clauses. Some modules may be imported under more than one module name.

The options in a use-clause are used to prevent some modules from being imported, to give some or all the imported modules different names in the new library, and to re-export modules which were imported from a used library. Each of these options applies within the scope of the particular use-clause, and does not affect the behavior of other use-clauses.

The meanings of the various options in a library-use-clause are similar to the corresponding options in a module-use-clause, except that it is module names in libraries that are being specified, rather than variable names in modules.

The mechanism by which the library-name in a library-use-clause is associated with the corresponding library description is implementation-defined.

Each implementation must provide a library named dylan which exports a module named dylan. That module must export exactly those variables documented as being part of the Dylan language, and the values of those variables must be as specified by the Dylan language. The dylan library is permitted to export additional implementation dependent modules.

Library declarations are expressions. Like other "defining forms," library declarations are only allowed at top level or inside of begin. The names in a library declaration are not module variable names, and thus are not affected by the library declaration's associated module. A library declaration can be associated with any module where "define library" has its normal meaning.

Macros can expand into library declarations. This happens during compilation of the library declaration.

Each library contains an implicitly defined module whose name is dylan-user. Within this module, all the variables specified by the Dylan language are accessible using their specified names. Additional implementation-dependent variables may also be accessible from this module.