diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/anchor-use.js | 2 | ||||
| -rw-r--r-- | doc/build-helpers/trivial-build-helpers.chapter.md | 111 | ||||
| -rw-r--r-- | doc/languages-frameworks/cuda.section.md | 2 | ||||
| -rw-r--r-- | doc/languages-frameworks/java.section.md | 29 | ||||
| -rw-r--r-- | doc/languages-frameworks/javascript.section.md | 49 | ||||
| -rw-r--r-- | doc/languages-frameworks/python.section.md | 9 |
6 files changed, 177 insertions, 25 deletions
diff --git a/doc/anchor-use.js b/doc/anchor-use.js index 06ec24883aa3..a45c4e2be68d 100644 --- a/doc/anchor-use.js +++ b/doc/anchor-use.js @@ -1,3 +1,3 @@ document.addEventListener('DOMContentLoaded', function(event) { - anchors.add('h1:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)'); + anchors.add('h1[id]:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2[id]:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3[id]:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4[id]:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5[id]:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6[id]:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)'); }); 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 diff --git a/doc/languages-frameworks/cuda.section.md b/doc/languages-frameworks/cuda.section.md index 11c86e375c61..09af824531a2 100644 --- a/doc/languages-frameworks/cuda.section.md +++ b/doc/languages-frameworks/cuda.section.md @@ -144,4 +144,4 @@ All new projects should use the CUDA redistributables available in [`cudaPackage | Find libraries | `configurePhase` | Missing dependency on a `dev` output | Add the missing dependency | The `dev` output typically contain CMake configuration files | | Find libraries | `buildPhase` or `patchelf` | Missing dependency on a `lib` or `static` output | Add the missing dependency | The `lib` or `static` output typically contain the libraries | -In the scenario you are unable to run the resulting binary: this is arguably the most complicated as it could be any combination of the previous reasons. This type of failure typically occurs when a library attempts to load or open a library it depends on that it does not declare in its `DT_NEEDED` section. As a first step, ensure that dependencies are patched with [`cudaPackages.autoAddOpenGLRunpath`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.autoAddOpenGLRunpath). Failing that, try running the application with [`nixGL`](https://github.com/guibou/nixGL) or a similar wrapper tool. If that works, it likely means that the application is attempting to load a library that is not in the `RPATH` or `RUNPATH` of the binary. +In the scenario you are unable to run the resulting binary: this is arguably the most complicated as it could be any combination of the previous reasons. This type of failure typically occurs when a library attempts to load or open a library it depends on that it does not declare in its `DT_NEEDED` section. As a first step, ensure that dependencies are patched with [`cudaPackages.autoAddDriverRunpath`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.autoAddDriverRunpath). Failing that, try running the application with [`nixGL`](https://github.com/guibou/nixGL) or a similar wrapper tool. If that works, it likely means that the application is attempting to load a library that is not in the `RPATH` or `RUNPATH` of the binary. diff --git a/doc/languages-frameworks/java.section.md b/doc/languages-frameworks/java.section.md index 371bdf6323fb..0ce1442cca68 100644 --- a/doc/languages-frameworks/java.section.md +++ b/doc/languages-frameworks/java.section.md @@ -4,12 +4,31 @@ Ant-based Java packages are typically built from source as follows: ```nix stdenv.mkDerivation { - name = "..."; + pname = "..."; + version = "..."; + src = fetchurl { ... }; - nativeBuildInputs = [ jdk ant ]; + nativeBuildInputs = [ + ant + jdk + stripJavaArchivesHook # removes timestamp metadata from jar files + ]; + + buildPhase = '' + runHook preBuild + ant # build the project using ant + runHook postBuild + ''; + + installPhase = '' + runHook preInstall - buildPhase = "ant"; + # copy generated jar file(s) to an appropriate location in $out + install -Dm644 build/foo.jar $out/share/java/foo.jar + + runHook postInstall + ''; } ``` @@ -17,6 +36,10 @@ Note that `jdk` is an alias for the OpenJDK (self-built where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in Nixpkgs (`Aarch32`, `Aarch64`) point to the (unfree) `oraclejdk`. +Also note that not using `stripJavaArchivesHook` will likely cause the +generated `.jar` files to be non-deterministic, which is not optimal. +Using it, however, does not always guarantee reproducibility. + JAR files that are intended to be used by other packages should be installed in `$out/share/java`. JDKs have a stdenv setup hook that add any JARs in the `share/java` directories of the build inputs to the diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index c148070ad244..d553444d53b0 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -4,11 +4,14 @@ This contains instructions on how to package javascript applications. -The various tools available will be listed in the [tools-overview](#javascript-tools-overview). Some general principles for packaging will follow. Finally some tool specific instructions will be given. +The various tools available will be listed in the [tools-overview](#javascript-tools-overview). +Some general principles for packaging will follow. +Finally some tool specific instructions will be given. ## Getting unstuck / finding code examples {#javascript-finding-examples} -If you find you are lacking inspiration for packing javascript applications, the links below might prove useful. Searching online for prior art can be helpful if you are running into solved problems. +If you find you are lacking inspiration for packaging javascript applications, the links below might prove useful. +Searching online for prior art can be helpful if you are running into solved problems. ### Github {#javascript-finding-examples-github} @@ -30,17 +33,23 @@ The following principles are given in order of importance with potential excepti It is often not documented which node version is used upstream, but if it is, try to use the same version when packaging. -This can be a problem if upstream is using the latest and greatest and you are trying to use an earlier version of node. Some cryptic errors regarding V8 may appear. +This can be a problem if upstream is using the latest and greatest and you are trying to use an earlier version of node. +Some cryptic errors regarding V8 may appear. ### Try to respect the package manager originally used by upstream (and use the upstream lock file) {#javascript-upstream-package-manager} -A lock file (package-lock.json, yarn.lock...) is supposed to make reproducible installations of node_modules for each tool. +A lock file (package-lock.json, yarn.lock...) is supposed to make reproducible installations of `node_modules` for each tool. -Guidelines of package managers, recommend to commit those lock files to the repos. If a particular lock file is present, it is a strong indication of which package manager is used upstream. +Guidelines of package managers, recommend to commit those lock files to the repos. +If a particular lock file is present, it is a strong indication of which package manager is used upstream. -It's better to try to use a Nix tool that understand the lock file. Using a different tool might give you hard to understand error because different packages have been installed. An example of problems that could arise can be found [here](https://github.com/NixOS/nixpkgs/pull/126629). Upstream use NPM, but this is an attempt to package it with `yarn2nix` (that uses yarn.lock). +It's better to try to use a Nix tool that understand the lock file. +Using a different tool might give you hard to understand error because different packages have been installed. +An example of problems that could arise can be found [here](https://github.com/NixOS/nixpkgs/pull/126629). +Upstream use NPM, but this is an attempt to package it with `yarn2nix` (that uses yarn.lock). -Using a different tool forces to commit a lock file to the repository. Those files are fairly large, so when packaging for nixpkgs, this approach does not scale well. +Using a different tool forces to commit a lock file to the repository. +Those files are fairly large, so when packaging for nixpkgs, this approach does not scale well. Exceptions to this rule are: @@ -78,17 +87,23 @@ Exceptions to this rule are: ### Using node_modules directly {#javascript-using-node_modules} -Each tool has an abstraction to just build the node_modules (dependencies) directory. You can always use the `stdenv.mkDerivation` with the node_modules to build the package (symlink the node_modules directory and then use the package build command). The node_modules abstraction can be also used to build some web framework frontends. For an example of this see how [plausible](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix) is built. `mkYarnModules` to make the derivation containing node_modules. Then when building the frontend you can just symlink the node_modules directory. +Each tool has an abstraction to just build the node_modules (dependencies) directory. +You can always use the `stdenv.mkDerivation` with the node_modules to build the package (symlink the node_modules directory and then use the package build command). +The node_modules abstraction can be also used to build some web framework frontends. +For an example of this see how [plausible](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix) is built. `mkYarnModules` to make the derivation containing node_modules. +Then when building the frontend you can just symlink the node_modules directory. ## Javascript packages inside nixpkgs {#javascript-packages-nixpkgs} The [pkgs/development/node-packages](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages) folder contains a generated collection of [NPM packages](https://npmjs.com/) that can be installed with the Nix package manager. -As a rule of thumb, the package set should only provide _end user_ software packages, such as command-line utilities. Libraries should only be added to the package set if there is a non-NPM package that requires it. +As a rule of thumb, the package set should only provide _end user_ software packages, such as command-line utilities. +Libraries should only be added to the package set if there is a non-NPM package that requires it. When it is desired to use NPM libraries in a development project, use the `node2nix` generator directly on the `package.json` configuration file of the project. -The package set provides support for the official stable Node.js versions. The latest stable LTS release in `nodePackages`, as well as the latest stable current release in `nodePackages_latest`. +The package set provides support for the official stable Node.js versions. +The latest stable LTS release in `nodePackages`, as well as the latest stable current release in `nodePackages_latest`. If your package uses native addons, you need to examine what kind of native build system it uses. Here are some examples: @@ -96,7 +111,8 @@ If your package uses native addons, you need to examine what kind of native buil - `node-gyp-builder` - `node-pre-gyp` -After you have identified the correct system, you need to override your package expression while adding in build system as a build input. For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix): +After you have identified the correct system, you need to override your package expression while adding in build system as a build input. +For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix): ```nix dat = prev.dat.override (oldAttrs: { @@ -159,7 +175,8 @@ git config --global url."https://github.com/".insteadOf git://github.com/ ### buildNpmPackage {#javascript-buildNpmPackage} -`buildNpmPackage` allows you to package npm-based projects in Nixpkgs without the use of an auto-generated dependencies file (as used in [node2nix](#javascript-node2nix)). It works by utilizing npm's cache functionality -- creating a reproducible cache that contains the dependencies of a project, and pointing npm to it. +`buildNpmPackage` allows you to package npm-based projects in Nixpkgs without the use of an auto-generated dependencies file (as used in [node2nix](#javascript-node2nix)). +It works by utilizing npm's cache functionality -- creating a reproducible cache that contains the dependencies of a project, and pointing npm to it. Here's an example: @@ -193,7 +210,9 @@ buildNpmPackage rec { } ``` -In the default `installPhase` set by `buildNpmPackage`, it uses `npm pack --json --dry-run` to decide what files to install in `$out/lib/node_modules/$name/`, where `$name` is the `name` string defined in the package's `package.json`. Additionally, the `bin` and `man` keys in the source's `package.json` are used to decide what binaries and manpages are supposed to be installed. If these are not defined, `npm pack` may miss some files, and no binaries will be produced. +In the default `installPhase` set by `buildNpmPackage`, it uses `npm pack --json --dry-run` to decide what files to install in `$out/lib/node_modules/$name/`, where `$name` is the `name` string defined in the package's `package.json`. +Additionally, the `bin` and `man` keys in the source's `package.json` are used to decide what binaries and manpages are supposed to be installed. +If these are not defined, `npm pack` may miss some files, and no binaries will be produced. #### Arguments {#javascript-buildNpmPackage-arguments} @@ -315,10 +334,10 @@ buildPhase = '' ''; ``` -The dist phase is also trying to build a binary, the only way to override it is with: +The `distPhase` is packing the package's dependencies in a tarball using `yarn pack`. You can disable it using: ```nix -distPhase = "true"; +doDist = false; ``` The configure phase can sometimes fail because it makes many assumptions which may not always apply. One common override is: diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index fa7f3eddf72c..049b395dcc25 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -74,8 +74,9 @@ and the aliases #### `buildPythonPackage` function {#buildpythonpackage-function} -The `buildPythonPackage` function is implemented in -`pkgs/development/interpreters/python/mk-python-derivation.nix` +The `buildPythonPackage` function has its name binding in +`pkgs/development/interpreters/python/python-packages-base.nix` and is +implemented in `pkgs/development/interpreters/python/mk-python-derivation.nix` using setup hooks. The following is an example: @@ -2014,6 +2015,10 @@ example of such a situation is when `py.test` is used. * Tests that attempt to access `$HOME` can be fixed by using the following work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)` +* Compiling with Cython causes tests to fail with a `ModuleNotLoadedError`. + This can be fixed with two changes in the derivation: 1) replacing `pytest` with + `pytestCheckHook` and 2) adding a `preCheck` containing `cd $out` to run + tests within the built output. ## Contributing {#contributing} |