4.5 Templates Variables¶

4.5 Templates Variables
Introduction
Types of variables
Action variables
Events
Variable values
Edit a variable's value
Modifying a variable's value from the command line
Modifying a variable's value by editing the configuration file
Use variables
Putting a value in a template
Passing the value to a function
Conditions in template headers
Conditional blocks

Introduction¶

Calculate utilities contain variables which may be used in templates. Each utility package has its own set of variables. Though variables belong to different packages, their names are unique. If you want, for instance, to view all variables belonging to a package (calculate-install in the exemple below) along with their values, execute:

# cl-install -v

You'll get the list of library variables:

------------------------------ ------ ----------
        Variable name           Mode    Value
------------------------------ ------ ----------
cl_autoupdate_set              [r]    off
cl_chroot_path                 [w]    /
...

...and install variables:

------------------------------ ------ ----------
        Variable name           Mode    Value
------------------------------ ------ ----------
ac_install_flash               [r] 
ac_install_merge               [r]    up
ac_install_system              [r]    up
cl_distfiles_path              [w]    /var/calculate/remote/distfiles
cl_image                       [r]    /var/calculate/remote/linux/cld-13.6-x86_64.iso
...

You can see that the utility has printed all variables which belong to calculate-install itself as well as to the calculate-lib package and that can be thus accessed by other packages.

Types of variables¶

For convenience, the type of a variable is indicated within its name; the package name may be used too, as well as the type of the returned value.

There are seven variable types all in all:

ac stands for Action variables
cl stands for Common settings
hr stands for Hardware settings
ld stands for LDAP attributes
os stands for OS-relative settings
sr stands for Services settings
ur stands for User data

E.g., the cl_install_autoupdate_set variable refers to common settings, belongs to the calculate-install package and is set either to on or <<off>.

Action variables¶

Calculate Utilities' packages include configuration templates, which are grouped by action, such as configure a user profile, configure a package at install time, etc. To determine which template(s) should be applied, action variables are used:

calculate-install

ac_install_flash configures the bootable USB Flash
ac_install_merge configures packages
ac_install_system configures the system while installing on HDD or USB-HDD

calculate-desktop

ac_desktop_desktop configures options in the user profile which do not depend on system configuration
ac_desktop_live configures options in the user profile which depend on system configuration
ac_desktop_install configures the calculate-desktop package
ac_desktop_merge configures a package

calculate-client

ac_client_domain configures a client in the domain
ac_client_merge configures a package

calculate-builder

ac_builder_iso configures the ISO image
ac_builder_squash configures the Squash image

calculate-assemble

ac_assemble_prepare configures the system to be built
ac_assemble_setup configures the system at build time

Events¶

How Calculate Utilities attribute values to action variables and apply templates depends on events (such as installing a package, for example).

Listed below are events and respective values for action variables, specified with a double equals sign, as required in template conditionals:

System setup

This is performed at the first bootup, but also when booting from a LiveCD, an USB-Flash or an USB-HDD, with the cl-install --startup and cl-template -l all commands.

ac_client_domain==up/down
ac_client_merge==up
ac_install_merge==up
ac_desktop_install==up
ac_desktop_merge==up

Hard disk installation

This is performed at system install, with the cl-install command.

ac_install_merge==up
ac_install_system==up

USB Flash installation

This is performed with the <cl-install>> command at system install if the USB-Flash is specified as the target media.

ac_install_flash==up

Builder mode installation

This is performed with launching cl-install --build.

ac_install_merge==up
ac_install_system==up

Package installation

This is performed when installing a package with emerge package_name.

ac_install_merge==up
ac_desktop_merge==up
ac_desktop_install==up
ac_desktop_desktop==up
ac_desktop_live==up
ac_client_domain==up/down
ac_client_merge==up

User profile setup

This is performed when launching cl-desktop user_login at user login.

ac_desktop_desktop==up
ac_desktop_live==up

This is performed when launching cl-desktop --startup user_login at user login.

ac_desktop_live==up

Making a Squash image

This is performed with the cl-image iso or cl-image squash commands before packing up the Squash image.

ac_builder_squash==up

Making an ISO image

This is performed before creating the ISO image with the cl-image iso command.

ac_builder_iso==up

Joining a domain

This is performed with cl-client host command when the client joins a domain.

ac_client_domain==up
ac_client_merge==up

Leaving a domain

This is performed when your computer leaves a domain, with cl-client -r.

ac_client_domain==down
ac_client_merge==up

Preparing the build environment

This is performed with the cl-assemble command, when your distribution is getting ready for build, once the Stage image has been unpacked.

ac_assemble_prepare==up

System setup at build time

This is performed with the<<cl-assemble>> command, when your distribution is getting ready for build, once the calculate overlay has been added.

ac_assemble_setup==up

System update at build time

This is performed with the cl-make -u or cl-make -U command before merging packages to the system to be built.

ac_assemble_prepare==up
ac_assemble_setup==up

Installation of calculate-desktop

This is performed when you install the calculate-desktop package with cl-desktop --install.

ac_desktop_install==up
ac_desktop_merge==up

Installation of calculate-client

This is performed when you install the calculate-client package with cl-client --install.

ac_client_domain==up/down
ac_client_merge==up

Removal of calculate-desktop

This is performed when you remove the calculate-desktop package with cl-desktop --uninstall.

ac_desktop_install==down
ac_desktop_merge==up

Removal of calculate-client

This is performed when you remove the calculate-client package with cl-client --uninstall.

ac_client_domain==down
ac_client_merge==up

Variable values¶

Variables accept values of several types, namely:

replacement values, assigned to a variable in the template file.
For instance:

os_locale_locale               [r] ru_RU.UTF-8
os_net_allow                   [r] 10.0.0.0/24
os_net_ip                      [r] 10.0.0.131
os_x11_video_drv               [r] radeon

regexp values, found in conditionals.
For instance:

cl_uuid_set                    [r] on
hr_video                       [r] ati
os_install_linux_system        [r] desktop
os_install_locale_language     [r] ru

data, which return the current system settings.
For instance:
```
os_net_interfaces_info         [r] eth0 (DHCP)
```

arrays of values, used by other variables or functions.
For instance:

cl_migrate_user                [r] ['root', 'guest']
os_install_disk_format         [r] ['swap', 'reiserfs', 'reiserfs', '', 'reiserfs']
os_install_disk_id             [r] ['82', '83', '83', '5', '83']
os_install_disk_mount          [r] ['swap', '/', '', '', '/var/calculate']

Note that this classification is purely conventional: one value may correspond to several types.

Edit a variable's value¶

When a variable is called, the program determines its value according to the system settings as well as the values of other variables. Some of these can be changed; such variables are marked with "w". Other, read-only variables are marked with "r". For instance:

cl_ver                         [r] 2.2.11
os_install_x11_composite       [w] off

You can change a value from the command line, by specifying relevant utility options, or by saving the value in the configuration file. If the value is modified in both ways, the command line instruction will have the priority.

Modifying a variable's value from the command line¶

The syntax for changing a variable value is --set variable=value.

For instance:

# cl-install -v --filter os_install_net_hostname --set os_install_net_hostname=mylinux

You got the list of install variables:

----------------------- ------ ----------
     Variable name       Mode    Value
----------------------- ------ ----------
os_install_net_hostname [w]    mylinux

Modifying a variable's value by editing the configuration file¶

You can assign new values to variables in the calculate.env file. Paths to the configuration files are stored in cl_env_path:

cl_env_path             [r]    ['/etc/calculate/calculate.env', '/var/calculate/calculate.env', '/var/calculate/remote/calculate.env']

The latter files have the priority. It means that the variable you have edited in /var/calculate/remote/calculate.env will override any other values.

An example of the calculate.env file is listed below:

[install]
os_install_ntp = ntp0.zenon.net

Note that the variable is the [install] section, i.e. variables belonging to the calculate-install package can see it.

Use variables¶

Variables are behind all templates, their values define system settings depending on the current state of your hardware and determine how the system should work. Below we will see all possible ways of using variables with Calculate templates.

Putting a value in a template¶

To put a variable's value in a template, use the following syntax: #-variable_name-#.

For instance, to setup the Xorg server:

Modes "#-os_install_x11_resolution-#"

Passing the value to a function¶

The value of a variable put between #--# is calculated and put in the template in the first place. If the variable is among a function's options, the function will be executed based on this precalculated value.

For instance:

<entry name="paned_size" type="int" value="#-sum(ysize,,#-os_x11_height-# / 3)-#"/>

In this example, the sum function receives three values: the ysize option, an empty option and the formula for finding the os_x11_height variable's contents (screen resolution in height), divided by 3.

Conditions in template headers¶

A template header may include conditional statements: if they are true, the template will be applied to set the system, otherwise it will be overridden.

Here is an example of a template header containing a condition:

# Calculate os_install_linux_system==server

Conditional blocks¶

As for now, simple syntax is supported for conditional blocks. A conditional statement of one or more variables (or functions) should begin with #? and end with #. Then comes a text block, followed by the first condition variable put between # signs, such as in:

#?hr_laptop==#
numlock on
#hr_laptop#

#?os_locale_language==ru&&pkg(media-gfx/cldx-themes)!=#
current_theme   calculate_en
#os_locale_language#

In the second example, the conditional includes the pkg() function, and its value is compared to null. The condition is true if English is a system language and if the package media-gfx/cldx-themes is installed.