calamares/src/modules

Calamares modules

Calamares modules are plugins that provide features like installer pages, batch jobs, etc. Each Calamares module lives in its own directory.

All modules are installed in $DESTDIR/lib/calamares/modules.

Module directory and descriptor

A Calamares module must have a module descriptor file, named module.desc, this file must be placed in the module's directory. The module descriptor file is a YAML 1.2 document which defines the module's name, type, interface and possibly other properties. The name of the module as defined in module.desc must be the same as the name of the module's directory.

There are two types of Calamares module:

• viewmodule,
• jobmodule.

There are three interfaces for Calamares modules:

• qtplugin,
• python,
• process.

Module-specific configuration

A Calamares module may read a module configuration file, named <modulename>.conf. If such a file is present in the module's directory, it is shipped as a default configuration file. The module configuration file, if it exists, is a YAML 1.2 document which contains a YAML map of anything. All default module configuration files are installed in $DESTDIR/share/calamares/modules but can be overridden by files with the same name placed manually (or by the packager) in /etc/calamares/modules.

Qt plugin viewmodules

Currently the only way to write a module which exposes one or more installer pages (viewmodule) is through a Qt plugin. Viewmodules should implement Calamares::ViewStep. They can also implement Calamares::Job to provide jobs.

To add a Qt plugin module, put it in a subdirectory and make sure it has a module.desc and a CMakeLists.txt with a calamares_add_plugin call. It will be picked up automatically by our CMake magic.

Python and process jobmodules

Batch jobs for Calamares can be written as Python scripts or as generic commands (shell scripts, external programs, etc.). To add a Python or process jobmodule, put it in a subdirectory and make sure it has a module.desc. It will be picked up automatically by our CMake magic.

CMakeLists.txt is not used for Python and process jobmodules.

A Python jobmodule is a Python program which imports libcalamares and has a function run() as entry point. run() must return None if everything went well, or a tuple (str,str) with an error message and description if something went wrong.

Calamares offers a Python API for module developers, the core Calamares functionality is exposed as libcalamares.job for job data, libcalamares.globalstorage for shared data and libcalamares.utils for generic utility functions. Documentation is inline.

All code in Python job modules must obey PEP8, the only exception are libcalamares.globalstorage keys, which should always be camelCaseWithLowerCaseInitial.

For testing and debugging we provide the testmodule.py script which fakes a limited Calamares Python environment for running a single jobmodule.