Who and when merges templates

Updated 5 November 2026

Contents

A template is not applied "whenever you like" but at the moment of a specific action. The action variables ac_* determine which templates to merge this time: the utility sets them, and the templates check them in the header. Therefore, the top-level directory of the template tree is conventionally named after the action: N_ac_[HTML_REMOVED].

The actual set of directories in the calculate tree:

1_ac_install_disk         6_ac_desktop_profile
2_ac_install_merge        6_ac_install_config
3_ac_install_live         6_ac_install_configure
5_ac_ad_client            6_ac_install_flash
5_ac_client_configure     6_ac_install_patch
6_ac_backup_create        6_ac_install_pxe
6_ac_backup_restore       6_ac_install_unmerge
6_ac_backup_service       6_ac_update_sync
6_ac_builder_container    7_ac_server_ldif
6_ac_builder_iso          7_ac_server_setup
6_ac_builder_prepare      9_ac_install_merge
6_ac_builder_setup        deprecated
6_ac_builder_squash

The set depends on the repository revision: deprecated and some of the 6_ac_builder_* may be missing from it. You get the full and current list from ls /var/db/repos/calculate/profiles/templates/.

The numeric prefix in the event directory name sets the order relative to the other directories; the file order inside a single directory is described on the page about template directories. The action itself is chosen by the header in .calculate_directory, not by the directory name.

Main events

Configuring a package

The 2_ac_install_merge, 9_ac_install_merge and 6_ac_install_unmerge events - these occur during the installation, update and removal of a package: emerge. This is implemented with Portage hooks - fragments of profile.bashrc that live in /var/lib/calculate/profile.bashrc.d/ and are themselves generated by templates. This is where templates of the form [HTML_REMOVED]/[HTML_REMOVED]/… work, and the condition mergepkg([HTML_REMOVED]/[HTML_REMOVED])!= проверяет, что настраивается этот пакет.

An important detail that explains half of the "why was it not applied" questions: the package's templates are merged only if the package is in the caches /var/lib/calculate/calculate-core/cache/merge-setup.list (configuration) or merge-patch.list (patches). These lists are updated at the installation/removal phases by /usr/libexec/calculate/cl-pkg-cache. If the package is not in the cache, there is no application either, even if the template is written correctly.

Modifying package sources

The 6_ac_install_patch event runs before compilation, and the templates of this event apply patches (usually format=diff). If a merge fails, the build may be interrupted.

Updating the system and syncing the Portage tree

The 6_ac_update_sync event is called by the update action. cl-update runs it, and during the synchronization of the Portage tree it is the Calculate sync module in portage: for repositories with sync-type = calculate it runs cl-core --method update --repositories <name> --sync-only on --skip-eix-update -T none. These are "migrations": directories with date names (2026/20261103), which are applied only once, and a typical template checks the overlay revision through ini(overlay-calculate.remerge)<#-cl_pass_file-#>. The condition ac_update_sync==on is satisfied during the synchronization and profile change actions, when the package being configured is not specified. The variable belongs to the update module and is read-only: you cannot set it manually, the action itself sets it, which is why you write it in the header together with the module - env=update ac_update_sync==on, the shipped 6_ac_update_sync directory is arranged exactly this way, with # Calculate append=skip env=update ac_update_sync==on.

Installing and booting the system

The 1_ac_install_disk, 3_ac_install_live, 6_ac_install_flash and 6_ac_install_pxe events - configuring the system being installed (cl-install), the live image, booting from USB-Flash and booting over the network.

User profile

The 6_ac_desktop_profile event runs when the user logs in to a session (via cl-desktop), and also when a package is installed on a working system - then the already created profile is configured further. The ur_* variables and the ~ path take part in this event, while the clt layer is not used.

Specific configurator

The 6_ac_install_configure, 5_ac_client_configure and 7_ac_server_setup events - actions by configuration type: network, sound, bootloader, locale, session, themes, video (cl-setup-network, cl-setup-locale, … - see cl-core --list-methods). The condition in the template usually checks cl_setup==[HTML_REMOVED] together with ac_install_configure==on.

Domain

5_ac_ad_client covers joining the machine to the domain and leaving it.

Building an image

6_ac_builder_* covers the builder actions (iso, squash, container, prepare, setup).

The same run can enable several events

This is a common source of surprises. The ac_install_merge and ac_install_live variables are enabled at the same time if you run package configuration directly on an already installed system (cl-core-setup …, cl-setup-system): ac_install_live is not "LiveCD only". Inside the Portage chroot (during a package build) the live mode is turned off, while merge remains. Hence the practical rule: if the template is specifically about the live image, you must place it in 3_ac_install_live and rely on the environment differences, rather than counting on the "installer" event.

ac_install_disk is set when the action is a system installation (and not flash/pxe).

Manual run

The most common way to check your template:

cl-core-setup -n [HTML_REMOVED]

  • -v - verbose output with a list of the applied templates and errors; for core_setup it is on by default, so in examples you can leave the flag out;
  • -c [HTML_REMOVED] - the package category; you do not have to specify it. Name collisions across categories are rare, and cl-core-setup -n baselayout is enough. -c comes in handy to tell such cases apart; and know the other side: with a wrong category not a single template is applied, and without any error message - the check will simply show an empty result;
  • --pkg-path [HTML_REMOVED] - direct the results to a directory without changing the configuration files themselves (see preview); the directory must exist, otherwise you get Error in parameter --pkg-path. Careful: the preview still changes the package manager database - the merged paths are written into the package file list (CONTENTS) as real ones: one such run adds several lines to CONTENTS that were not in the equery f <package> output. Save that output before the trial, and after it compare with the current CONTENTS and remove the lines that appeared;
  • -T - choose the template layers from a fixed set: calculate, distros, local, remote, clt; none disables the selection entirely.

The list of available actions: cl-core --list-methods.

See also