Project:Systemd/Ebuild policy

From Gentoo Wiki
Jump to:navigation Jump to:search

This article describes the policy that needs to be followed for a consistent user experience for systemd users in Gentoo.

General guidelines

  1. We aim to support OpenRC and systemd at the same time. Therefore, adding systemd support to a package is not a reason to remove OpenRC support, and vice versa.
  2. We do not expect all developers to use systemd or test their packages with it. If necessary, systemd@ can be CC-ed in any case that requires systemd-specific testing or expertise.
  3. We reserve the right to add systemd units to any package as requested by users. However, we aren't going to commit any patches or changes risking in bugs, just add the necessary files to FILESDIR and install them.
  4. Ebuilds must not introduce USE=systemd in order to control unit file installation. Unit files do not require systemd installed, and follow the usual guidelines against small text files (bash completion, logrotate etc.).

Unit file guidelines

There are a few rules that need to be obeyed when writing unit files. Since the goal is somehow different from the goals of OpenRC, porting those files 1:1 is terribly for unit file quality.

  1. At least one unit file per daemon. It is disallowed to start multiple daemons from a single unit file. Instead, create multiple unit files and link them using proper dependencies (Requires, BindTo, …).
  2. Similarly, indirection and abuse of start/stop scripts is discouraged. The task of unit file is to start a service, not configure it, check system, load kernel modules, do laundry. The other tasks either belong in the program itself or in the ebuild (the rarely-used pkg_configure phase).
  3. Use of Type=forking is appropriate if the exit of the parent process allows systemd to detect failures at startup, before other dependent units are started. This will also allow for immediate feedback from systemctl start.
  4. If the daemon does not properly implement forking, use Type=simple and run the daemon in the foreground.
  5. Referring to conf.d files in unit files is prohibited (see: conf.d files). Using other files for configurable variables is strongly discouraged. Instead, the unit file should use defaults, and a boilerplate /etc/systemd/system/foo.service.d/gentoo.conf with commented out additional options may be installed. It is encouraged to just override ExecStart= there rather than invent a special environment variable for command-line options.

Please consult the appropriate systemd manpages before writing unit files (systemd.service(5), systemd.exec(5), systemd.unit(5)). When in doubt, don't hesitate to join us on #gentoo-systemd or mail us and we'll be happy to help.

Detailed instructions

Upstreamed unit files

One of the goals of systemd is to move the burden of maintaining service files from downstream to upstream. Therefore, many packages supply and install unit files already.

In such a package, it is usually enough to pass appropriate directory to the configure script.

FILE foomatic-0.ebuildSnippets how to control upstream unit file installation
inherit systemd

src_configure() {
    econf \

Please note that some upstreams may be using a non-standard configure variable. In that case, please report a bug upstream (pointing them to daemon.7) and pass the non-standard option name as an argument to systemd_with_unitdir.

Using this option is obligatory. While upstream packages are usually able to autodetect unit file location properly, that relies on systemd being installed prior to the package. Providing the path directly allows systemd to be installed later with no need of rebuilding other packages.

Downstream unit files

If upstream does not provide unit files, we can still supply them to improve user experience. However, developers that do that are encouraged to submit the files for inclusion upstream. But please make sure that the unit is of sufficient quality first.

Downstream unit files are to be placed in FILESDIR and installed using systemd_dounit (or systemd_newunit):

FILE barmatic-0.ebuildSnippets how to control downstream unit file installation
inherit systemd

src_install() {
    systemd_dounit "${FILESDIR}"/bar.service

You can often base your unit files on those supplied by Arch Linux or Fedora. However, please make sure that they comply with our quality guidelines.

Packages that link against systemd or otherwise require systemd

If a package links against one of the systemd libraries or uses systemd in a way making it impossible to use the package without systemd (e.g. an obligatory logind requirement), the package needs to have a run-time dependency against systemd.

If the feature in question is optional and controlled at build-time, it is advised to introduce systemd USE flag on the ebuild that controls both the dependency and the feature:

FILE foomatic-1.ebuildSnippets how to control systemd linkage
inherit systemd


RDEPEND="systemd? ( sys-apps/systemd )"

src_configure() {
    econf \
        $(use_enable systemd systemd-activation) \

Please note that unit files are still installed unconditionally to the USE flag. This should be the case unless the unit file utilizes features enabled by USE=systemd. For example, a unit with Type=notify which starts a daemon that calls the sd_notify() function is broken/useless if the daemon has not been linked against libsystemd.