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

Далее могут следовать одиночные параметры, параметры со значениями и условные выражения, объединённые в один или несколько блоков условий "и" (&&) и "или" (||).

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

Выполнение этого шаблона приведёт к созданию символической ссылки из директории /usr/share/pixmaps/calculate/breeze в директорию /usr/share/pixmaps/faces в случае наличия в системе пакетов kde-plasma/breeze и x11-themes/calculate-icon-theme версии 15-r2 или выше и свяжет эту ссылку с пакетом x11-themes/calculate-icon-theme.

Example 1: Just a template

Для примера создадим шаблон настроек пакета sys-libs/ncurses. First 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
    Параметром "env" задаётся область действия имён переменных и функций. По умолчанию используются базовые переменные и функции модуля main из библиотеки утилит. Подключая модуль install, мы можем использовать дополнительно переменные настройки системы. Посмотреть список переменных можно, выполнив @cl-core-variables-show --filter install.@ (с точкой в конце). Если модуль отсутствует в системе, шаблон будет пропущен.
  • 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
    Путь к директории, где будет записан конфигурационный файл.
  • comment=#
    Так как мы не задавали формат конфигурационного файла, неплохо указать символ разделителя комментария, чтобы утилиты могли сохранить служебную информацию, в т.ч. путь к шаблону, которым был настроен файл. Впоследствии по этому заголовку утилита cl-backup сможет отыскать ваш настроенный файл.

Проверьте одну из особенностей шаблонов - интеграцию с пакетным менеджером. 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

Как видим, контрольная сумма созданного нами файла соответствует данным пакетного менеджера.

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.