commit b75d47e7f0dd532b906c7783d42e7e28bb299798 · pyrox.dev/nixpkgs

+152

doc/languages-frameworks/cosmic.section.md

···

       1
       +
       # COSMIC {#sec-language-cosmic}

     

       2
       +
       

     

       3
       +
       ## Packaging COSMIC applications {#ssec-cosmic-packaging}

     

       4
       +
       

     

       5
       +
       COSMIC (Computer Operating System Main Interface Components) is a desktop environment developed by

     

       6
       +
       System76, primarily for the Pop!_OS Linux distribution. Applications in the COSMIC ecosystem are

     

       7
       +
       written in Rust and use libcosmic, which builds on the Iced GUI framework. This section explains

     

       8
       +
       how to properly package and integrate COSMIC applications within Nix.

     

       9
       +
       

     

       10
       +
       ### libcosmicAppHook {#ssec-cosmic-libcosmic-app-hook}

     

       11
       +
       

     

       12
       +
       The `libcosmicAppHook` is a setup hook that helps with this by automatically configuring

     

       13
       +
       and 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
       +
       

     

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

     

       21
       +
       

     

       22
       +
       ```nix

     

       23
       +
       {

     

       24
       +
         lib,

     

       25
       +
         rustPlatform,

     

       26
       +
         libcosmicAppHook,

     

       27
       +
       }:

     

       28
       +
       rustPlatform.buildRustPackage {

     

       29
       +
         # ...

     

       30
       +
         nativeBuildInputs = [ libcosmicAppHook ];

     

       31
       +
         # ...

     

       32
       +
       }

     

       33
       +
       ```

     

       34
       +
       

     

       35
       +
       ### Settings fallback {#ssec-cosmic-settings-fallback}

     

       36
       +
       

     

       37
       +
       COSMIC 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.

     

       39
       +
       By default, `libcosmicAppHook` includes this fallback path in `XDG_DATA_DIRS`, ensuring that COSMIC

     

       40
       +
       applications will have access to theme settings even if they aren't available elsewhere in the

     

       41
       +
       system.

     

       42
       +
       

     

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

     

       44
       +
       

     

       45
       +
       ```nix

     

       46
       +
       {

     

       47
       +
         lib,

     

       48
       +
         rustPlatform,

     

       49
       +
         libcosmicAppHook,

     

       50
       +
       }:

     

       51
       +
       let

     

       52
       +
         # Get build-time version of libcosmicAppHook

     

       53
       +
         libcosmicAppHook' = (libcosmicAppHook.__spliced.buildHost or libcosmicAppHook).override {

     

       54
       +
           includeSettings = false;

     

       55
       +
         };

     

       56
       +
       in

     

       57
       +
       rustPlatform.buildRustPackage {

     

       58
       +
         # ...

     

       59
       +
         nativeBuildInputs = [ libcosmicAppHook' ];

     

       60
       +
         # ...

     

       61
       +
       }

     

       62
       +
       ```

     

       63
       +
       

     

       64
       +
       Note that `cosmic-settings` is a separate application and not a part of the libcosmic settings

     

       65
       +
       system itself. It's included by default in `libcosmicAppHook` only to provide these fallback theme

     

       66
       +
       settings.

     

       67
       +
       

     

       68
       +
       ### Icons {#ssec-cosmic-icons}

     

       69
       +
       

     

       70
       +
       COSMIC applications can use icons from the COSMIC icon theme. While COSMIC applications can build

     

       71
       +
       and run without these icons, they would be missing visual elements. The `libcosmicAppHook`

     

       72
       +
       automatically includes `cosmic-icons` in the wrapped application's `XDG_DATA_DIRS` as a fallback,

     

       73
       +
       ensuring that the application has access to its required icons even if the system doesn't have the

     

       74
       +
       COSMIC icon theme installed globally.

     

       75
       +
       

     

       76
       +
       Unlike the `cosmic-settings` fallback, the `cosmic-icons` fallback cannot be removed or disabled, as

     

       77
       +
       it is essential for COSMIC applications to have access to these icons for proper visual rendering.

     

       78
       +
       

     

       79
       +
       ### Runtime Libraries {#ssec-cosmic-runtime-libraries}

     

       80
       +
       

     

       81
       +
       COSMIC applications built on libcosmic and Iced require several runtime libraries that are dlopen'd

     

       82
       +
       rather than linked directly. The `libcosmicAppHook` ensures that these libraries are correctly

     

       83
       +
       linked 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
       +
       

     

       89
       +
       This ensures that the applications will work correctly at runtime, even though they use dynamic

     

       90
       +
       loading for these dependencies.

     

       91
       +
       

     

       92
       +
       ### Adding custom wrapper arguments {#ssec-cosmic-custom-wrapper-args}

     

       93
       +
       

     

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

     

       95
       +
       

     

       96
       +
       ```nix

     

       97
       +
       {

     

       98
       +
         lib,

     

       99
       +
         rustPlatform,

     

       100
       +
         libcosmicAppHook,

     

       101
       +
       }:

     

       102
       +
       rustPlatform.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
       +
       

     

       115
       +
       Many COSMIC applications use the Vergen Rust crate for build-time information. The `libcosmicAppHook`

     

       116
       +
       automatically sets up the `VERGEN_GIT_COMMIT_DATE` environment variable based on `SOURCE_DATE_EPOCH`

     

       117
       +
       to ensure reproducible builds.

     

       118
       +
       

     

       119
       +
       However, some applications may explicitly require additional Vergen environment variables.

     

       120
       +
       Without 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
       +
       

     

       131
       +
       While `libcosmicAppHook` handles `VERGEN_GIT_COMMIT_DATE`, you may need to explicitly set other

     

       132
       +
       variables. For applications that require these variables, you should set them directly in the

     

       133
       +
       package definition:

     

       134
       +
       

     

       135
       +
       ```nix

     

       136
       +
       {

     

       137
       +
         lib,

     

       138
       +
         rustPlatform,

     

       139
       +
         libcosmicAppHook,

     

       140
       +
       }:

     

       141
       +
       rustPlatform.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
       +
       

     

       151
       +
       Not all COSMIC applications require these variables, but for those that do, setting them explicitly

     

       152
       +
       will prevent build failures.

doc/languages-frameworks/index.md

···

       58
        
       bower.section.md

     

       59
        
       chicken.section.md

     

       60
        
       coq.section.md

     

       0
        
       
     

       61
        
       crystal.section.md

     

       62
        
       cuda.section.md

     

       63
        
       cuelang.section.md

···

       58
        
       bower.section.md

     

       59
        
       chicken.section.md

     

       60
        
       coq.section.md

     

       61
       +
       cosmic.section.md

     

       62
        
       crystal.section.md

     

       63
        
       cuda.section.md

     

       64
        
       cuelang.section.md

+27

doc/redirects.json

···

       62
        
         "sec-build-helper-extendMkDerivation": [

     

       63
        
           "index.html#sec-build-helper-extendMkDerivation"

     

       64
        
         ],

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       65
        
         "sec-modify-via-packageOverrides": [

     

       66
        
           "index.html#sec-modify-via-packageOverrides"

     

       67
        
         ],

     
···

       316
        
         ],

     

       317
        
         "sec-tools-of-stdenv": [

     

       318
        
           "index.html#sec-tools-of-stdenv"

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       319
        
         ],

     

       320
        
         "ssec-stdenv-dependencies": [

     

       321
        
           "index.html#ssec-stdenv-dependencies"

···

       62
        
         "sec-build-helper-extendMkDerivation": [

     

       63
        
           "index.html#sec-build-helper-extendMkDerivation"

     

       64
        
         ],

     

       65
       +
         "sec-language-cosmic": [

     

       66
       +
           "index.html#sec-language-cosmic"

     

       67
       +
         ],

     

       68
        
         "sec-modify-via-packageOverrides": [

     

       69
        
           "index.html#sec-modify-via-packageOverrides"

     

       70
        
         ],

     
···

       319
        
         ],

     

       320
        
         "sec-tools-of-stdenv": [

     

       321
        
           "index.html#sec-tools-of-stdenv"

     

       322
       +
         ],

     

       323
       +
         "ssec-cosmic-common-issues": [

     

       324
       +
           "index.html#ssec-cosmic-common-issues"

     

       325
       +
         ],

     

       326
       +
         "ssec-cosmic-common-issues-vergen": [

     

       327
       +
           "index.html#ssec-cosmic-common-issues-vergen"

     

       328
       +
         ],

     

       329
       +
         "ssec-cosmic-custom-wrapper-args": [

     

       330
       +
           "index.html#ssec-cosmic-custom-wrapper-args"

     

       331
       +
         ],

     

       332
       +
         "ssec-cosmic-icons": [

     

       333
       +
           "index.html#ssec-cosmic-icons"

     

       334
       +
         ],

     

       335
       +
         "ssec-cosmic-libcosmic-app-hook": [

     

       336
       +
           "index.html#ssec-cosmic-libcosmic-app-hook"

     

       337
       +
         ],

     

       338
       +
         "ssec-cosmic-packaging": [

     

       339
       +
           "index.html#ssec-cosmic-packaging"

     

       340
       +
         ],

     

       341
       +
         "ssec-cosmic-runtime-libraries": [

     

       342
       +
           "index.html#ssec-cosmic-runtime-libraries"

     

       343
       +
         ],

     

       344
       +
         "ssec-cosmic-settings-fallback": [

     

       345
       +
           "index.html#ssec-cosmic-settings-fallback"

     

       346
        
         ],

     

       347
        
         "ssec-stdenv-dependencies": [

     

       348
        
           "index.html#ssec-stdenv-dependencies"