diff options
author | Daniel Sidhion <DanielSidhion@users.noreply.github.com> | 2024-03-18 16:08:29 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-03-18 16:08:29 -0700 |
commit | 83f77a1b3858caddca36c7e371d6d0b8cc1a75d5 (patch) | |
tree | 396d55af6c58c8957bda99176599106293f2573f /doc | |
parent | 4e1ac556ab6753d4f0144d0303a49d72ca0d83e7 (diff) | |
parent | 7d61bb198f715c133e5221b6307b2b569a0f06b2 (diff) | |
download | nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar.gz nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar.bz2 nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar.lz nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar.xz nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.tar.zst nixlib-83f77a1b3858caddca36c7e371d6d0b8cc1a75d5.zip |
Merge pull request #294019 from Lurkki14/doc-makedesktopitem
doc: document makeDesktopItem
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build-helpers/trivial-build-helpers.chapter.md | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 02d0a8682bf7..8354ee23b2db 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -94,6 +94,107 @@ writeShellScript "evaluate-my-file.sh" '' ``` :::: +### `makeDesktopItem` {#trivial-builder-makeDesktopItem} + +Write an [XDG desktop file](https://specifications.freedesktop.org/desktop-entry-spec/1.4/) to the Nix store. + +This function is usually used to add desktop items to a package through the `copyDesktopItems` hook. + +`makeDesktopItem` adheres to version 1.4 of the specification. + +#### Inputs {#trivial-builder-makeDesktopItem-inputs} + +`makeDesktopItem` takes an attribute set that accepts most values from the [XDG specification](https://specifications.freedesktop.org/desktop-entry-spec/1.4/ar01s06.html). + +All recognised keys from the specification are supported with the exception of the "Hidden" field. The keys are converted into camelCase format, but correspond 1:1 to their equivalent in the specification: `genericName`, `noDisplay`, `comment`, `icon`, `onlyShowIn`, `notShowIn`, `dbusActivatable`, `tryExec`, `exec`, `path`, `terminal`, `mimeTypes`, `categories`, `implements`, `keywords`, `startupNotify`, `startupWMClass`, `url`, `prefersNonDefaultGPU`. + +The "Version" field is hardcoded to the version `makeDesktopItem` currently adheres to. + +The following fields are either required, are of a different type than in the specification, carry specific default values, or are additional fields supported by `makeDesktopItem`: + +`name` (String) + +: The name of the desktop file in the Nix store. + +`type` (String; _optional_) + +: Default value: `"Application"` + +`desktopName` (String) + +: Corresponds to the "Name" field of the specification. + +`actions` (List of Attribute set; _optional_) + +: A list of attribute sets {name, exec?, icon?} + +`extraConfig` (Attribute set; _optional_) + +: Additional key/value pairs to be added verbatim to the desktop file. Attributes need to be prefixed with 'X-'. + +#### Examples {#trivial-builder-makeDesktopItem-examples} + +::: {.example #ex-makeDesktopItem} +# Usage 1 of `makeDesktopItem` + +Write a desktop file `/nix/store/<store path>/my-program.desktop` to the Nix store. + +```nix +{makeDesktopItem}: +makeDesktopItem { + name = "my-program"; + desktopName = "My Program"; + genericName = "Video Player"; + noDisplay = false; + comment = "Cool video player"; + icon = "/path/to/icon"; + onlyShowIn = [ "KDE" ]; + dbusActivatable = true; + tryExec = "my-program"; + exec = "my-program --someflag"; + path = "/some/working/path"; + terminal = false; + actions.example = { + name = "New Window"; + exec = "my-program --new-window"; + icon = "/some/icon"; + }; + mimeTypes = [ "video/mp4" ]; + categories = [ "Utility" ]; + implements = [ "org.my-program" ]; + keywords = [ "Video" "Player" ]; + startupNotify = false; + startupWMClass = "MyProgram"; + prefersNonDefaultGPU = false; + extraConfig.X-SomeExtension = "somevalue"; +} +``` + +::: + +::: {.example #ex2-makeDesktopItem} +# Usage 2 of `makeDesktopItem` + +Override the `hello` package to add a desktop item. + +```nix +{ copyDesktopItems +, hello +, makeDesktopItem }: + +hello.overrideAttrs { + nativeBuildInputs = [ copyDesktopItems ]; + + desktopItems = [(makeDesktopItem { + name = "hello"; + desktopName = "Hello"; + exec = "hello"; + })]; +} +``` + +::: + ### `writeTextFile` {#trivial-builder-writeTextFile} Write a text file to the Nix store. |