Milestone 1

Modules

A module is a set of packages together with a module descriptor. A module is packaged as a module archive, which serves as a unit of distribution.

Usage

An example module descriptor:

module com.example.foo '1.2.0' {
    import com.example.bar '3.4.1';
}

This would occur in the source file <source-dir>/com/example/foo/module.ceylon where <source-dir> is a directory containing ceylon source code, conventionally source.

Description

Member packages

The names of the packages in a module must begin with the name of the module, so for example in a module called com.example.foo all package names must begin com.example.foo.

Descriptor

The module descriptor holds metadata about the module and is declared in a source file called module.ceylon in the base package of the module (that is the package whose name is the same as the module name). Here's an example:

"An example module."
module com.example.foo '1.2.0' {
    import com.example.bar '3.4.1';
    import org.example.whizzbang '0.5';
}

The module declaration may be preceeded by annotations, including:

  • doc to let you to specify module-level documentation,
  • license to let you specify the module's license,
  • by to document the module's author or authors.

The module declaration itself starts with the module keyword followed by the module name and version and a list of imports enclosed in braces.

Each dependency of the module must be declared with an import declaration specifying the module name of the dependency and its version.

The import declarations can also be annotated. Two annotations particularly worth noting are:

  • shared to mark the imported module as also being exported to clients of this module. If your module uses types from an imported module in its API then the import for that module must be annotated shared in the module descriptor.
  • optional to mark the imported module as being an optional dependency.

Distribution

Modules are distributed in .car files, which are essentially .jar files with a different extension, and with a module descriptor.

Modules are kept in a module repository. The list of module repositories to use is passed to ceylon compile, ceylon run, and other tools.

See also