View source | Edit

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 preceded 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. 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.
  • doc, if there is something about the dependency worthy of documentation.

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.

Legacy modules

For interoperation with Java it's possible to convert Java .jar files into Ceylon compatible modules. All we need is a module descriptor telling Ceylon what it needs to know about the module and its dependencies.

If there is any module descriptor inside the .jar, in any of the following locations, it will be used:

  • META-INF/jbossmodules/module/name/version/module.xml,
  • META-INF/jbossmodules/module/name/version/module.properties,
  • META-INF/MANIFEST.MF, for OSGi modules, or
  • META-INF/maven/module/name/pom.xml, for Maven modules.

If there is no module descriptor inside the .jar, you can provide an external descriptor:

  • using a module.properties file whose format is explained here, or
  • using a JBoss Modules module.xml file, whose detailed specification can be found here.

In both cases the file must be placed in the same folder as the .jar file it belongs to. The name of the .jar file itself, and of the folder structure containing it, must adhere to the same rules as those for .car files.

Alternatively, you can use a flat repository to define external module.xml or module.properties descriptors in a flat folder.

Metamodel

Modules can be manipulated at runtime via their representation as instances of Module. A module's import declarations are represented as instances of Import. The modules object can be used to list the modules currently loaded in the virtual machine.

See also