4ae484dbca
- Now that multiple netinstall pages may be supported, it's annoying that they all have the same name. Copy the approach from other modules (e.g. notesQML) of having the sidebar and other labels configured in the config file. |
||
|---|---|---|
| .. | ||
| bootloader | ||
| contextualprocess | ||
| displaymanager | ||
| dracut | ||
| dracutlukscfg | ||
| dummycpp | ||
| dummyprocess | ||
| dummypython | ||
| dummypythonqt | ||
| finished | ||
| fsresizer | ||
| fstab | ||
| grubcfg | ||
| hostinfo | ||
| hwclock | ||
| initcpio | ||
| initcpiocfg | ||
| initramfs | ||
| initramfscfg | ||
| interactiveterminal | ||
| keyboard | ||
| license | ||
| locale | ||
| localecfg | ||
| luksbootkeyfile | ||
| luksopenswaphookcfg | ||
| machineid | ||
| mount | ||
| netinstall | ||
| networkcfg | ||
| notesqml | ||
| oemid | ||
| openrcdmcryptcfg | ||
| packagechooser | ||
| packages | ||
| partition | ||
| plasmalnf | ||
| plymouthcfg | ||
| preservefiles | ||
| rawfs | ||
| removeuser | ||
| services-openrc | ||
| services-systemd | ||
| shellprocess | ||
| summary | ||
| tracking | ||
| umount | ||
| unpackfs | ||
| users | ||
| webview | ||
| welcome | ||
| welcomeq | ||
| CMakeLists.txt | ||
| globalStorage.yaml | ||
| README.md | ||
| test_conf.cpp | ||
| testmodule.py | ||
| testpythonrun.sh | ||
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.
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.
A viewmodule exposes a UI to the user. The PythonQt-based modules are considered experimental (and as of march 2019 may be on the way out again as never-used-much and PythonQt is not packaged on Debian anymore).
There are three (four) interfaces for Calamares modules:
- qtplugin (viewmodules, jobmodules),
- python (jobmodules only),
- pythonqt (viewmodules, jobmodules, 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 for Python and PythonQt modules must have the following key:
- script (the name of the Python script to load, nearly always
main.py)
Module descriptors may have the following keys:
- emergency (a boolean value, set to true to mark the module as an emergency module)
- noconfig (a boolean value, set to true to state that the module has no configuration file; defaults to false)
- requiredModules (a list of modules which are required for this module to operate properly)
Required Modules
A module may list zero (if it has no requirements) or more modules
by name. As modules are loaded from the global sequence in settings.conf,
each module is checked that all of the modules it requires are
already loaded before it. This ensures that if a module needs
another one to fill in globalstorage keys, that happens before
it needs those keys.
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 (see below). 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).
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 can be shipped as a default configuration file.
This only happens if the CMake-time option INSTALL_CONFIG is on.
Modules that have noconfig set to true will not attempt to read a configuration file, and will not warn that one is missing; conversely if noconfig is set to false (or is missing, since the default value is false) if there is no configuration file, a warning is printed during Calamares start-up.
The sample configuration files may work and may be suitable for your distribution, but no guarantee is given about their stability beyond syntactic correctness.
The module configuration file, if it exists, is a YAML 1.2 document which contains a YAML map of anything.
All sample 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
Type: viewmodule, jobmodule Interface: qtplugin
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 not recommended:
nearly all cases can be described in CMake.
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
Type: jobmodule Interface: python
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.
Python API
TODO: this needs documentation
PythonQt modules
Type: viewmodule, jobmodule Interface: pythonqt
The PythonQt modules are considered experimental and may be removed again due to low uptake. Their documentation is also almost completely lacking.
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.
Python API
TODO: this needs documentation
Process jobmodules
Type: jobmodule Interface: process
A process jobmodule runs a (single) command. The interface is process, while the module type must be job or jobmodule.
The module-descriptor key command should have a string as value, which is passed to the shell -- remember to quote it properly. It is generally recommended to use a shellprocess job module instead (less configuration, easier to have multiple instances).