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