summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/build-helpers/fetchers.chapter.md160
-rw-r--r--doc/languages-frameworks/gnome.section.md6
-rw-r--r--doc/packages/index.md1
-rw-r--r--doc/packages/krita.section.md37
-rw-r--r--doc/stdenv/stdenv.chapter.md4
5 files changed, 194 insertions, 14 deletions
diff --git a/doc/build-helpers/fetchers.chapter.md b/doc/build-helpers/fetchers.chapter.md
index 6efe64281e82..cb37dca06d48 100644
--- a/doc/build-helpers/fetchers.chapter.md
+++ b/doc/build-helpers/fetchers.chapter.md
@@ -283,7 +283,7 @@ If `pname` and `version` are specified, `fetchurl` will use those values and wil
_Default value:_ `""`.
-`recursiveHash` (Boolean; _optional_)
+`recursiveHash` (Boolean; _optional_) []{#sec-pkgs-fetchers-fetchurl-inputs-recursiveHash}
: If set to `true`, will signal to Nix that the hash given to `fetchurl` was calculated using the `"recursive"` mode.
See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHashMode) for more information about the existing modes.
@@ -296,7 +296,7 @@ If `pname` and `version` are specified, `fetchurl` will use those values and wil
_Default value_: `false`.
-`downloadToTemp` (Boolean; _optional_)
+`downloadToTemp` (Boolean; _optional_) []{#sec-pkgs-fetchers-fetchurl-inputs-downloadToTemp}
: If `true`, saves the downloaded file to a temporary location instead of the expected Nix store location.
This is useful when used in conjunction with `postFetch` attribute, otherwise `fetchurl` will not produce any meaningful output.
@@ -519,15 +519,81 @@ See [](#chap-pkgs-fetchers-caveats) for more details on how to work with the `ha
## `fetchzip` {#sec-pkgs-fetchers-fetchzip}
-Downloads content from a given URL (which is assumed to be an archive), and decompresses the archive for you, making files and directories directly accessible.
-`fetchzip` can only be used with archives.
-Despite its name, `fetchzip` is not limited to `.zip` files and can also be used with any tarball.
+Returns a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary.html#gloss-fixed-output-derivation) which downloads an archive from a given URL and decompresses it.
+
+Despite its name, `fetchzip` is not limited to `.zip` files but can also be used with [various compressed tarball formats](#tar-files) by default.
+This can extended by specifying additional attributes, see [](#ex-fetchers-fetchzip-rar-archive) to understand how to do that.
+
+### Inputs {#sec-pkgs-fetchers-fetchzip-inputs}
+
+`fetchzip` requires an attribute set, and most attributes are passed to the underlying call to [`fetchurl`](#sec-pkgs-fetchers-fetchurl).
+
+The attributes below are treated differently by `fetchzip` when compared to what `fetchurl` expects:
+
+`name` (String; _optional_)
+: Works as defined in `fetchurl`, but has a different default value than `fetchurl`.
+
+ _Default value:_ `"source"`.
+
+`nativeBuildInputs` (List of Attribute Set; _optional_)
+: Works as defined in `fetchurl`, but it is also augmented by `fetchzip` to include packages to deal with additional archives (such as `.zip`).
+
+ _Default value:_ `[]`.
+
+`postFetch` (String; _optional_)
+: Works as defined in `fetchurl`, but it is also augmented with the code needed to make `fetchzip` work.
+
+ :::{.caution}
+ It is only safe to modify files in `$out` in `postFetch`.
+ Consult the implementation of `fetchzip` for anything more involved.
+ :::
+
+ _Default value:_ `""`.
+
+`stripRoot` (Boolean; _optional_)
+: If `true`, the decompressed contents are moved one level up the directory tree.
+
+ This is useful for archives that decompress into a single directory which commonly includes some values that change with time, such as version numbers.
+ When this is the case (and `stripRoot` is `true`), `fetchzip` will remove this directory and make the decompressed contents available in the top-level directory.
+
+ [](#ex-fetchers-fetchzip-simple-striproot) shows what this attribute does.
+
+ This attribute is **not** passed through to `fetchurl`.
+
+ _Default value:_ `true`.
+
+`extension` (String or Null; _optional_)
+: If set, the archive downloaded by `fetchzip` will be renamed to a filename with the extension specified in this attribute.
+
+ This is useful when making `fetchzip` support additional types of archives, because the implementation may use the extension of an archive to determine whether they can decompress it.
+ If the URL you're using to download the contents doesn't end with the extension associated with the archive, use this attribute to fix the filename of the archive.
+
+ This attribute is **not** passed through to `fetchurl`.
+
+ _Default value:_ `null`.
+
+`recursiveHash` (Boolean; _optional_)
+: Works [as defined in `fetchurl`](#sec-pkgs-fetchers-fetchurl-inputs-recursiveHash), but its default value is different than for `fetchurl`.
+
+ _Default value:_ `true`.
+
+`downloadToTemp` (Boolean; _optional_)
+: Works [as defined in `fetchurl`](#sec-pkgs-fetchers-fetchurl-inputs-downloadToTemp), but its default value is different than for `fetchurl`.
+
+ _Default value:_ `true`.
+
+`extraPostFetch` **DEPRECATED**
+: This attribute is deprecated.
+ Please use `postFetch` instead.
+
+ This attribute is **not** passed through to `fetchurl`.
+
+### Examples {#sec-pkgs-fetchers-fetchzip-examples}
-It has two required arguments, a URL and a hash.
-The hash is typically `hash`, although many more hash algorithms are supported.
-Nixpkgs contributors are currently recommended to use `hash`.
-This hash will be used by Nix to identify your source.
-A typical usage of `fetchzip` is provided below.
+::::{.example #ex-fetchers-fetchzip-simple-striproot}
+# Using `fetchzip` to output contents directly
+
+The following recipe shows how to use `fetchzip` to decompress a `.tar.gz` archive:
```nix
{ fetchzip }:
@@ -537,6 +603,80 @@ fetchzip {
}
```
+This archive has all its contents in a directory named `patchelf-0.18.0`.
+This means that after decompressing, you'd have to enter this directory to see the contents of the archive.
+However, `fetchzip` makes this easier through the attribute `stripRoot` (enabled by default).
+
+After building the recipe, the derivation output will show all the files in the archive at the top level:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/1b7h3fvmgrcddvs0m299hnqxlgli1yjw-source
+
+$ ls /nix/store/1b7h3fvmgrcddvs0m299hnqxlgli1yjw-source
+aclocal.m4 completions configure.ac m4 Makefile.in patchelf.spec README.md tests
+build-aux configure COPYING Makefile.am patchelf.1 patchelf.spec.in src version
+```
+
+If `stripRoot` is set to `false`, the derivation output will be the decompressed archive as-is:
+
+```nix
+{ fetchzip }:
+fetchzip {
+ url = "https://github.com/NixOS/patchelf/releases/download/0.18.0/patchelf-0.18.0.tar.gz";
+ hash = "sha256-uv3FuKE4DqpHT3yfE0qcnq0gYjDNQNKZEZt2+PUAneg=";
+ stripRoot = false;
+}
+```
+
+:::{.caution}
+The hash changed!
+Whenever changing attributes of a Nixpkgs fetcher, [remember to invalidate the hash](#chap-pkgs-fetchers-caveats), otherwise you won't get the results you're expecting!
+:::
+
+After building the recipe:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source
+
+$ ls /nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source
+patchelf-0.18.0
+```
+::::
+
+::::{.example #ex-fetchers-fetchzip-rar-archive}
+# Using `fetchzip` to decompress a `.rar` file
+
+The `unrar` package provides a [setup hook](#ssec-setup-hooks) to decompress `.rar` archives during the [unpack phase](#ssec-unpack-phase), which can be used with `fetchzip` to decompress those archives:
+
+```nix
+{ fetchzip, unrar }:
+fetchzip {
+ url = "https://archive.org/download/SpaceCadet_Plus95/Space_Cadet.rar";
+ hash = "sha256-fC+zsR8BY6vXpUkVd6i1jF0IZZxVKVvNi6VWCKT+pA4=";
+ stripRoot = false;
+ nativeBuildInputs = [ unrar ];
+}
+```
+
+Since this particular `.rar` file doesn't put its contents in a directory inside the archive, `stripRoot` must be set to `false`.
+
+After building the recipe, the derivation output will show the decompressed files:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/zpn7knxfva6rfjja2gbb4p3l9w1f0d36-source
+
+$ ls /nix/store/zpn7knxfva6rfjja2gbb4p3l9w1f0d36-source
+FONT.DAT PINBALL.DAT PINBALL.EXE PINBALL2.MID TABLE.BMP WMCONFIG.EXE
+MSCREATE.DIR PINBALL.DOC PINBALL.MID Sounds WAVEMIX.INF
+```
+::::
+
## `fetchpatch` {#fetchpatch}
`fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example, it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time.
diff --git a/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md
index 6bf867b21abe..e158cea0e512 100644
--- a/doc/languages-frameworks/gnome.section.md
+++ b/doc/languages-frameworks/gnome.section.md
@@ -102,9 +102,11 @@ Given the requirements above, the package expression would become messy quickly:
}
```
-Fortunately, there is [`wrapGAppsHook`]{#ssec-gnome-hooks-wrapgappshook}. It works in conjunction with other setup hooks that populate environment variables, and it will then wrap all executables in `bin` and `libexec` directories using said variables.
+Fortunately, there is [`wrapGAppsHook`]{#ssec-gnome-hooks-wrapgappshook}. It works in conjunction with other setup hooks that populate environment variables, and it will then wrap all executables in `bin` and `libexec` directories using said variables. For convenience, it also adds `dconf.lib` for a GIO module implementing a GSettings backend using `dconf`, `gtk3` for GSettings schemas, and `librsvg` for GdkPixbuf loader to the closure.
-For convenience, it also adds `dconf.lib` for a GIO module implementing a GSettings backend using `dconf`, `gtk3` for GSettings schemas, and `librsvg` for GdkPixbuf loader to the closure. There is also [`wrapGAppsHook4`]{#ssec-gnome-hooks-wrapgappshook4}, which replaces GTK 3 with GTK 4. And in case you are packaging a program without a graphical interface, you might want to use [`wrapGAppsNoGuiHook`]{#ssec-gnome-hooks-wrapgappsnoguihook}, which runs the same script as `wrapGAppsHook` but does not bring `gtk3` and `librsvg` into the closure.
+There is also [`wrapGAppsHook4`]{#ssec-gnome-hooks-wrapgappshook4}, which replaces GTK 3 with GTK 4. Instead of `wrapGAppsHook`, this should be used for all GTK4 applications.
+
+In case you are packaging a program without a graphical interface, you might want to use [`wrapGAppsNoGuiHook`]{#ssec-gnome-hooks-wrapgappsnoguihook}, which runs the same script as `wrapGAppsHook` but does not bring `gtk3` and `librsvg` into the closure.
- `wrapGAppsHook` itself will add the package’s `share` directory to `XDG_DATA_DIRS`.
diff --git a/doc/packages/index.md b/doc/packages/index.md
index 1f45018ffc4a..38dba5b3498f 100644
--- a/doc/packages/index.md
+++ b/doc/packages/index.md
@@ -14,6 +14,7 @@ fish.section.md
fuse.section.md
ibus.section.md
kakoune.section.md
+krita.section.md
linux.section.md
locales.section.md
etc-files.section.md
diff --git a/doc/packages/krita.section.md b/doc/packages/krita.section.md
new file mode 100644
index 000000000000..ba427bd62ba1
--- /dev/null
+++ b/doc/packages/krita.section.md
@@ -0,0 +1,37 @@
+# Krita {#sec-krita}
+
+## Python plugins {#krita-python-plugins}
+
+"pykrita" plugins should be installed following
+[Krita's manual](https://docs.krita.org/en/user_manual/python_scripting/install_custom_python_plugin.html).
+This generally involves extracting the extension to `~/.local/share/krita/pykrita/`.
+
+## Binary plugins {#krita-binary-plugins}
+
+Binary plugins are Dynamically Linked Libraries to be loaded by Krita.
+
+_Note: You most likely won't need to deal with binary plugins,
+all known plugins are bundled and enabled by default._
+
+### Installing binary plugins {#krita-install-binary-plugins}
+
+You can choose what plugins are added to Krita by overriding the
+`binaryPlugins` attribute.
+
+If you want to add plugins instead of replacing, you can read the
+list of previous plugins via `pkgs.krita.binaryPlugins`:
+
+```nix
+(pkgs.krita.override (old: {
+ binaryPlugins = old.binaryPlugins ++ [ your-plugin ];
+}))
+```
+
+### Example structure of a binary plugin {#krita-binary-plugin-structure}
+
+```
+/nix/store/00000000000000000000000000000000-krita-plugin-example-1.2.3
+└── lib
+ └── kritaplugins
+ └── krita_example.so
+```
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index a1e27b7bdf7f..f3cdb1f2dc0c 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -797,7 +797,7 @@ A shell array containing additional arguments passed to the configure script. Yo
##### `dontAddPrefix` {#var-stdenv-dontAddPrefix}
-By default, the flag `--prefix=$prefix` is added to the configure flags. If this is undesirable, set this variable to true.
+By default, `./configure` is passed the concatenation of [`prefixKey`](#var-stdenv-prefixKey) and [`prefix`](#var-stdenv-prefix) on the command line. Disable this by setting `dontAddPrefix` to `true`.
##### `prefix` {#var-stdenv-prefix}
@@ -805,7 +805,7 @@ The prefix under which the package must be installed, passed via the `--prefix`
##### `prefixKey` {#var-stdenv-prefixKey}
-The key to use when specifying the prefix. By default, this is set to `--prefix=` as that is used by the majority of packages.
+The key to use when specifying the installation [`prefix`](#var-stdenv-prefix). By default, this is set to `--prefix=` as that is used by the majority of packages. Other packages may need `--prefix ` (with a trailing space) or `PREFIX=`.
##### `dontAddStaticConfigureFlags` {#var-stdenv-dontAddStaticConfigureFlags}