From 4eabe806554896ea70d1ea1eaf399146b7ad3084 Mon Sep 17 00:00:00 2001 From: Heitor Augusto Date: Sun, 2 Mar 2025 12:11:58 -0300 Subject: [PATCH] doc: add COSMIC section --- doc/languages-frameworks/cosmic.section.md | 152 +++++++++++++++++++++ doc/languages-frameworks/index.md | 1 + doc/redirects.json | 27 ++++ 3 files changed, 180 insertions(+) create mode 100644 doc/languages-frameworks/cosmic.section.md diff --git a/doc/languages-frameworks/cosmic.section.md b/doc/languages-frameworks/cosmic.section.md new file mode 100644 index 000000000000..9e07985b1295 --- /dev/null +++ b/doc/languages-frameworks/cosmic.section.md @@ -0,0 +1,152 @@ +# COSMIC {#sec-language-cosmic} + +## Packaging COSMIC applications {#ssec-cosmic-packaging} + +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 {#ssec-cosmic-libcosmic-app-hook} + +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`: + +```nix +{ + lib, + rustPlatform, + libcosmicAppHook, +}: +rustPlatform.buildRustPackage { + # ... + nativeBuildInputs = [ libcosmicAppHook ]; + # ... +} +``` + +### Settings fallback {#ssec-cosmic-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: + +```nix +{ + 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 {#ssec-cosmic-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 {#ssec-cosmic-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 {#ssec-cosmic-custom-wrapper-args} + +You can pass additional arguments to the wrapper using `libcosmicAppWrapperArgs` in the `preFixup` hook: + +```nix +{ + lib, + rustPlatform, + libcosmicAppHook, +}: +rustPlatform.buildRustPackage { + # ... + preFixup = '' + libcosmicAppWrapperArgs+=(--set-default ENVIRONMENT_VARIABLE VALUE) + ''; + # ... +} +``` + +## Frequently encountered issues {#ssec-cosmic-common-issues} + +### Setting up Vergen environment variables {#ssec-cosmic-common-issues-vergen} + +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: + +```nix +{ + 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. diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index 50c83ec939bc..a08318540aac 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -58,6 +58,7 @@ beam.section.md bower.section.md chicken.section.md coq.section.md +cosmic.section.md crystal.section.md cuda.section.md cuelang.section.md diff --git a/doc/redirects.json b/doc/redirects.json index 4757c2672057..a229e00a1ec7 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -62,6 +62,9 @@ "sec-build-helper-extendMkDerivation": [ "index.html#sec-build-helper-extendMkDerivation" ], + "sec-language-cosmic": [ + "index.html#sec-language-cosmic" + ], "sec-modify-via-packageOverrides": [ "index.html#sec-modify-via-packageOverrides" ], @@ -317,6 +320,30 @@ "sec-tools-of-stdenv": [ "index.html#sec-tools-of-stdenv" ], + "ssec-cosmic-common-issues": [ + "index.html#ssec-cosmic-common-issues" + ], + "ssec-cosmic-common-issues-vergen": [ + "index.html#ssec-cosmic-common-issues-vergen" + ], + "ssec-cosmic-custom-wrapper-args": [ + "index.html#ssec-cosmic-custom-wrapper-args" + ], + "ssec-cosmic-icons": [ + "index.html#ssec-cosmic-icons" + ], + "ssec-cosmic-libcosmic-app-hook": [ + "index.html#ssec-cosmic-libcosmic-app-hook" + ], + "ssec-cosmic-packaging": [ + "index.html#ssec-cosmic-packaging" + ], + "ssec-cosmic-runtime-libraries": [ + "index.html#ssec-cosmic-runtime-libraries" + ], + "ssec-cosmic-settings-fallback": [ + "index.html#ssec-cosmic-settings-fallback" + ], "ssec-stdenv-dependencies": [ "index.html#ssec-stdenv-dependencies" ],