Templates ARE Easy

Many of you who have extensive knowledge of Gentoo but come to use Calculate have wondered what exactly templates do, as those become commoner every day. Guess it’s high time we explained.

  • System requirements are getting higher, while standard setup tools do not correspond.
  • All templates use the one and same format: once you’ve learned it, it will be easy to use them.
  • Templates can be used for numerous tasks.

Let us see what Calculate Linux 13 has to offer us in the way of templates.


  1. How dependencies are handled

As good as said in the release announcement, we got rid of meta-packages - those had been quite a cumbersome matter for many, but then we had to imagine how the world file should be generated (the complete path for it, let me remind you, is /var/lib/portage/world). A priori one wouldn’t want to use templates for that: technically they may be very different. But templates have just enough indenpendence to build their own configuration scripts.

So we decided on generating world with templates, because:

  • Meta-packages were cumbersome! Before CL 13, if you wanted to delete a package and never see it again, you had to turn off the meta-package it belonged to with the corresponding USE flag and then manually add all packages that were left of it to the world file… we could not let our users suffer that any longer.
  • Sets are more easily described, but without USE flags they’re not flexible enough. Also, they have the same problem as meta-packages do.
  • Before using metas, we’d already tried, quite successfully, to generate the world file with templates at build time.
  • Templates had much developed overtime. A new event appeared, designed for applying templates and called whenever Portage is updated (with eix-sync).

Therefore, the world file in CL 13 is generated at build time and contains the software pack version. For the version number, have a look at /etc/calculate/ini.env:

world = 3

We had used meta-packages in the first place because we wanted our users to be able to edit their software list; this behaviour hasn’t changed. Via the update event, templates can modify the world file, adding, removing or replacing programs. This will allow for any modifications you made: should you, for instance, delete Audacious, you will not be offered another audio player to replace it.

For example, if you update to version 3, the net-wireless/madwifi-ng and net-wireless/madwifi-ng-tools packages will be deleted from world. They were frozen by Gentoo maintainers, as there is no more use in them: the drivers they provided had been moved to the kernel. If these masked packages were allowed into the world file, unpleasant blockages would occur when you tried to update your system.

Now, when you want to restore the original world file, you simply execute 'cl-update --rebuild-world'.

World templates are for now stored in:

  1. What configuration templates do

The bottom panel of any CL desktop features a set of main applications. Which icons you see there is determined by desktop files, found in the /usr/share/applications directory. Unfortunately, anything can happen to those: they quite often got renamed either by developers or by Gentoo maintainers, and once in a while it is users who replace a standard application with the one they prefer to it. We designed a default set of icons applied by templates, so that the modified applications do not disappear from the panel after a system update. These icons are specified in desktop files whose names start with ‘calculate’ followed by the application type (such as in calculate-browser.desktop).

Configuration templates were completely rewritten for CL 13, in order to be able to

  • reconfigure a default application should the current one be removed, and
  • configure a default application as the application preferred for a specific file extension.

The list of default applications is still kept in /etc/calculate/ini.env, here’s an example:

browser = chromium
mail = claws-mail
chat = xchat

Wanna try it? Install Firefox, then delete Chromium. If you are a CLDX user, relogin. Voilà, the new icon has appeared on the bottom panel, and /usr/share/applications/mimeapps.list was updated correspondingly. It happened so, because the configuration logic is described in templates within:


One more example. Just after we released CLDX 13, the new version of the terminal, Terminal 0.6.0, was made available in Portage. But it is not Terminal.desktop anymore: it is xfce4-terminal.desktop. The package itself was renamed as well from x11-terms/terminal to x11-terms/xfce4-terminal (see /usr/portage/profiles/updates/4Q-2012). And the configuration path is not the same either! Have you noticed these changes? If you haven’t, templates did their job just great.

  1. What system revisions are

Calculate Linux 13 uses system revisions. To find out the revision number, look for the 'rev' parameter in /etc/calculate/ini.env:

rev = 1

Revisions are used for minor updates on a regular basis, for your system to run smooth after you’ve updated to a new version. They’ve replaced templates that handled the updating procedure for some meta-packages. Revisions are not numbered after releases or build versions. Just before we released CL 13, revision 1 was created to fix problems with binding /usr/share/applications/mimeapps.list to x11-base/xorg-server.

The best thing about the said file is that it binds default applications to their respective MIME files. Before CL 13, it was created by the template applied when installing x11-base/xorg-server and associated with it. Reemerging the package would result in removal of the settings; revision 1 removed the binding.

For the time being, revisions are stored in



You may have noticed that some settings are kept in /etc/calculate/ini.env. This file (unlike calculate.env that you find in the same directory) does not store variable values, but templates parameters. Templates read and save them automatically; you are the one to choose the logic.

Only Portage, with its rolling-release approach, could give us this opportunity: thus we can add support for new software anytime, not necessarily when a new release is due.


Thank You, for the Templates ARE Easy Article.
Simple and to the point. Clears up some misunderstandings that I had…
Examples are always a Big Help… ;^)

sql python wrote:

Clears up some misunderstandings that I had…

Glad it helps :wink:

And if you ask my personal opinion, I think we should have more extensive documentation on templates… they are one of CL major features after all!

Anyway, the doc section will most certainly change much within the next few month… a month if I can cope with all translations.