Installer YCP modules API documentation

This document describes a general API for the installation modules.
It does not define strict rules, but some hints and reasoning for module implementors.

A module should be written like a class in an object oriented design. It should keep most information internally and only reveal the functionality, not the implementation.

Persistent data

For persistent information, the module must be able to save and restore it's internal state.
This state information should be kept to a minimum. Do not save computable data, re-compute the data from its basic components instead.

/etc/sysconfig

Try to use a file in /etc/sysconfig for the persistent data. Only use YaST2 specific files, if the information is YaST2 specific and can't be re-generated from the sysconfig file.

Constructor

The constructor should set the module to a defined state.
For modules with persistent data, this data should be re-generated in the constructor. Do *not* call functions in the constructor which might require user-interaction (i.e. loading of kernel modules, since it must be confirmed in 'manual mode') or which need too much time (like loading of scsi modules, this can take up to 10 seconds !). If such functions are needed, put them in a 'Probe' or 'Init' function and document it.

See the Mouse module as an example.

Special case: Configuration System for AutoYaST2

Some modules are now being re-used in the configuration system used to create control files for auto-installation.
To avoid probing and reading data from the running system when configuring a control file for different system, please use the config mode: Mode::config.

API functions

In order to distinguish between global and module-local functions, all global functions and variables start with an upper-case letter.
Ideally, all functions should work with consistent syntactic and semantic values. For example, all external language data is based on the ISO codes ("de_DE", "en_US", etc.).

Check

If the module state depends on (configurations of) other modules, a re-configuration might be needed.
The Check function takes care of such dependencies and returns 1 if the re-configuration changed the internal state previously defined by Set.
If the configuration is unchanged, Check should return 0.

There's no need to return true if the previous state was automatically defined (either by the Constructor or by probing). It's only needed to inform the user who manually defined the configuration.

The Check function should also determine if the current configuration is consistent and return 2 if it's not. E.g. the package selection depends on partitioning and requires user interaction if the partition is too small for the packages.

Selection

The Selection function is used to build up a selection list for the user. Therefore, it should contain translated, user-readable strings.
A good approach is to return a map, where the key is an (internal) identifier and the value is the translated string.
Other solutions are possible, see the Language module.

Set

The Set function effectively changes the running system according to the parameter passed. It does not change any configuration files, this is done with the Save function.

Probe

If the constructor can't do any probing (see Constructor above), a separate probing function should be supplied.
This is done in the Mouse module since USB mice required some additional kernel modules.

Save

The Save function stores the current configuration (defined by the last call to Set) to the system.
If possible, an appropriate file below /etc/sysconfig should be used.
If unsure, login to redhat.suse.de or ask on yast2-hacker.


Last changed 13-12-2001 11:21
Written by Klaus Kämpf