source: calamares/trunk/fuentes/src/modules/README.md @ 7538

Last change on this file since 7538 was 7538, checked in by kbut, 13 months ago

sync with github

File size: 4.9 KB
Line 
1# Calamares modules
2
3Calamares modules are plugins that provide features like installer pages,
4batch jobs, etc. An installer page (visible to the user) is called a "view",
5while other modules are "jobs".
6
7Each Calamares module lives in its own directory.
8
9All modules are installed in `$DESTDIR/lib/calamares/modules`.
10
11# Module types
12
13There are two types of Calamares module:
14* viewmodule, for user-visible modules. These may be in C++, or PythonQt.
15* jobmodule, for not-user-visible modules. These may be done in C++,
16  Python, or as external processes.
17
18# Module interfaces
19
20There are three (four) interfaces for Calamares modules:
21* qtplugin,
22* python (jobmodules only),
23* pythonqt (optional),
24* process (jobmodules only).
25
26# Module directory
27
28Each Calamares module lives in its own directory. The contents
29of the directory depend on the interface and type of the module.
30
31## Module descriptor
32
33A Calamares module must have a *module descriptor file*, named
34`module.desc`. For C++ (qtplugin) modules using CMake as a build-
35system and using the calamares_add_plugin() function -- this is the
36recommended way to create such modules -- the module descriptor
37file is optional, since it can be generated by the build system.
38For other module interfaces, the module descriptor file is required.
39
40The module descriptor file must be placed in the module's directory.
41The module descriptor file is a YAML 1.2 document which defines the
42module's name, type, interface and possibly other properties. The name
43of the module as defined in `module.desc` must be the same as the name
44of the module's directory.
45
46Module descriptors must have the following keys:
47- *name* (an identifier; must be the same as the directory name)
48- *type* ("job" or "view")
49- *interface* (see below for the different interfaces; generally we
50  refer to the kinds of modules by their interface)
51
52## Module-specific configuration
53
54A Calamares module *may* read a module configuration file,
55named `<modulename>.conf`. If such a file is present in the
56module's directory, it is shipped as a *default* configuration file.
57The module configuration file, if it exists, is a YAML 1.2 document
58which contains a YAML map of anything.
59
60All default module configuration files are installed in
61`$DESTDIR/share/calamares/modules` but can be overridden by
62files with the same name placed manually (or by the packager)
63in `/etc/calamares/modules`.
64
65## C++ modules
66
67Currently the recommended way to write a module which exposes one or more
68installer pages (viewmodule) is through a C++ and Qt plugin. Viewmodules must
69implement `Calamares::ViewStep`. They can also implement `Calamares::Job`
70to provide jobs.
71
72To add a Qt plugin module, put it in a subdirectory and make sure it has
73a `CMakeLists.txt` with a `calamares_add_plugin` call. It will be picked
74up automatically by our CMake magic. The `module.desc` file is optional.
75
76## Python modules
77
78Modules may use one of the python interfaces, which may be present
79in a Calamares installation (but also may not be). These modules must have
80a `module.desc` file. The Python script must implement one or more of the
81Python interfaces for Calamares -- either the python jobmodule interface,
82or the experimental pythonqt job- and viewmodule interfaces.
83
84To add a Python or process jobmodule, put it in a subdirectory and make sure
85it has a `module.desc`. It will be picked up automatically by our CMake magic.
86For all kinds of Python jobs, the key *script* must be set to the name of
87the main python file for the job. This is almost universally "main.py".
88
89`CMakeLists.txt` is *not* used for Python and process jobmodules.
90
91Calamares offers a Python API for module developers, the core Calamares
92functionality is exposed as `libcalamares.job` for job data,
93`libcalamares.globalstorage` for shared data and `libcalamares.utils` for
94generic utility functions. Documentation is inline.
95
96All code in Python job modules must obey PEP8, the only exception are
97`libcalamares.globalstorage` keys, which should always be
98camelCaseWithLowerCaseInitial to match the C++ identifier convention.
99
100For testing and debugging we provide the `testmodule.py` script which
101fakes a limited Calamares Python environment for running a single jobmodule.
102
103### Python Jobmodule
104
105A Python jobmodule is a Python program which imports libcalamares and has a
106function `run()` as entry point. The function `run()` must return `None` if
107everything went well, or a tuple `(str,str)` with an error message and
108description if something went wrong.
109
110### PythonQt Jobmodule
111
112A PythonQt jobmodule implements the experimental Job interface by defining
113a subclass of something.
114
115### PythonQt Viewmodule
116
117A PythonQt viewmodule implements the experimental View interface by defining
118a subclass of something.
119
120## Process jobmodules
121
122A process jobmodule runs a (single) command. The interface is "process",
123while the module type must be "job" or "jobmodule".
124
125The key *command* should have a string as value, which is passed to the
126shell -- remember to quote it properly.
127
Note: See TracBrowser for help on using the repository browser.