pyrox.dev
1# COSMIC {#sec-language-cosmic}
2
3## Packaging COSMIC applications {#ssec-cosmic-packaging}
4
5COSMIC (Computer Operating System Main Interface Components) is a desktop environment developed by
6System76, primarily for the Pop!_OS Linux distribution. Applications in the COSMIC ecosystem are
7written in Rust and use libcosmic, which builds on the Iced GUI framework. This section explains
8how to properly package and integrate COSMIC applications within Nix.
9
10### libcosmicAppHook {#ssec-cosmic-libcosmic-app-hook}
11
12The `libcosmicAppHook` is a setup hook that helps with this by automatically configuring
13and wrapping applications based on libcosmic. It handles many common requirements like:
14
15- Setting up proper linking for libraries that may be dlopen'd by libcosmic/iced apps
16- Configuring XDG paths for settings schemas, icons, and other resources
17- Managing Vergen environment variables for build-time information
18- Setting up Rust linker flags for specific libraries
19
20To use the hook, simply add it to your package's `nativeBuildInputs`:
21
22```nix
23{
24 lib,
25 rustPlatform,
26 libcosmicAppHook,
27}:
28rustPlatform.buildRustPackage {
29 # ...
30 nativeBuildInputs = [ libcosmicAppHook ];
31 # ...
32}
33```
34
35### Settings fallback {#ssec-cosmic-settings-fallback}
36
37COSMIC applications use libcosmic's UI components, which may need access to theme settings. The
38`cosmic-settings` package provides default theme settings as a fallback in its `share` directory.
39By default, `libcosmicAppHook` includes this fallback path in `XDG_DATA_DIRS`, ensuring that COSMIC
40applications will have access to theme settings even if they aren't available elsewhere in the
41system.
42
43This fallback behavior can be disabled by setting `includeSettings = false` when including the hook:
44
45```nix
46{
47 lib,
48 rustPlatform,
49 libcosmicAppHook,
50}:
51let
52 # Get build-time version of libcosmicAppHook
53 libcosmicAppHook' = (libcosmicAppHook.__spliced.buildHost or libcosmicAppHook).override {
54 includeSettings = false;
55 };
56in
57rustPlatform.buildRustPackage {
58 # ...
59 nativeBuildInputs = [ libcosmicAppHook' ];
60 # ...
61}
62```
63
64Note that `cosmic-settings` is a separate application and not a part of the libcosmic settings
65system itself. It's included by default in `libcosmicAppHook` only to provide these fallback theme
66settings.
67
68### Icons {#ssec-cosmic-icons}
69
70COSMIC applications can use icons from the COSMIC icon theme. While COSMIC applications can build
71and run without these icons, they would be missing visual elements. The `libcosmicAppHook`
72automatically includes `cosmic-icons` in the wrapped application's `XDG_DATA_DIRS` as a fallback,
73ensuring that the application has access to its required icons even if the system doesn't have the
74COSMIC icon theme installed globally.
75
76Unlike the `cosmic-settings` fallback, the `cosmic-icons` fallback cannot be removed or disabled, as
77it is essential for COSMIC applications to have access to these icons for proper visual rendering.
78
79### Runtime Libraries {#ssec-cosmic-runtime-libraries}
80
81COSMIC applications built on libcosmic and Iced require several runtime libraries that are dlopen'd
82rather than linked directly. The `libcosmicAppHook` ensures that these libraries are correctly
83linked by setting appropriate Rust linker flags. The libraries handled include:
84
85- Graphics libraries (EGL, Vulkan)
86- Input libraries (xkbcommon)
87- Display server protocols (Wayland, X11)
88
89This ensures that the applications will work correctly at runtime, even though they use dynamic
90loading for these dependencies.
91
92### Adding custom wrapper arguments {#ssec-cosmic-custom-wrapper-args}
93
94You can pass additional arguments to the wrapper using `libcosmicAppWrapperArgs` in the `preFixup` hook:
95
96```nix
97{
98 lib,
99 rustPlatform,
100 libcosmicAppHook,
101}:
102rustPlatform.buildRustPackage {
103 # ...
104 preFixup = ''
105 libcosmicAppWrapperArgs+=(--set-default ENVIRONMENT_VARIABLE VALUE)
106 '';
107 # ...
108}
109```
110
111## Frequently encountered issues {#ssec-cosmic-common-issues}
112
113### Setting up Vergen environment variables {#ssec-cosmic-common-issues-vergen}
114
115Many COSMIC applications use the Vergen Rust crate for build-time information. The `libcosmicAppHook`
116automatically sets up the `VERGEN_GIT_COMMIT_DATE` environment variable based on `SOURCE_DATE_EPOCH`
117to ensure reproducible builds.
118
119However, some applications may explicitly require additional Vergen environment variables.
120Without these properly set, you may encounter build failures with errors like:
121
122```
123> cargo:rerun-if-env-changed=VERGEN_GIT_COMMIT_DATE
124> cargo:rerun-if-env-changed=VERGEN_GIT_SHA
125>
126> --- stderr
127> Error: no suitable 'git' command found!
128> warning: build failed, waiting for other jobs to finish...
129```
130
131While `libcosmicAppHook` handles `VERGEN_GIT_COMMIT_DATE`, you may need to explicitly set other
132variables. For applications that require these variables, you should set them directly in the
133package definition:
134
135```nix
136{
137 lib,
138 rustPlatform,
139 libcosmicAppHook,
140}:
141rustPlatform.buildRustPackage {
142 # ...
143 env = {
144 VERGEN_GIT_COMMIT_DATE = "2025-01-01";
145 VERGEN_GIT_SHA = "0000000000000000000000000000000000000000"; # SHA-1 hash of the commit
146 };
147 # ...
148}
149```
150
151Not all COSMIC applications require these variables, but for those that do, setting them explicitly
152will prevent build failures.