doc: document makeDesktopItem
This commit is contained in:
parent
5320e67e91
commit
7d61bb198f
@ -92,6 +92,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.
|
||||
|
Loading…
Reference in New Issue
Block a user