Modules: documentation of CMake, module.desc, etc.

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 <view|job>
+#   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 )

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
+# Module types
-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,
+* viewmodule, for user-visible modules. These may be in C++, or PythonQt.
-* jobmodule.
+* 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,
+* python (jobmodules only),
-* process.
+* pythonqt (optional),
+* process (jobmodules only).
 
-### Module-specific configuration
+# Module directory
-A Calamares module *may* read a module configuration file, named `<modulename>.conf`. If such a file is present in the
+
+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 `<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.
+The module configuration file, if it exists, is a YAML 1.2 document
-All default module configuration files are installed in `$DESTDIR/share/calamares/modules` but can be overridden by
+which contains a YAML map of anything.
-files with the same name placed manually (or by the packager) in `/etc/calamares/modules`.
 
-### 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.
+## C++ modules
-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
+Currently the recommended way to write a module which exposes one or more
-`calamares_add_plugin` call. It will be picked up automatically by our CMake magic.
+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.).
+Modules may use one of the python interfaces, which may be present
-To add a Python or process jobmodule, put it in a subdirectory and make sure it has a `module.desc`.
+in a Calamares installation (but also may not be). These modules must have
-It will be picked up automatically by our CMake magic.
+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.
+Calamares offers a Python API for module developers, the core Calamares
-`run()` must return `None` if everything went well, or a tuple `(str,str)` with an error message and description if
+functionality is exposed as `libcalamares.job` for job data,
-something went wrong.
+`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`
+All code in Python job modules must obey PEP8, the only exception are
-for job data, `libcalamares.globalstorage` for shared data and `libcalamares.utils` for generic utility functions.
+`libcalamares.globalstorage` keys, which should always be
-Documentation is inline.
+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
+For testing and debugging we provide the `testmodule.py` script which
-always be camelCaseWithLowerCaseInitial.
+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. 

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"