Templates

Updated 2 April 2019

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.

If you consider the format, templates are configuration files with extended syntax, including embedded variables, functions, conditionals 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:

/var/calculate/templates/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:

emerge -a1 ncurses

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

/etc/profile.d/ncurses.sh

#------------------------------------------------------------------------------
# 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)!=
    Два условных выражения, записанных без пробела и обязательных для выполнения шаблона:
  • ac_install_merge==on
    Проверка на выполнение действия по настройке пакета - обязательное условие выполнения шаблона.
  • mergepkg(sys-libs/ncurses)!=
    Проверка на выполнение установки пакета sys-libs/ncurses. При выполнении @cl-setup-system@ условие также даст положительный результат.
  • path=/etc/profile.d Path to the directory where the configuration file will be saved.
  • comment=#
    Так как мы не задавали формат конфигурационного файла, неплохо указать символ разделителя комментария, чтобы утилиты могли сохранить служебную информацию, в т.ч. путь к шаблону, которым был настроен файл. Впоследствии по этому заголовку утилита cl-backup сможет отыскать ваш настроенный файл.

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:

equery f sys-libs/ncurses | grep ncurses.sh

/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:

qcheck sys-libs/ncurses

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

Попробуем немного усложнить пример. Для пересылки пакетов между сетями настроим /etc/sysctl.conf. Поскольку у нас уже есть один шаблон, сгруппируем их вместе, чтобы упростить синтаксис. Для этого в директории /var/calculate/templates создадим директорию с произвольным именем merge:

mkdir -p /var/calculate/templates/merge

В данном случае директория - это тоже шаблон, и он имеет свои свойства. Чтобы описать их, создайте файл .calculate_directory внутри директории со следующим содержимым:

/var/calculate/templates/merge/.calculate_directory

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

Здесь вы видите, что установка области действия переменных env=install и проверка значения переменной действия ac_install_merge==on были перенесены из шаблона первого примера. А это значит, что в шаблонах внутри этой директории эту проверку уже можно не выполнять. Помимо этого был добавлен новый параметр append=skip. Установка этого параметра говорит о том, что сама директория не будет создана в системе.

Перенесите шаблон из первого примера в общую директорию:

mv /var/calculate/templates/ncurses.sh /var/calculate/templates/merge/

and make its syntax simpler:

/var/calculate/templates/merge/ncurses.sh

# 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:

/var/calculate/templates/merge/sysctl.conf

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

Обратите внимание, что шаблон связан с пакетом sys-apps/baselayot. Чтобы узнать, какому пакету принадлежит файл, выполните:

equery b /etc/sysctl.conf

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

Для того, чтобы проверить работу шаблона, вы можете либо переустановить пакет sys-apps/baselayout, либо выполнить:

cl-core-setup --pkg-name=baselayout -v -T local

 * Конфигурация утилитами Calculate системных настроек baselayout ...
 * Утилиты Calculate изменили файлы:  
 *      /etc/sysctl.conf 

Обратите внимание, что в файле /etc/sysctl.conf был изменён только один параметр:

/etc/sysctl.conf

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

Аналогичным образом вы можете проверить работу шаблона ncurses.sh:

cl-core-setup --pkg-name=ncurses -v -T local

 * Конфигурация утилитами Calculate системных настроек ncurses ...
 * Утилиты Calculate изменили файлы:  
 *      /etc/profile.d/ncurses.sh  

Example 3: A clt template

Для упрощения работы с шаблонами был создан новый тип - так называемые clt-шаблоны. Эти шаблоны размещаются не в специально выделенной директории, а непосредственно в директории /etc и имеют расширение .clt. Удобство использования таких шаблонов заключается в предустановленных значениях путей и условий использования. При этом clt-шаблоны обладают всеми возможностями полноценных шаблонов.

Для примера давайте попробуем изменить размер консольного шрифта при помощи шаблона. Для этого создадим копию файла:

cp /etc/conf.d/consolefont /etc/conf.d/consolefont.clt

and edit the font size:

/etc/conf.d/consolefont.clt

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

Теперь, чтобы увидеть результат, переустановите пакет sys-apps/openrc, которому принадлежит файл настроек:

emerge -a1 openrc

grep ^consolefont /etc/conf.d/consolefont

consolefont="ter-v12n"

Данный шаблон всегда будет полностью переписывать файл своими настройками. Причём он даже не будет сообщать о том, что файл был создан им. Поэтому мы рекомендуем использовать clt-шаблоны, задействуя хотя бы минимум возможностей. Вместо копирования всего файла целиком создайте шаблон, состоящий всего из двух строк:

/etc/conf.d/consolefont.clt

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

Этот шаблон выполнит все те же действия, только проще и эффективней. Давайте выполним обновление пакета, чтобы посмотреть результат:

emerge -a1 openrc

grep ^consolefont /etc/conf.d/consolefont

consolefont="ter-v12n"

В результате вы видите, что только одна строчка осталась без изменения, плюс в заголовке файла был добавлен путь к вашему шаблону. Безусловно, это удобно - ведь в шаблоне вы указываете только те параметры, которые вам нужно изменить.

Вы видите, что синтаксис clt-шаблона максимально упрощён. Это стало возможно благодаря тому, что следующие настройки были заданы по умолчанию: env=install, ac_install_merge=on, path=/etc/conf.d и name=consolefont.

Conclusion

В этой статье вы смогли получить только общее представление о шаблонах утилит Calculate.