Templates

Updated 25 January 2021

Introduction

Templates is really fantastic tools for system customization. There is no Calculate Linux without templates. While developing the templates, we have been relying on our many years of experience in Linux/Unix system administration, and the fact that we did not make any significant changes in the syntax over 10 years proves that we made good choices.

What are templates?

• For users
  Calculate Linux is a rolling-release distribution. Meaning that once you install the system, you will be able to update it continuously throughout its lifetime. In the meantime, packages can change their versions, names and configuration file formats. Templates used by Calculate utilities help to maintain the system settings up to date with each update of packages.

• For admins
  Updating configuration files often involves editing only a few lines in them. Identifying the changes that are being made, and understanding why they are being made, becomes difficult over time. Besides, installing a new version of a package may overwrite your previous changes. As a result, the only way to keep your system up and running would be to either discard updates or completely freeze your settings.

Fortunately, we have templates. They are integrated with the package manager, involved in the configuration file update process. All changes in the system are easily readable in templates, as the latter only contain the differences from the initial settings. Calculate utilities merge your settings with the initial ones, allowing for the format of configuration files.

Features

• Integrated with the main OS events and actions performed by Calculate Utilities.
• Integrated with the package manager.
• Configuration support for both system files and user data.
• Syntax support for the most popular configuration file formats.
• Support for variables, functions, and conditionals.
• Several ways to write to files, including selective editing of configuration files.
• Multiple storage paths to templates: in the active overlays, in the directories you specify and in /etc.

Templates are configuration files with extended syntax that includes embedded variables, functions, conditional expressions and parameters. While supporting the basic syntax formats of configuration files, templates can modify the given settings without overwriting the file. Templates are used everywhere: they are involved in system configuration at build time and throughout the installation, first start-up, update, and user session configuration processes. They even create the LDAP database.

Templates are closely integrated with the system. They both edit configuration files and link them to packages. When setting up a user session, the templates consider the packages installed in the system, and only configure these. When new programs are installed, they will also be configured at the user level. Profile configuration is flexible and version-specific. The functionality is described in the templates themselves.

You can hardly underestimate what templates do. For example, one of the key differences between Calculate Linux and Gentoo, the procedure for [fixes and migration] (calculate_vs_gentoo) is indeed implemented with templates. At system update time, the migration templates are executed immediately after the Portage and overlay synchronization is complete. This ensures that the system gets all the necessary fixes before installing the packages. With this, the system is always up and running and transitions between versions are made when necessary.

The templates are handled by Calculate Utilities. Templates use variables to define call events and retrieve values. Using parameters and conditional expressions makes it possible to avoid fixed paths in names and paths of templates, thus making the structure of the database flexible and adaptable. This means that you can use multiple paths to sort templates by type, or use a single path where all conditions are listed in the template header.

Formats

The first line of a template may contain the # Calculate header:

# Calculate

This can be followed by single parameters, parameters with values and conditional expressions, combined into one or more conditional blocks "and" (&&) or " or" (||).

A template may only consist of a header:

# Calculate path=/usr/share/pixmaps name=faces link=/usr/share/pixmaps/calculate/breeze symbolic pkg(kde-plasma/breeze)!=&&mergepkg(x11-themes/calculate-icon-theme)>=15-r2

Applying this template will create a symbolic link in ~/usr/share/pixmaps/calculate/breeze, pointing to the /usr/share/pixmaps/faces directory if kde-plasma/breeze and x11-themes/calculate-icon-theme version 15-r2~~ or higher exist and will associate this link with package x11-themes/calculate-icon-theme.

Example 1: Just a template

Create a settings template for sys-libs/ncurses. First you will have to create and fill the template file, ncurses.sh:

# Calculate env=install ac_install_merge==on&&mergepkg(sys-libs/ncurses)!= path=/etc/profile.d comment=#
export LDFLAGS="${LDFLAGS} -ltinfo"

Now reinstall sys-libs/ncurses by running:

Make sure that ~/etc/profile.d contains the ncurses.sh~~ file, filled with the following:

#------------------------------------------------------------------------------
# Modified Calculate Utilities 3.6.4.2
# Processed template files:
# /var/calculate/templates/ncurses.sh
# For modify this file, create /etc/profile.d/ncurses.sh.clt template.
#------------------------------------------------------------------------------
export LDFLAGS="${LDFLAGS} -ltinfo"

Let's take a closer look at the format:

• env=install The env parameter sets the scope of names for variables and functions. By default, the basic variables and functions of the main module from the CU library are used. You can also enable the install module to use system settings variables. To view the variable list, run @cl-core-variables-show --filter install.@ (note the final dot). If a module is absent from the system, the corresponding template will be skipped.
• ac_install_merge==on&mergepkg(sys-libs/ncurses)!= Two conditional expressions written with no space and required for template execution:
• ac_install_merge==on Check for a package configuration action, required for template execution.
• mergepkg(sys-libs/ncurses)!= Check for installed sys-libs/ncurses package. Also returns positive if @cl-setup-system@ is executed.
• path=/etc/profile.d Path to the directory where the configuration file will be saved.
• comment=#
  Since the format of the configuration file has not been specified, it makes sense to add the comment separator symbol, so that Calculate Utilities can store the service information, including the path to the template the file was configured with, and so that later, cl-backup be able to find the file you edited using this header.

Check the template integration with the package manager, one of their main features. To do this, view and filter the list of installed package files:

/etc/profile.d/ncurses.sh

Here you can see that the file created by the template belongs to the sys-libs/ncurses package.

Check the file checksum:

Checking sys-libs/ncurses-6.1-r2 ...
  * 4038 out of 4038 files are good

As you can see, the checksum corresponds to the data of the package manager.

Example 2: Grouping templates

Let's do something that is more complicated. Edit /etc/sysctl.conf to send packages from one network to another. Since you already have a template, group up the templates together to make the syntax simpler. To do this, create a directory with an arbitrary name - for example, ~merge - in /var/calculate/templates:

In this case, the directory is also a template. It has its properties. To describe those, create a file inside, named .calculate_directory, and fill it with the following:

# Calculate append=skip env=install ac_install_merge==on

As you can see, setting the scope of the env=install variables and checking the value of the ac_install_merge==on were copied from the first example. It means that you do not need to do this check in templates stored in this directory. A new parameter, append=skip was also added. Setting this parameter tells the system not to create the directory.

Move the template from the first example to the common directory:

and make its syntax simpler:

# Calculate mergepkg(sys-libs/ncurses)!= path=/etc/profile.d comment=#
export LDFLAGS="${LDFLAGS} -ltinfo"

Create a new template, sysctl.conf, that would contain the following:

# Calculate format=procmail mergepkg(sys-apps/baselayout)!= path=/etc
net.ipv4.ip_forward = 1

Note that the package refers to the sys-apps/baselayot package. To find out which package the file belongs to, run:

 * Searching for /etc/sysctl.conf ... 
sys-apps/baselayout-2.6-r1 (/etc/sysctl.conf)

You can either reinstall sys-apps/baselayout or run the following command to check that the template actually works:

 * Calculate Utilities configuring baselayout system settings ...
 * Calculate Utilities modified the files:  
 *      /etc/sysctl.conf 

Note that only one parameter was edited in /etc/sysctl.conf:

...
net.ipv4.ip_forward = 1
...

Do in the same way for ncurses.sh:

 * Calculate Utilities configurging ncurses system settings...
 * Calculate Utilities modified the files: 
 *      /etc/profile.d/ncurses.sh  

Example 3: A clt template

To make working with templates even easier, we introduced a new clt template. These templates are not located in a dedicated directory, but instead in /etc+, and have a .clt extension. Such templates are easy to use since they have preset path values and usage conditions. At the same time, clt templates have the full functionality of normal templates.

For example, try changing the size of the terminal font by editing the relevant template. To do this, copy the file:

and edit the font size:

...
consolefont="ter-v12n"
...

To see the result, reinstall sys-apps/openrc to which the configuration file belongs:

consolefont="ter-v12n"

This template will rewrite the configuration file completely, without ever telling that a new version was created. That is why we recommend using clt templates, even if you only master some features. Instead of copying the whole of the file, create a template containing only lines:

# Calculate format=openrc
consolefont="ter-v12n"

This template will do the same, but in a more simple and efficient manner. Update to see the result:

consolefont="ter-v12n"

As a result, only one line remains unchanged, and the path to your template was added to the file header. Of course, this is convenient, since the template only lists the parameters you need to change.

As you can see, the syntax of a clt template is quite simple. This was possible because the following settings had been set by default: env=install, ac_install_merge=on, path=/etc/conf.d and name=consolefont.

Conclusion

Please be aware that this is only a brief description of what Calculate templates are.