Packaging Cairo-Dock

The info on this page is intended for developers who would like to package Cairo-Dock for a GNU/Linux (or compatible) distribution. See also the source of our packages created for Ubuntu as an example: https://github.com/Cairo-Dock/debian (currently the jammy subdirectory). If you are a regular user, see the Installation or Compiling from source pages instead.

Components

Cairo-Dock is made up of four main components that are currently available in separate repositories:

1. core: https://github.com/Cairo-Dock/cairo-dock-core
2. main plugins: https://github.com/Cairo-Dock/cairo-dock-plug-ins
3. themes: https://github.com/Cairo-Dock/glxdock-repository (themes subdirectory)
4. external plugins (written in a language other than C): https://github.com/Cairo-Dock/cairo-dock-plug-ins-extras

Typically, you would need to package (1) and (2) as both are required to get a functional dock. On the other hand, once installed, Cairo-Dock can download components of (3) and (4) as needed (to the user's home directory), so it is typically not recommended to package these.

1. cairo-dock-core

https://github.com/Cairo-Dock/cairo-dock-core

This repository contains the core components of Cairo-Dock. However, the functionality without plugins is very limited (almost unusable), so it is strongly recommended to combine this with the plugins in some way.

Note: this repository also contains the desktop sessions, which depend on having either Compiz or Metacity and a bunch of GNOME components installed. It might make sense to split this into a separate package so that users can install Cairo-Dock without all of these dependencies (e.g. if a user only wants to use it in a different desktop environment). However, since many users might want to use these sessions, they should be made discoverable (e.g. "recommends" or "suggest" relationship with the main package). Similarly, this repository contains a systemd unit that can be useful, but not essential; This could be split in a separate package as well to not have systemd as a dependency (although it should be fine to install it even on a system without systemd).

2. cairo-dock-plug-ins

https://github.com/Cairo-Dock/cairo-dock-plug-ins

Plugins provide most of the functionality of the dock (see below for more detail). For technical reasons, they are provided in a separate repository and need to be compiled and installed separately; however, at least the most important plugins should be included in a standard installation of Cairo-Dock. There are several options to package the plugins:

• Together with core: this simplifies installation for users, as there is only one "Cairo-Dock" package that can be installed in a straightforward way. However, this does not allow customizing the installation (skipping plugins and their dependencies that a user does not need) and also can add some complications in building a package from multiple source repositories.
• Create one separate package (e.g. "cairo-dock-plugins"). This has the advantage of easy packaging (as one repository corresponds to one package) and relatively easy installation (as there are only two packages, the core and the plugins). It has the same disadvantage as above, that installation of individual plugins cannot be customized. To help users, it is recommended to create a metapackage (e.g. simply "cairo-dock") that installs both the core and the plugins.
• Create a separate package for each plugin. This allows the most flexibility for users as they can avoid installing plugins (and dependencies) that they don't need. However, this will result in a large number of packages that can be confusing as well. It is strongly recommended to create a metapackage that depends on common plugins (or even several metapackages that each depend on groups of plugins). Note that there are some files shared by multiple plugins; it is best to put these in a separate package that can be the dependency for these. This is the method currently used in our packages.

Plugins can be divided by their importance roughly into the following categories (note: names are the directory names in the plug-ins repository):

• Essential -- these are required to get a functioning dock as they provide some core functionality: Animated-icons, desklet-rendering, dialog-rendering, dock-rendering, drop-indicator
• Main plugins -- these provide some functionality that is typically required for a complete desktop session: clock, Folders, GMenu, gnome-integration, gvfs-integration, Indicator-applet, Indicator-applet3, Indicator-Generic, kde-integration, keyboard-indicator, logout, quick-browser, shortcuts, Status-Notifier, switcher, systray, xfce-integration. Note: systray only works on X11; the *-integration applets are also useful beyond their desktop environments and will auto-detect the features available, so it is recommended to always install them (and they do not need to depend on the respective desktop environment being installed).
• Visuals -- these improve the appearance of the dock, but are not essential: icon-effect, illusion, Impulse, motion-blur, Sound-Effects
• Additional utilities -- these allow more comfortable usage of the dock or better desktop integration, but are less essential IMO: alsaMixer, Cairo-Penguin, Clipper, Composite-Manager, Dbus, Disks, dustbin, netspeed, Network-Monitor, powermanager, Recent-Events, Remote-Control, Screenshot, showDesktop, show-mouse, slider, stack, System-Monitor, terminal, Toons, wifi, Xgamma. Note: the DBus plugin allows controlling some aspects of the dock externally, and is also required for external applets (those from the extra plugins repository and also for running Cairo-Dock as a systemd service.
• External services -- these plugins provide integration with other apps or online services: dnd2share, Messaging-Menu, musicPlayer, RSSreader, tomboy, weather, weblets
• Experimental -- these plugins provide some additional service, but are not fully functional or are not well maintained currently: Doncky, Global-Menu, mail, Scooby-Do

3. Themes

https://github.com/Cairo-Dock/glxdock-repository/tree/main/themes

This includes additional themes for individual plugins (under the plugin name) + themes for the dock under the themes3.4 subdirectory. Note that themes include user-contributed materials that might not be compatible with a FOSS license (see the individual themes for more info). It is not necessary to package these, as Cairo-Dock will offer the user to download them if the theme configuration is opened. If you'd like to package these, you should unzip the theme package in each directory and then install the content under {prefix}/cairo-dock/themes (e.g. /usr/share/cairo-dock/themes).

4. External plugins

https://github.com/Cairo-Dock/cairo-dock-plug-ins-extras

This repository contains additional plugins that were written in some other programming language (typically Python), and communicate with Cairo-Dock via its DBus interface. Many of these are not maintained and might contain bugs, or be outdated. It is also not necessary to package these, as Cairo-Dock will offer the user to download them as needed.

Versioning

Cairo-Dock uses a variation on semantic versioning where typically minor versions correspond to releases. New versions are released in our Github repositories. Typically a new release will include a Github release for both the core and plug-ins repository: https://github.com/Cairo-Dock/cairo-dock-core/releases https://github.com/Cairo-Dock/cairo-dock-plug-ins/releases

A version number will have three components:

X.Y.Z

X is the major version, currently 3. For most of the project, this followed the version of GTK used, and will likely only be incremented when updating to GTK 4. Y is the "minor" version, but a new minor version typically includes a lot of changes and new features (so it could be treated like major versions actually :D). Z is the micro version which starts from 0 with each minor version and has the following meaning:

• 0 <= Z < 90 are stable releases. Versions with Z > 0 are intended to fix bugs found after a release without adding significant new functionality. It is advised to always update to the latest micro version as soon as possible.
• 90 <= Z are development versions and typically include new features and potentially new bugs. If you package these, please indicate their beta / experimental status.

Before version 3.5.99, there was a strict requirement that the exact version of the core and plug-ins package should match (and plugins should be compiled with the same version of core that they will be run); i.e. you need to package and release core and plugins together.

Since version 3.5.99, there is a separate ABI version that is defined when compiling plugins, with the goal of broader compatibility. Currently, this means that an increase in the release candidate verion (e.g. from 3.5.99.rc5 to 3.5.99.rc6 requires recompiling the plugins). The following is planned from version 3.6.0. onward:

• Stable releases with the same minor version maintain ABI compatibility (so no need to recompile plugins if the micro version is incremented)
• For development versions, ABI compatibility is only maintained for the same micro version.

3. Compiling Cairo-Dock

See the Compilation page for more details.

Note that typically you would want to ensure that all optional dependencies are present when compiling. Several features are "optional" in the sense that they will be automatically disabled by CMake if the required dependencies are not available. This can result in important functions missing (e.g. if gtk-layer-shell is not available at compilation, it will be disabled and the dock will be unusable on Wayland). It is recommended to look at the package build logs and check the summary that CMake prints after configuring the build. Ideally, all features should report as enabled.