You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Adriaan de Groot 61865a8e11 i18n: fix encoding of dummy translations -- not ASCII, but UTF-8 8 years ago
..
bootloader
displaymanager LightDM: fix type (thanks Kevin Kofler) 8 years ago
dracut
dracutlukscfg Modules: remove another boilerplate module.desc 8 years ago
dummycpp Modules: documentation of CMake, module.desc, etc. 8 years ago
dummyprocess
dummypython Python: separate description of dummy module from docs of run() 8 years ago
dummypythonqt i18n: fix encoding of dummy translations -- not ASCII, but UTF-8 8 years ago
finished Modules: remove boilerplate module.desc 8 years ago
fstab Fix unknown partition-type Fat32 at mount and in fstab 8 years ago
grubcfg
hwclock Python: tidy description of hwclock module 8 years ago
initcpio
initcpiocfg
initramfs
initramfscfg
interactiveterminal Modules: remove boilerplate module.desc 8 years ago
keyboard Modules: remove boilerplate module.desc 8 years ago
license Modules: remove boilerplate module.desc 8 years ago
locale Modules: remove boilerplate module.desc 8 years ago
localecfg
luksbootkeyfile
luksopenswaphookcfg
machineid
mount Fix unknown partition-type Fat32 at mount and in fstab 8 years ago
netinstall Modules: remove boilerplate module.desc 8 years ago
networkcfg
packages
partition Merge branch 'simplify-module-desc' 8 years ago
plymouthcfg
removeuser RemoveUser: fix bad PEP8-ing 8 years ago
services
summary Modules: remove boilerplate module.desc 8 years ago
umount
unpackfs Python: move unsquash documentation to the config file 8 years ago
users i18n: mark non-translatable string as such 8 years ago
webview Merge branch 'simplify-module-desc' 8 years ago
welcome Merge branch 'simplify-module-desc' 8 years ago
CMakeLists.txt
README.md Modules: documentation of CMake, module.desc, etc. 8 years ago
globalStorage.yaml
testmodule.py

README.md

Calamares modules

Calamares modules are plugins that provide features like installer pages, batch jobs, etc. An installer page (visible to the user) is called a "view", while other modules are "jobs".

Each Calamares module lives in its own directory.

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

Module types

There are two types of Calamares module:

  • viewmodule, for user-visible modules. These may be in C++, or PythonQt.
  • jobmodule, for not-user-visible modules. These may be done in C++, Python, or as external processes.

Module interfaces

There are three (four) interfaces for Calamares modules:

  • qtplugin,
  • python (jobmodules only),
  • pythonqt (optional),
  • process (jobmodules only).

Module directory

Each Calamares module lives in its own directory. The contents of the directory depend on the interface and type of the module.

Module descriptor

A Calamares module must have a module descriptor file, named module.desc. For C++ (qtplugin) modules using CMake as a build- system and using the calamares_add_plugin() function -- this is the recommended way to create such modules -- the module descriptor file is optional, since it can be generated by the build system. For other module interfaces, the module descriptor file is required.

The module descriptor 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.

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.

C++ modules

Currently the recommended way to write a module which exposes one or more installer pages (viewmodule) is through a C++ and Qt plugin. Viewmodules must 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 CMakeLists.txt with a calamares_add_plugin call. It will be picked up automatically by our CMake magic. The module.desc file is optional.

Python modules

Modules may use one of the python interfaces, which may be present in a Calamares installation (but also may not be). These modules must have a module.desc file. The Python script must implement one or more of the Python interfaces for Calamares -- either the python jobmodule interface, or the experimental pythonqt job- and viewmodule interfaces.

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.

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 to match the C++ identifier convention.

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

Python Jobmodule

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

PythonQt Jobmodule

A PythonQt jobmodule implements the experimental Job interface by defining a subclass of something.

PythonQt Viewmodule

A PythonQt viewmodule implements the experimental View interface by defining a subclass of something.

Process jobmodules

A process jobmodule runs a (single) command. The interface is "process", while the module type must be "job" or "jobmodule".

The key command should have a string as value, which is passed to the shell -- remember to quote it properly.