From 88d5a301c94aebf861d3c09e1ee01350454df95b Mon Sep 17 00:00:00 2001 From: Teo Mrnjavac Date: Wed, 6 Aug 2014 15:50:39 +0200 Subject: [PATCH] Update Calamares modules documentation. --- src/modules/README.md | 54 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/src/modules/README.md b/src/modules/README.md index 60eaec82d..386d15a48 100644 --- a/src/modules/README.md +++ b/src/modules/README.md @@ -1,18 +1,60 @@ -Calamares modules directory +Calamares modules === -Calamares modules are plugins that provide features like installer pages, batch jobs, etc. Each Calamares module lives in its own directory. +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 `.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. +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. +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. +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. -All code in Python job modules must obey PEP8, the only exception are `libcalamares.globalstorage` keys, which should always be camelCaseWithLowerCaseInitial. \ No newline at end of file +`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. \ No newline at end of file