diff options
Diffstat (limited to 'doc/build-helpers')
| -rw-r--r-- | doc/build-helpers/images.md | 1 | ||||
| -rw-r--r-- | doc/build-helpers/images/snaptools.section.md | 71 | ||||
| -rw-r--r-- | doc/build-helpers/trivial-build-helpers.chapter.md | 111 |
3 files changed, 108 insertions, 75 deletions
diff --git a/doc/build-helpers/images.md b/doc/build-helpers/images.md index 5596784bfa48..033891fcef48 100644 --- a/doc/build-helpers/images.md +++ b/doc/build-helpers/images.md @@ -6,7 +6,6 @@ This chapter describes tools for creating various types of images. images/appimagetools.section.md images/dockertools.section.md images/ocitools.section.md -images/snaptools.section.md images/portableservice.section.md images/makediskimage.section.md images/binarycache.section.md diff --git a/doc/build-helpers/images/snaptools.section.md b/doc/build-helpers/images/snaptools.section.md deleted file mode 100644 index 259fa1b06180..000000000000 --- a/doc/build-helpers/images/snaptools.section.md +++ /dev/null @@ -1,71 +0,0 @@ -# pkgs.snapTools {#sec-pkgs-snapTools} - -`pkgs.snapTools` is a set of functions for creating Snapcraft images. Snap and Snapcraft is not used to perform these operations. - -## The makeSnap Function {#ssec-pkgs-snapTools-makeSnap-signature} - -`makeSnap` takes a single named argument, `meta`. This argument mirrors [the upstream `snap.yaml` format](https://docs.snapcraft.io/snap-format) exactly. - -The `base` should not be specified, as `makeSnap` will force set it. - -Currently, `makeSnap` does not support creating GUI stubs. - -## Build a Hello World Snap {#ssec-pkgs-snapTools-build-a-snap-hello} - -The following expression packages GNU Hello as a Snapcraft snap. - -``` {#ex-snapTools-buildSnap-hello .nix} -let - inherit (import <nixpkgs> { }) snapTools hello; -in snapTools.makeSnap { - meta = { - name = "hello"; - summary = hello.meta.description; - description = hello.meta.longDescription; - architectures = [ "amd64" ]; - confinement = "strict"; - apps.hello.command = "${hello}/bin/hello"; - }; -} -``` - -`nix-build` this expression and install it with `snap install ./result --dangerous`. `hello` will now be the Snapcraft version of the package. - -## Build a Graphical Snap {#ssec-pkgs-snapTools-build-a-snap-firefox} - -Graphical programs require many more integrations with the host. This example uses Firefox as an example because it is one of the most complicated programs we could package. - -``` {#ex-snapTools-buildSnap-firefox .nix} -let - inherit (import <nixpkgs> { }) snapTools firefox; -in snapTools.makeSnap { - meta = { - name = "nix-example-firefox"; - summary = firefox.meta.description; - architectures = [ "amd64" ]; - apps.nix-example-firefox = { - command = "${firefox}/bin/firefox"; - plugs = [ - "pulseaudio" - "camera" - "browser-support" - "avahi-observe" - "cups-control" - "desktop" - "desktop-legacy" - "gsettings" - "home" - "network" - "mount-observe" - "removable-media" - "x11" - ]; - }; - confinement = "strict"; - }; -} -``` - -`nix-build` this expression and install it with `snap install ./result --dangerous`. `nix-example-firefox` will now be the Snapcraft version of the Firefox package. - -The specific meaning behind plugs can be looked up in the [Snapcraft interface documentation](https://docs.snapcraft.io/supported-interfaces). diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 02d0a8682bf7..6d14db639938 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. @@ -557,14 +658,18 @@ This creates a derivation with a directory structure like the following: ## `writeReferencesToFile` {#trivial-builder-writeReferencesToFile} -Writes the closure of transitive dependencies to a file. +Deprecated. Use [`writeClosure`](#trivial-builder-writeClosure) instead. + +## `writeClosure` {#trivial-builder-writeClosure} + +Given a list of [store paths](https://nixos.org/manual/nix/stable/glossary#gloss-store-path) (or string-like expressions coercible to store paths), write their collective [closure](https://nixos.org/manual/nix/stable/glossary#gloss-closure) to a text file. -This produces the equivalent of `nix-store -q --requisites`. +The result is equivalent to the output of `nix-store -q --requisites`. For example, ```nix -writeReferencesToFile (writeScriptBin "hi" ''${hello}/bin/hello'') +writeClosure [ (writeScriptBin "hi" ''${hello}/bin/hello'') ] ``` produces an output path `/nix/store/<hash>-runtime-deps` containing |