diff --git a/src/modules/README.md b/src/modules/README.md index 29fa79cff..2f0790863 100644 --- a/src/modules/README.md +++ b/src/modules/README.md @@ -8,27 +8,28 @@ 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: +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 +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: +There are three (four) **interfaces** for Calamares modules: * qtplugin (viewmodules, jobmodules), * python (jobmodules only), * pythonqt (viewmodules, jobmodules, optional), * process (jobmodules only). -# Module directory +## 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 +### Module descriptor A Calamares module must have a *module descriptor file*, named `module.desc`. For C++ (qtplugin) modules using CMake as a build- @@ -55,7 +56,28 @@ Module descriptors **may** have the following keys: - *emergency* (a boolean value, set to true to mark the module as an emergency module) -## Module-specific configuration +### 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 `.conf`. If such a file is present in the @@ -74,6 +96,8 @@ All sample module configuration files are installed in 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 @@ -85,6 +109,8 @@ 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 @@ -119,6 +145,17 @@ 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 + +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 @@ -129,33 +166,18 @@ a subclass of something. A PythonQt viewmodule implements the experimental View interface by defining a subclass of something. +### Python API + +**TODO:** this needs documentation + + + ## Process jobmodules -A process jobmodule runs a (single) command. The interface is "process", -while the module type must be "job" or "jobmodule". +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. It is generally recommended to use -a *shellprocess* job module instead (less configuration, easier to have -multiple instances). - -## 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. +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).