napcok/calamares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: touch-ups and typos

Browse Source
This commit is contained in:
Adriaan de Groot 2021-11-03 13:51:17 +01:00
parent 2800128a8d
commit 74d65d8338
1 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/modules/README.md
View File

@ -14,9 +14,9 @@ Each Calamares module lives in its own directory.
All modules are installed in `$DESTDIR/lib/calamares/modules`.
There are two **types** of Calamares module:
* viewmodule, for user-visible modules. These use C++ and QWidgets or QML
* viewmodule, for user-visible modules. These use C++ and either Widgets or QML
* jobmodule, for not-user-visible modules. These may be done in C++,
Python, or as external processes.
Python, or as external processes (external processes not recommended).
A viewmodule exposes a UI to the user.
@ -39,7 +39,7 @@ 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, if required, is 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
@ -63,6 +63,7 @@ Module descriptors for process modules **must** have the following key:
Module descriptors for process modules **may** have the following keys:
- *timeout* (how long, in seconds, to wait for the command to run)
- *chroot* (if true, run the command in the target system rather than the host)
Note that process modules are not recommended.
Module descriptors **may** have the following keys:
- *emergency* (a boolean value, set to true to mark the module
@ -134,7 +135,7 @@ in `/etc/calamares/modules`.
During the *exec* phase of an installation, where jobs are run and
things happen to the target system, there is a running progress bar.
It goes from 0% to 100% while all of the jobs for that exec phase
are run. Generally, one module creates on job, but this varies a little
are run. Generally, one module creates one job, but this varies a little
(e.g. the partition module can spawn a whole bunch of jobs to
deal with each disk, and the users module has separate jobs for
the regular user and the root user).
@ -162,7 +163,10 @@ visible.
It is also possible to set a weight on a specific module **instance**,
which can be done in `settings.conf`. This overrides any weight
set in the module descriptor.
set in the module descriptor. Doing so is the recommended approach,
since that is where the specific installation-process is configured;
it is possible to take the whole installation-process into account
for determining the relative weights there.
## C++ modules
@ -252,7 +256,7 @@ it has a `module.desc`. It will be picked up automatically by our CMake magic.
For all kinds of Python jobs, the key *script* must be set to the name of
the main python file for the job. This is almost universally `main.py`.
`CMakeLists.txt` is *not* used for Python and process jobmodules.
`CMakeLists.txt` is *not* used for Python jobmodules.
Calamares offers a Python API for module developers, the core Calamares
functionality is exposed as `libcalamares.job` for job data,
@ -309,6 +313,8 @@ passed to the shell -- remember to quote it properly. It is generally
recommended to use a *shellprocess* job module instead (less configuration,
easier to have multiple instances).
`CMakeLists.txt` is *not* used for process jobmodules.
## Testing Modules