Develop Modules

Testing External Modules

Suppose you are developing a new module for Calamares. It does not live in the main Calamares repository (yet!), so it needs to be built separately. This guide describes how to build and test such an external module. As a large-scale example, it will use the calamares-extensions repository, but you can write your module in its own repository or directory as you see fit.

For the purpose of this guide, we are not going to build as root, so we will be putting everything in a temporary directory; it won't affect the system as a whole unless you do something destructive with Calamares itself, like repartition your disk.

Building Calamares

Build Calamares in debug mode (because new modules will crash; you want good debugging information) and with its own prefix so that it does not interfere with the existing system.

Assuming you already have a clone of the Calamares source this will set the Calamares build up to install to /tmp/calamares, which is safely out-of-the-way. PolKit files are always installed to system directories, so turn them off.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_INSTALL_PREFIX=/tmp/calamares \
      -DINSTALL_POLKIT=OFF \
      ..

Then run make and make install with whatever flags are necessary.

Source for Modules

A module repository can be any kind of source repository and contain any kind of build system, but it is recommended to use CMake and the convenience CMake-modules that Calamares provides. With Calamares installed, a repository for modules can find it:

find_package(Calamares 3.2.26 REQUIRED NO_CMAKE_PACKAGE_REGISTRY)
if (NOT TARGET Calamares::calamares OR NOT TARGET Calamares::calamaresui)
    message(FATAL_ERROR "Calamares found, but missing CMake targets")
endif()

Once Calamares is found, the associated convenience functions are made available; see the Calamares CMake documentation for details. Any single module should be placed in a directory of its own, and that directory should be added to the build through, (e.g. for a module in directory modules/os-nixos/),

calamares_add_module_subdirectory( modules/os-nixos LIST_SKIPPED_MODULES )

Modules that are written in C++ will need a CMakeLists.txt in the module directory that calls calamares_add_plugin() with suitable arguments.

Building Modules

The build instructions for a repository that contains modules that uses CMake are the same as for building Calamares itself. Do a Debug build and pass in the same prefix as Calamares has. Then run make and make install.

Check Calamares Startup

Once Calamares and the modules have been built and installed, try running Calamares. The separate prefix that it has been installed in is not normally in the search path, and it should not even run:

/tmp/calamares/bin/calamares --version

This ought to produce output like the following:

/tmp/calamares/bin/calamares: error while loading shared libraries:
  libcalamaresui.so.3.2.40: cannot open shared object file: No such file or directory

To remedy this, set LD_LIBRARY_PATH in the environment to search in the newly-installed Calamares libraries.

export LD_LIBRARY_PATH=/tmp/calamares/lib

Then re-run /tmp/calamares/bin/calamares --version to check that it can start, or run it with other flags to try a normal startup. Unless your system contains Calamares configuration files in one of the places is searches normally, it will fail to start with messages about missing settings.conf or other missing configurations.