diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/builders/fetchers.chapter.md | 47 | ||||
| -rw-r--r-- | doc/default.nix | 1 | ||||
| -rw-r--r-- | doc/functions.md | 1 | ||||
| -rw-r--r-- | doc/functions/fileset.section.md | 51 | ||||
| -rw-r--r-- | doc/hooks/waf.section.md | 19 | ||||
| -rw-r--r-- | doc/languages-frameworks/chicken.section.md | 29 | ||||
| -rw-r--r-- | doc/languages-frameworks/cuda.section.md | 62 | ||||
| -rw-r--r-- | doc/stdenv/stdenv.chapter.md | 2 |
8 files changed, 200 insertions, 12 deletions
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 4d4f3f427cd49..ba105764904c4 100644 --- a/doc/builders/fetchers.chapter.md +++ b/doc/builders/fetchers.chapter.md @@ -82,6 +82,53 @@ Note that because the checksum is computed after applying these effects, using o Most other fetchers return a directory rather than a single file. + +## `fetchDebianPatch` {#fetchdebianpatch} + +A wrapper around `fetchpatch`, which takes: +- `patch` and `hash`: the patch's filename without the `.patch` suffix, + and its hash after normalization by `fetchpatch` ; +- `pname`: the Debian source package's name ; +- `version`: the upstream version number ; +- `debianRevision`: the [Debian revision number] if applicable ; +- the `area` of the Debian archive: `main` (default), `contrib`, or `non-free`. + +Here is an example of `fetchDebianPatch` in action: + +```nix +{ lib +, fetchDebianPatch +, buildPythonPackage +}: + +buildPythonPackage rec { + pname = "pysimplesoap"; + version = "1.16.2"; + src = ...; + + patches = [ + (fetchDebianPatch { + inherit pname version; + debianRevision = "5"; + name = "Add-quotes-to-SOAPAction-header-in-SoapClient"; + hash = "sha256-xA8Wnrpr31H8wy3zHSNfezFNjUJt1HbSXn3qUMzeKc0="; + }) + ]; + + ... +} +``` + +Patches are fetched from `sources.debian.org`, and so must come from a +package version that was uploaded to the Debian archive. Packages may +be removed from there once that specific version isn't in any suite +anymore (stable, testing, unstable, etc.), so maintainers should use +`copy-tarballs.pl` to archive the patch if it needs to be available +longer-term. + +[Debian revision number]: https://www.debian.org/doc/debian-policy/ch-controlfields.html#version + + ## `fetchsvn` {#fetchsvn} Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`. diff --git a/doc/default.nix b/doc/default.nix index 58b945c692fc3..18e12c1a8aca1 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -19,6 +19,7 @@ let { name = "options"; description = "NixOS / nixpkgs option handling"; } { name = "path"; description = "path functions"; } { name = "filesystem"; description = "filesystem functions"; } + { name = "fileset"; description = "file set functions"; } { name = "sources"; description = "source filtering functions"; } { name = "cli"; description = "command-line serialization functions"; } { name = "gvariant"; description = "GVariant formatted string serialization functions"; } diff --git a/doc/functions.md b/doc/functions.md index 09033c9e3c199..551ba522a9041 100644 --- a/doc/functions.md +++ b/doc/functions.md @@ -8,4 +8,5 @@ functions/generators.section.md functions/debug.section.md functions/prefer-remote-fetch.section.md functions/nix-gitignore.section.md +functions/fileset.section.md ``` diff --git a/doc/functions/fileset.section.md b/doc/functions/fileset.section.md new file mode 100644 index 0000000000000..b24ebe26cc3b7 --- /dev/null +++ b/doc/functions/fileset.section.md @@ -0,0 +1,51 @@ +<!-- TODO: Render this document in front of function documentation in case https://github.com/nix-community/nixdoc/issues/19 is ever supported --> + +# File sets {#sec-fileset} + +The [`lib.fileset`](#sec-functions-library-fileset) library allows you to work with _file sets_. +A file set is a mathematical set of local files that can be added to the Nix store for use in Nix derivations. +File sets are easy and safe to use, providing obvious and composable semantics with good error messages to prevent mistakes. + +These sections apply to the entire library. +See the [function reference](#sec-functions-library-fileset) for function-specific documentation. + +The file set library is currently very limited but is being expanded to include more functions over time. + +## Implicit coercion from paths to file sets {#sec-fileset-path-coercion} + +All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments. +Such path arguments are implicitly coerced to file sets containing all files under that path: +- A path to a file turns into a file set containing that single file. +- A path to a directory turns into a file set containing all files _recursively_ in that directory. + +If the path points to a non-existent location, an error is thrown. + +::: {.note} +Just like in Git, file sets cannot represent empty directories. +Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files. +::: + +:::{.note} +File set coercion does _not_ add any of the files under the coerced paths to the store. +Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument. +This is in contrast to using [paths in string interpolation](https://nixos.org/manual/nix/stable/language/values.html#type-path), which does add the entire referenced path to the store. +::: + +### Example {#sec-fileset-path-coercion-example} + +Assume we are in a local directory with a file hierarchy like this: +``` +├─ a/ +│ ├─ x (file) +│ └─ b/ +│ └─ y (file) +└─ c/ + └─ d/ +``` + +Here's a listing of which files get included when different path expressions get coerced to file sets: +- `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted). +- `./a` as a file set contains both `a/x` and `a/b/y`. +- `./a/x` as a file set contains only `a/x`. +- `./a/b` as a file set contains only `a/b/y`. +- `./c` as a file set is empty, since neither `c` nor `c/d` contain any files. diff --git a/doc/hooks/waf.section.md b/doc/hooks/waf.section.md index 8cacb30ea85f6..5e79b8bb30662 100644 --- a/doc/hooks/waf.section.md +++ b/doc/hooks/waf.section.md @@ -1,24 +1,20 @@ -# wafHook {#wafhook} +# waf.hook {#wafhook} [Waf](https://waf.io) is a Python-based software building system. -In Nixpkgs, `wafHook` overrides the default configure, build, and install phases. +In Nixpkgs, `waf.hook` overrides the default configure, build, and install phases. -## Variables controlling wafHook {#variablesControllingWafHook} +## Variables controlling waf.hook {#variablesControllingWafHook} ### `wafPath` {#wafPath} Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees. -If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it. - -### `wafConfigureFlags` {#wafConfigureFlags} - -Controls the flags passed to waf tool during configure phase. +If `wafPath` doesn't exist, then `waf.hook` will copy the `waf` provided from Nixpkgs to it. ### `wafFlags` {#wafFlags} -Controls the flags passed to waf tool during build and install phases. +Controls the flags passed to waf tool during build and install phases. For settings specific to build or install phases, use `buildFlags` or `installFlags` respectively. ### `dontAddWafCrossFlags` {#dontAddWafCrossFlags} @@ -36,11 +32,12 @@ When set to true, don't use the predefined `wafBuildPhase`. When set to true, don't use the predefined `wafInstallPhase`. -### Variables honored by wafHook {#variablesHonoredByWafHook} +### Variables honored by waf.hook {#variablesHonoredByWafHook} -The following variables commonly used by `stdenv.mkDerivation` are also honored by `wafHook`. +The following variables commonly used by `stdenv.mkDerivation` are also honored by `waf.hook`. - `prefixKey` +- `configureFlags` - `configureTargets` - `enableParallelBuilding` - `enableParallelInstalling` diff --git a/doc/languages-frameworks/chicken.section.md b/doc/languages-frameworks/chicken.section.md index d329943dc3c24..72c2642a6478c 100644 --- a/doc/languages-frameworks/chicken.section.md +++ b/doc/languages-frameworks/chicken.section.md @@ -47,3 +47,32 @@ To include more eggs, edit `pkgs/development/compilers/chicken/5/eggs.scm`. The first section of this file lists eggs which are required by `egg2nix` itself; all other eggs go into the second section. After editing, follow the procedure for updating eggs. + +## Override Scope {#sec-chicken-override-scope} + +The chicken package and its eggs, respectively, reside in a scope. This means, +the scope can be overridden to effect other packages in it. + +This example shows how to use a local copy of `srfi-180` and have it affect +all the other eggs: + +```nix +let + myChickenPackages = pkgs.chickenPackages.overrideScope' (self: super: { + # The chicken package itself can be overridden to effect the whole ecosystem. + # chicken = super.chicken.overrideAttrs { + # src = ... + # }; + + chickenEggs = super.chickenEggs.overrideScope' (eggself: eggsuper: { + srfi-180 = eggsuper.srfi-180.overrideAttrs { + # path to a local copy of srfi-180 + src = ... + }; + }); + }); +in +# Here, `myChickenPackages.chickenEggs.json-rpc`, which depends on `srfi-180` will use +# the local copy of `srfi-180`. +# ... +``` diff --git a/doc/languages-frameworks/cuda.section.md b/doc/languages-frameworks/cuda.section.md index 2d680ea6b3b6a..01a4f20da982d 100644 --- a/doc/languages-frameworks/cuda.section.md +++ b/doc/languages-frameworks/cuda.section.md @@ -54,3 +54,65 @@ for your specific card(s). Library maintainers should consult [NVCC Docs](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/) and release notes for their software package. + +## Adding a new CUDA release {#adding-a-new-cuda-release} + +> **WARNING** +> +> This section of the docs is still very much in progress. Feedback is welcome in GitHub Issues tagging @NixOS/cuda-maintainers or on [Matrix](https://matrix.to/#/#cuda:nixos.org). + +The CUDA Toolkit is a suite of CUDA libraries and software meant to provide a development environment for CUDA-accelerated applications. Until the release of CUDA 11.4, NVIDIA had only made the CUDA Toolkit available as a multi-gigabyte runfile installer, which we provide through the [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit) attribute. From CUDA 11.4 and onwards, NVIDIA has also provided CUDA redistributables (“CUDA-redist”): individually packaged CUDA Toolkit components meant to facilitate redistribution and inclusion in downstream projects. These packages are available in the [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) package set. + +All new projects should use the CUDA redistributables available in [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) in place of [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit), as they are much easier to maintain and update. + +### Updating CUDA redistributables {#updating-cuda-redistributables} + +1. Go to NVIDIA's index of CUDA redistributables: <https://developer.download.nvidia.com/compute/cuda/redist/> +2. Copy the `redistrib_*.json` corresponding to the release to `pkgs/development/compilers/cudatoolkit/redist/manifests`. +3. Generate the `redistrib_features_*.json` file by running: + + ```bash + nix run github:ConnorBaker/cuda-redist-find-features -- <path to manifest> + ``` + + That command will generate the `redistrib_features_*.json` file in the same directory as the manifest. + +4. Include the path to the new manifest in `pkgs/development/compilers/cudatoolkit/redist/extension.nix`. + +### Updating the CUDA Toolkit runfile installer {#updating-the-cuda-toolkit} + +> **WARNING** +> +> While the CUDA Toolkit runfile installer is still available in Nixpkgs as the [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit) attribute, its use is not recommended and should it be considered deprecated. Please migrate to the CUDA redistributables provided by the [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) package set. +> +> To ensure packages relying on the CUDA Toolkit runfile installer continue to build, it will continue to be updated until a migration path is available. + +1. Go to NVIDIA's CUDA Toolkit runfile installer download page: <https://developer.nvidia.com/cuda-downloads> +2. Select the appropriate OS, architecture, distribution, and version, and installer type. + + - For example: Linux, x86_64, Ubuntu, 22.04, runfile (local) + - NOTE: Typically, we use the Ubuntu runfile. It is unclear if the runfile for other distributions will work. + +3. Take the link provided by the installer instructions on the webpage after selecting the installer type and get its hash by running: + + ```bash + nix store prefetch-file --hash-type sha256 <link> + ``` + +4. Update `pkgs/development/compilers/cudatoolkit/versions.toml` to include the release. + +### Updating the CUDA package set {#updating-the-cuda-package-set} + +1. Include a new `cudaPackages_<major>_<minor>` package set in `pkgs/top-level/all-packages.nix`. + + - NOTE: Changing the default CUDA package set should occur in a separate PR, allowing time for additional testing. + +2. Successfully build the closure of the new package set, updating `pkgs/development/compilers/cudatoolkit/redist/overrides.nix` as needed. Below are some common failures: + +| Unable to ... | During ... | Reason | Solution | Note | +| --- | --- | --- | --- | --- | +| Find headers | `configurePhase` or `buildPhase` | Missing dependency on a `dev` output | Add the missing dependency | The `dev` output typically contain the headers | +| 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. diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index c466e375b1af7..4e993e898de28 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -1201,7 +1201,7 @@ someVar=$(stripHash $name) ### `wrapProgram` \<executable\> \<makeWrapperArgs\> {#fun-wrapProgram} -Convenience function for `makeWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation) and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations). +Convenience function for `makeWrapper` that replaces `<executable>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation) and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations). If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided. |