COSMIC

Packaging COSMIC applications

COSMIC (Computer Operating System Main Interface Components) is a desktop environment developed by System76, primarily for the Pop!_OS Linux distribution. Applications in the COSMIC ecosystem are written in Rust and use libcosmic, which builds on the Iced GUI framework. This section explains how to properly package and integrate COSMIC applications within Nix.

libcosmicAppHook

The libcosmicAppHook is a setup hook that helps with this by automatically configuring and wrapping applications based on libcosmic. It handles many common requirements like:

Setting up proper linking for libraries that may be dlopen'd by libcosmic/iced apps
Configuring XDG paths for settings schemas, icons, and other resources
Managing Vergen environment variables for build-time information
Setting up Rust linker flags for specific libraries

To use the hook, simply add it to your package's nativeBuildInputs:

{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
rustPlatform.buildRustPackage {
  # ...
  nativeBuildInputs = [ libcosmicAppHook ];
  # ...
}

Settings fallback

COSMIC applications use libcosmic's UI components, which may need access to theme settings. The cosmic-settings package provides default theme settings as a fallback in its share directory. By default, libcosmicAppHook includes this fallback path in XDG_DATA_DIRS, ensuring that COSMIC applications will have access to theme settings even if they aren't available elsewhere in the system.

This fallback behavior can be disabled by setting includeSettings = false when including the hook:

{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
let
  # Get build-time version of libcosmicAppHook
  libcosmicAppHook' = (libcosmicAppHook.__spliced.buildHost or libcosmicAppHook).override {
    includeSettings = false;
  };
in
rustPlatform.buildRustPackage {
  # ...
  nativeBuildInputs = [ libcosmicAppHook' ];
  # ...
}

Note that cosmic-settings is a separate application and not a part of the libcosmic settings system itself. It's included by default in libcosmicAppHook only to provide these fallback theme settings.

Icons

COSMIC applications can use icons from the COSMIC icon theme. While COSMIC applications can build and run without these icons, they would be missing visual elements. The libcosmicAppHook automatically includes cosmic-icons in the wrapped application's XDG_DATA_DIRS as a fallback, ensuring that the application has access to its required icons even if the system doesn't have the COSMIC icon theme installed globally.

Unlike the cosmic-settings fallback, the cosmic-icons fallback cannot be removed or disabled, as it is essential for COSMIC applications to have access to these icons for proper visual rendering.

Runtime Libraries

COSMIC applications built on libcosmic and Iced require several runtime libraries that are dlopen'd rather than linked directly. The libcosmicAppHook ensures that these libraries are correctly linked by setting appropriate Rust linker flags. The libraries handled include:

Graphics libraries (EGL, Vulkan)
Input libraries (xkbcommon)
Display server protocols (Wayland, X11)

This ensures that the applications will work correctly at runtime, even though they use dynamic loading for these dependencies.

Adding custom wrapper arguments

You can pass additional arguments to the wrapper using libcosmicAppWrapperArgs in the preFixup hook:

{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
rustPlatform.buildRustPackage {
  # ...
  preFixup = ''
    libcosmicAppWrapperArgs+=(--set-default ENVIRONMENT_VARIABLE VALUE)
  '';
  # ...
}

Frequently encountered issues

Setting up Vergen environment variables

Many COSMIC applications use the Vergen Rust crate for build-time information. The libcosmicAppHook automatically sets up the VERGEN_GIT_COMMIT_DATE environment variable based on SOURCE_DATE_EPOCH to ensure reproducible builds.

However, some applications may explicitly require additional Vergen environment variables. Without these properly set, you may encounter build failures with errors like:

>   cargo:rerun-if-env-changed=VERGEN_GIT_COMMIT_DATE
>   cargo:rerun-if-env-changed=VERGEN_GIT_SHA
>
>   --- stderr
>   Error: no suitable 'git' command found!
> warning: build failed, waiting for other jobs to finish...

While libcosmicAppHook handles VERGEN_GIT_COMMIT_DATE, you may need to explicitly set other variables. For applications that require these variables, you should set them directly in the package definition:

{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
rustPlatform.buildRustPackage {
  # ...
  env = {
    VERGEN_GIT_COMMIT_DATE = "2025-01-01";
    VERGEN_GIT_SHA = "0000000000000000000000000000000000000000"; # SHA-1 hash of the commit
  };
  # ...
}

Not all COSMIC applications require these variables, but for those that do, setting them explicitly will prevent build failures.

5.2 KiB Raw Permalink Blame History