diff --git a/CMakeModules/CalamaresAddPlugin.cmake b/CMakeModules/CalamaresAddPlugin.cmake index 72ccf17df..560638de8 100644 --- a/CMakeModules/CalamaresAddPlugin.cmake +++ b/CMakeModules/CalamaresAddPlugin.cmake @@ -1,3 +1,25 @@ +# Convenience function for creating a C++ (qtplugin) module for Calamares. +# This function provides cmake-time feedback about the plugin, adds +# targets for compilation and boilerplate information, and creates +# a module.desc with standard values if none is provided (which only +# happens for very unusual plugins). +# +# Usage: +# +# calamaers_add_plugin( +# module-name +# TYPE +# EXPORT_MACRO macro-name +# SOURCES source-file... +# UI ui-file... +# LINK_LIBRARIES lib... +# LINK_PRIVATE_LIBRARIES lib... +# COMPILE_DEFINITIONS def... +# RESOURCES resource-file +# [NO_INSTALL] +# [SHARED_LIB] +# ) + include( CMakeParseArguments ) include( CalamaresAddLibrary ) include( CMakeColors ) diff --git a/src/modules/README.md b/src/modules/README.md index 386d15a48..80a8ffbd9 100644 --- a/src/modules/README.md +++ b/src/modules/README.md @@ -1,60 +1,119 @@ -Calamares modules -=== +# 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". -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. +# Module types There are two types of Calamares module: -* viewmodule, -* jobmodule. +* 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. -There are three interfaces for Calamares modules: +# Module interfaces + +There are three (four) interfaces for Calamares modules: * qtplugin, -* python, -* process. +* python (jobmodules only), +* pythonqt (optional), +* process (jobmodules only). -### Module-specific configuration -A Calamares module *may* read a module configuration file, named `.conf`. If such a file is present in the +# 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 `.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`. +The module configuration file, if it exists, is a YAML 1.2 document +which contains a YAML map of anything. -### Qt plugin viewmodules +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`. -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. +## C++ modules -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. +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 and process jobmodules +## Python modules -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. +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. -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. -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. -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. + +### 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. -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 diff --git a/src/modules/dummycpp/module.desc b/src/modules/dummycpp/module.desc index 7f29e512e..11b9c500c 100644 --- a/src/modules/dummycpp/module.desc +++ b/src/modules/dummycpp/module.desc @@ -1,5 +1,18 @@ # Module metadata file for dummycpp job +# +# The metadata for C++ (qtplugin) plugins is almost never interesting: +# the CMakeLists.txt should be using calamares_add_plugin() which will +# generate the metadata file during the build. Only C++ plugins that +# have strange settings should have a module.desc (non-C++ plugins, +# on the other hand, must have one, since they don't have CMakeLists.txt). +# # Syntax is YAML 1.2 +# +# All four keys are mandatory. For C++ (qtplugin) modules, the interface +# value must be "qtplugin"; type is one of "job" or "view"; the name +# is the machine-identifier for the module and the load value should +# be the filename of the library that contains the implementation. +# --- type: "job" name: "dummycpp"