Note: information on this page refers to Ceylon 1.0, not to the current release.

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. 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 which is 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 interoperability with Java it's possible to convert Java .jar files into Ceylon compatible modules. But for that they need a module descriptor telling Ceylon what it needs to know. There are two possible ways to do this:

  • Using a module.properties file whose format is explained here
  • Or using a JBoss Modules module.xml file whose detailed explanation 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 the folder structure must adhere to the same rules as those for .car files.

Metamodel

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

See also