Permalink
..
Failed to load latest commit information.
bootloader [modules] Minor documentation work on modules a-g Jun 26, 2018
contextualprocess Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
displaymanager [modules] Minor documentation work on modules a-g Jun 26, 2018
dracut Documentation: change http links to GitHub to https Dec 20, 2017
dracutlukscfg Documentation: change http links to GitHub to https Dec 20, 2017
dummycpp [modules] Minor documentation work on modules a-g Jun 26, 2018
dummyprocess Add option to run process jobmodules in chroot. Aug 12, 2014
dummypython [modules] Minor documentation work on modules a-g Jun 26, 2018
dummypythonqt i18n: [dummypythonqt] Automatic merge of Transifex translations Aug 6, 2018
finished Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
fstab [modules] Documentation for fstab, grubcfg, mkinitcpio Jun 26, 2018
grubcfg [modules] Documentation for fstab, grubcfg, mkinitcpio Jun 26, 2018
hwclock Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
initcpio [modules] Documentation for fstab, grubcfg, mkinitcpio Jun 26, 2018
initcpiocfg Merge branch 'kpmcore-3.2' Jan 2, 2018
initramfs Documentation: change http links to GitHub to https Dec 20, 2017
initramfscfg Documentation: change http links to GitHub to https Dec 20, 2017
interactiveterminal [interactiveterminal] Make optional if requirements not met May 26, 2018
keyboard Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
license Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
locale Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
localecfg [localecfg] Be slightly more conservative interpreting comments Jun 20, 2018
luksbootkeyfile Documentation: change http links to GitHub to https Dec 20, 2017
luksopenswaphookcfg [modules] Configuration documentation for mount and luksopenswaphookcfg Jun 26, 2018
machineid Documentation: change http links to GitHub to https Dec 20, 2017
mount [modules] Configuration documentation for mount and luksopenswaphookcfg Jun 26, 2018
netinstall Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
networkcfg Documentation: change http links to GitHub to https Dec 20, 2017
openrcdmcryptcfg Documentation: change http links to GitHub to https Dec 20, 2017
packages [packages]: Implement update_system for pkcon, yum, dnf Jun 18, 2018
partition [partition] fix build with latest kpmcore. Aug 12, 2018
plasmalnf Copyright: fix bad email address Jun 15, 2018
plymouthcfg Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
preservefiles [preservefiles] Mark this as an emergency module Jun 15, 2018
removeuser [removeuser] Minor documentation Jun 26, 2018
services-openrc [services-openrc] Introduce *mandatory* subkey Jun 27, 2018
services-systemd [services-systemd] Follow the flexible example of openrc Jun 27, 2018
shellprocess Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
summary Documentation: change http links to GitHub to https Dec 20, 2017
tracking Copyright: fix bad email address Jun 15, 2018
umount [umount] Make a pretty_name() Feb 20, 2018
unpackfs finally !must! never fail unhandled Dec 26, 2017
users Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
webview Documentation: change http links to GitHub to https Dec 20, 2017
welcome Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
CMakeLists.txt CMake: improve error-handling for USE_* Jun 26, 2018
README.md [libcalamaresui] Adjust the emergency-ness of modules Jun 15, 2018
globalStorage.yaml Consistency: calamares_main ==> run; global_storage => globalStorage Jul 25, 2014
test_conf.cpp Copyright: update copyright lines on files touched in 2018 Jun 15, 2018
testmodule.py Documentation: change http links to GitHub to https Dec 20, 2017

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 descriptors must have the following keys:

  • name (an identifier; must be the same as the directory name)
  • type ("job" or "view")
  • interface (see below for the different interfaces; generally we refer to the kinds of modules by their interface)

Module descriptors may have the following keys:

  • required unimplemented (a list of modules which are required for this module to operate properly)
  • emergency (a boolean value, set to true to mark the module as an emergency module)

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. For all kinds of Python jobs, the key script must be set to the name of the main python file for the job. This is almost universally "main.py".

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.

Emergency Modules

Only C++ modules and job modules may be emergency modules. If, during an exec step in the sequence, a module fails, installation as a whole fails and the install is aborted. If there are emergency modules in the same exec block, those will be executed before the installation is aborted. Non-emergency modules are not executed.

If an emergency-module fails while processing emergency-modules for another failed module, that failure is ignored and emergency-module processing continues.

Use the EMERGENCY keyword in the CMake description of a C++ module to generate a suitable module.desc.

A module that is marked as an emergency module in its module.desc must also set the emergency key to true in its configuration file. If it does not, the module is not considered to be an emergency module after all (this is so that you can have modules that have several instances, only some of which are actually needed for emergencies.