diff options
Diffstat (limited to 'doc')
37 files changed, 1701 insertions, 626 deletions
diff --git a/doc/Makefile b/doc/Makefile index cdef493502bf..49f361ebb60b 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,4 +1,4 @@ -MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md))) +MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'))) .PHONY: all all: validate format out/html/index.html out/epub/manual.epub diff --git a/doc/builders/images/appimagetools.xml b/doc/builders/images/appimagetools.xml index 0767a509a43d..45c5619abd97 100644 --- a/doc/builders/images/appimagetools.xml +++ b/doc/builders/images/appimagetools.xml @@ -63,7 +63,7 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x) appimageTools.wrapType2 { # or wrapType1 name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' /> src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' /> - url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage; + url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage"; sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s"; }; extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' /> diff --git a/doc/builders/images/dockertools.xml b/doc/builders/images/dockertools.xml index e7f37fdaaf00..126698d0a9ed 100644 --- a/doc/builders/images/dockertools.xml +++ b/doc/builders/images/dockertools.xml @@ -166,7 +166,7 @@ hello latest de2bf4786de6 About a minute ago 25.2MB <title>buildLayeredImage</title> <para> - Create a Docker image with many of the store paths being on their own layer to improve sharing between images. + Create a Docker image with many of the store paths being on their own layer to improve sharing between images. The image is realized into the Nix store as a gzipped tarball. Depending on the intended usage, many users might prefer to use <function>streamLayeredImage</function> instead, which this function uses internally. </para> <variablelist> @@ -327,6 +327,27 @@ pkgs.dockerTools.buildLayeredImage { </section> </section> + <section xml:id="ssec-pkgs-dockerTools-streamLayeredImage"> + <title>streamLayeredImage</title> + + <para> + Builds a script which, when run, will stream an uncompressed tarball of a Docker image to stdout. The arguments to this function are as for <function>buildLayeredImage</function>. This method of constructing an image does not realize the image into the Nix store, so it saves on IO and disk/cache space, particularly with large images. + </para> + + <para> + The image produced by running the output script can be piped directly into <command>docker load</command>, to load it into the local docker daemon: + <screen><![CDATA[ +$(nix-build) | docker load + ]]></screen> + </para> + <para> + Alternatively, the image be piped via <command>gzip</command> into <command>skopeo</command>, e.g. to copy it into a registry: + <screen><![CDATA[ +$(nix-build) | gzip --fast | skopeo copy docker-archive:/dev/stdin docker://some_docker_registry/myimage:tag + ]]></screen> + </para> + </section> + <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry"> <title>pullImage</title> diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/builders/packages/cataclysm-dda.section.md new file mode 100644 index 000000000000..ae2ee56a010e --- /dev/null +++ b/doc/builders/packages/cataclysm-dda.section.md @@ -0,0 +1,94 @@ +# Cataclysm: Dark Days Ahead + +## How to install Cataclysm DDA + +To install the latest stable release of Cataclysm DDA to your profile, execute +`nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build +without tiles), install `cataclysmDDA.stable.curses`. Note: `cataclysm-dda` is +an alias to `cataclysmDDA.stable.tiles`. + +If you like access to a development build of your favorite git revision, +override `cataclysm-dda-git` (or `cataclysmDDA.git.curses` if you like curses +build): + +```nix +cataclysm-dda-git.override { + version = "YYYY-MM-DD"; + rev = "YOUR_FAVORITE_REVISION"; + sha256 = "CHECKSUM_OF_THE_REVISION"; +} +``` + +The sha256 checksum can be obtained by + +```sh +nix-prefetch-url --unpack "https://github.com/CleverRaven/Cataclysm-DDA/archive/${YOUR_FAVORITE_REVISION}.tar.gz" +``` + +The default configuration directory is `~/.cataclysm-dda`. If you prefer +`$XDG_CONFIG_HOME/cataclysm-dda`, override the derivation: + +```nix +cataclysm-dda.override { + useXdgDir = true; +} +``` + +## Customizing with mods + +To install Cataclysm DDA with mods of your choice, you can use `withMods` +attribute: + +```nix +cataclysm-dda.withMods (mods: with mods; [ + tileset.UndeadPeople +]) +``` + +All mods, soundpacks, and tilesets available in nixpkgs are found in +`cataclysmDDA.pkgs`. + +Here is an example to modify existing mods and/or add more mods not available +in nixpkgs: + +```nix +let + customMods = self: super: lib.recursiveUpdate super { + # Modify existing mod + tileset.UndeadPeople = super.tileset.UndeadPeople.overrideAttrs (old: { + # If you like to apply a patch to the tileset for example + patches = [ ./path/to/your.patch ]; + }); + + # Add another mod + mod.Awesome = cataclysmDDA.buildMod { + modName = "Awesome"; + version = "0.x"; + src = fetchFromGitHub { + owner = "Someone"; + repo = "AwesomeMod"; + rev = "..."; + sha256 = "..."; + }; + # Path to be installed in the unpacked source (default: ".") + modRoot = "contents/under/this/path/will/be/installed"; + }; + + # Add another soundpack + soundpack.Fantastic = cataclysmDDA.buildSoundPack { + # ditto + }; + + # Add another tileset + tileset.SuperDuper = cataclysmDDA.buildTileSet { + # ditto + }; + }; +in +cataclysm-dda.withMods (mods: with mods.extend customMods; [ + tileset.UndeadPeople + mod.Awesome + soundpack.Fantastic + tileset.SuperDuper +]) +``` diff --git a/doc/builders/packages/citrix.xml b/doc/builders/packages/citrix.xml index c629dc9ee503..16f1bc6f8f21 100644 --- a/doc/builders/packages/citrix.xml +++ b/doc/builders/packages/citrix.xml @@ -4,34 +4,36 @@ <title>Citrix Workspace</title> <para> - <note> - <para> - Please note that the <literal>citrix_receiver</literal> package has been deprecated since its development was <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued by upstream</link> and has been replaced by <link xlink:href="https://www.citrix.com/products/workspace-app/">the citrix workspace app</link>. - </para> - </note> - <link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> and <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> are a remote desktop viewers which provide access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations. + The <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> is a remote desktop viewer which provides access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations. </para> <section xml:id="sec-citrix-base"> <title>Basic usage</title> <para> - The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix Receiver</link> or <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> need to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix. + The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> needs to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix. </para> + </section> - <warning> - <title>Caution with <command>nix-shell</command> installs</title> - <para> - It's recommended to install <literal>Citrix Receiver</literal> and/or <literal>Citrix Workspace</literal> using <literal>nix-env -i</literal> or globally to ensure that the <literal>.desktop</literal> files are installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to open <literal>.ica</literal> files automatically from the browser to start a Citrix connection. - </para> - </warning> + <section xml:id="sec-citrix-selfservice"> + <title>Citrix Selfservice</title> + <para> + The <link xlink:href="https://support.citrix.com/article/CTX200337">selfservice</link> is an application managing Citrix desktops and applications. Please note that this feature only works with at least <package>citrix_workspace_20_06_0</package> and later versions. + </para> + <para> + In order to set this up, you first have to <link xlink:href="https://its.uiowa.edu/support/article/102186">download the <literal>.cr</literal> file from the Netscaler Gateway</link>. After that you can configure the <command>selfservice</command> like this: + <screen> + <prompt>$ </prompt>storebrowse -C ~/Downloads/receiverconfig.cr + <prompt>$ </prompt>selfservice + </screen> + </para> </section> <section xml:id="sec-citrix-custom-certs"> <title>Custom certificates</title> <para> - The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trust several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>: + The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trusts several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>: <programlisting> <![CDATA[with import <nixpkgs> { config.allowUnfree = true; }; let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml index 4e109bd1c599..e20b0c689a80 100644 --- a/doc/builders/packages/index.xml +++ b/doc/builders/packages/index.xml @@ -18,6 +18,7 @@ <xi:include href="opengl.xml" /> <xi:include href="shell-helpers.xml" /> <xi:include href="steam.xml" /> + <xi:include href="cataclysm-dda.section.xml" /> <xi:include href="urxvt.xml" /> <xi:include href="weechat.xml" /> <xi:include href="xorg.xml" /> diff --git a/doc/builders/packages/steam.xml b/doc/builders/packages/steam.xml index 8dfede59ac1b..59673328bace 100644 --- a/doc/builders/packages/steam.xml +++ b/doc/builders/packages/steam.xml @@ -45,13 +45,7 @@ <title>How to play</title> <para> - For 64-bit systems it's important to have -<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting> - in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need -<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting> - if you are using PulseAudio - this will enable 32bit ALSA apps integration. To use the Steam controller or other Steam supported controllers such as the DualShock 4 or Nintendo Switch Pro, you need to add -<programlisting>hardware.steam-hardware.enable = true;</programlisting> - to your configuration. + Use <programlisting>programs.steam.enable = true;</programlisting> if you want to add steam to systemPackages and also enable a few workarrounds aswell as Steam controller support or other Steam supported controllers such as the DualShock 4 or Nintendo Switch Pr. </para> </section> diff --git a/doc/builders/packages/urxvt.xml b/doc/builders/packages/urxvt.xml index f85680cecc40..135cc82a0b51 100644 --- a/doc/builders/packages/urxvt.xml +++ b/doc/builders/packages/urxvt.xml @@ -50,7 +50,7 @@ map (p: p.name) pkgs.rxvt-unicode.plugins In addition to <literal>plugins</literal> the options <literal>extraDeps</literal> and <literal>perlDeps</literal> can be used to install extra packages. - <literal>extraDeps</literal> can be used, for example, to provide + <literal>extraDeps</literal> can be used, for example, to provide <literal>xsel</literal> (a clipboard manager) to the clipboard plugin, without installing it globally: <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: { diff --git a/doc/contributing/quick-start.xml b/doc/contributing/quick-start.xml index 8e4e914d4511..09d60834ec29 100644 --- a/doc/contributing/quick-start.xml +++ b/doc/contributing/quick-start.xml @@ -111,7 +111,7 @@ </para> <para> The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the <link - xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter on writing Nix expressions</link>. + xlink:href="https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter on writing Nix expressions</link>. </para> </listitem> <listitem> diff --git a/doc/contributing/submitting-changes.xml b/doc/contributing/submitting-changes.xml index 73222c1a49ac..a88965f5cc60 100644 --- a/doc/contributing/submitting-changes.xml +++ b/doc/contributing/submitting-changes.xml @@ -407,23 +407,47 @@ Additional information. <section xml:id="submitting-changes-stable-release-branches"> <title>Stable release branches</title> - <itemizedlist> + <para> + For cherry-picking a commit to a stable release branch (<quote>backporting</quote>), use <literal>git cherry-pick -x <original commit></literal> so that the original commit id is included in the commit. + </para> + + <para> + Add a reason for the backport by using <literal>git cherry-pick -xe <original commit></literal> instead when it is not obvious from the original commit message. It is not needed when it’s a minor version update that includes security and bug fixes but don’t add new features or when the commit fixes an otherwise broken package. + </para> + + <para> + Here is an example of a cherry-picked commit message with good reason description: + </para> + +<screen> +zfs: Keep trying root import until it works + +Works around #11003. + +(cherry picked from commit 98b213a11041af39b39473906b595290e2a4e2f9) + +Reason: several people cannot boot with ZFS on NVMe +</screen> + + <para> + Other examples of reasons are: + </para> + + <itemizedlist spacing="compact"> <listitem> <para> - If you're cherry-picking a commit to a stable release branch (“backporting”), always use <command>git cherry-pick -xe</command> and ensure the message contains a clear description about why this needs to be included in the stable branch. + Previously the build would fail due to, e.g., <literal>getaddrinfo</literal> not being defined </para> + </listitem> + <listitem> <para> - An example of a cherry-picked commit would look like this: + The previous download links were all broken + </para> + </listitem> + <listitem> + <para> + Crash when starting on some X11 systems </para> -<screen> -nixos: Refactor the world. - -The original commit message describing the reason why the world was torn apart. - -(cherry picked from commit abcdef) -Reason: I just had a gut feeling that this would also be wanted by people from -the stone age. -</screen> </listitem> </itemizedlist> </section> diff --git a/doc/languages-frameworks/agda.section.md b/doc/languages-frameworks/agda.section.md new file mode 100644 index 000000000000..9ce046d05b6f --- /dev/null +++ b/doc/languages-frameworks/agda.section.md @@ -0,0 +1,106 @@ +--- +title: Agda +author: Alex Rice (alexarice) +date: 2020-01-06 +--- +# Agda + +## How to use Agda + +Agda can be installed from `agda`: +``` +$ nix-env -iA agda +``` + +To use agda with libraries, the `agda.withPackages` function can be used. This function either takes: ++ A list of packages, ++ or a function which returns a list of packages when given the `agdaPackages` attribute set, ++ or an attribute set containing a list of packages and a GHC derivation for compilation (see below). + +For example, suppose we wanted a version of agda which has access to the standard library. This can be obtained with the expressions: + +``` +agda.withPackages [ agdaPackages.standard-library ] +``` + +or + +``` +agda.withPackages (p: [ p.standard-library ]) +``` + +or can be called as in the [Compiling Agda](#compiling-agda) section. + +If you want to use a library in your home directory (for instance if it is a development version) then typecheck it manually (using `agda.withPackages` if necessary) and then override the `src` attribute of the package to point to your local repository. + +Agda will not by default use these libraries. To tell agda to use the library we have some options: +- Call `agda` with the library flag: +``` +$ agda -l standard-library -i . MyFile.agda +``` +- Write a `my-library.agda-lib` file for the project you are working on which may look like: +``` +name: my-library +include: . +depend: standard-library +``` +- Create the file `~/.agda/defaults` and add any libraries you want to use by default. + +More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html). + +## Compiling Agda +Agda modules can be compiled with the `--compile` flag. A version of `ghc` with `ieee` is made available to the Agda program via the `--with-compiler` flag. +This can be overridden by a different version of `ghc` as follows: + +``` +agda.withPackages { + pkgs = [ ... ]; + ghc = haskell.compiler.ghcHEAD; +} +``` + +## Writing Agda packages +To write a nix derivation for an agda library, first check that the library has a `*.agda-lib` file. + +A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions: ++ `everythingFile` can be used to specify the location of the `Everything.agda` file, defaulting to `./Everything.agda`. If this file does not exist then either it should be patched in or the `buildPhase` should be overridden (see below). ++ `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`. ++ `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`. + +### Building Agda packages +The default build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file. +If something else is needed to build the package (e.g. `make`) then the `buildPhase` should be overridden. +Additionally, a `preBuild` or `configurePhase` can be used if there are steps that need to be done prior to checking the `Everything.agda` file. +`agda` and the Agda libraries contained in `buildInputs` are made available during the build phase. + +### Installing Agda packages +The default install phase copies agda source files, agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory. +This can be overridden. + +By default, agda sources are files ending on `.agda`, or literate agda files ending on `.lagda`, `.lagda.tex`, `.lagda.org`, `.lagda.md`, `.lagda.rst`. The list of recognised agda source extensions can be extended by setting the `extraExtensions` config variable. + +To add an agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other agda libraries, so the top line of the `default.nix` can look like: +``` +{ mkDerivation, standard-library, fetchFromGitHub }: +``` +and `mkDerivation` should be called instead of `agdaPackages.mkDerivation`. Here is an example skeleton derivation for iowa-stdlib: + +``` +mkDerivation { + version = "1.5.0"; + pname = "iowa-stdlib"; + + src = ... + + libraryFile = ""; + libraryName = "IAL-1.3"; + + buildPhase = '' + patchShebangs find-deps.sh + make + ''; +} +``` +This library has a file called `.agda-lib`, and so we give an empty string to `libraryFile` as nothing precedes `.agda-lib` in the filename. This file contains `name: IAL-1.3`, and so we let `libraryName = "IAL-1.3"`. This library does not use an `Everything.agda` file and instead has a Makefile, so there is no need to set `everythingFile` and we set a custom `buildPhase`. + +When writing an agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes agda to think that the nix store is a agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613). diff --git a/doc/languages-frameworks/android.section.md b/doc/languages-frameworks/android.section.md index 23547085b387..f4f6c086a805 100644 --- a/doc/languages-frameworks/android.section.md +++ b/doc/languages-frameworks/android.section.md @@ -167,7 +167,7 @@ parameters that the SDK composition function (the function shown in the previous section) supports. This build function is particularly useful when it is desired to use -[Hydra](http://nixos.org/hydra): the Nix-based continuous integration solution +[Hydra](https://nixos.org/hydra): the Nix-based continuous integration solution to build Android apps. An Android APK gets exposed as a build product and can be installed on any Android device with a web browser by navigating to the build result page. @@ -186,7 +186,7 @@ with import <nixpkgs> {}; androidenv.emulateApp { name = "emulate-MyAndroidApp"; platformVersion = "28"; - abiVersion = "x86_64"; # armeabi-v7a, mips, x86 + abiVersion = "x86"; # armeabi-v7a, mips, x86_64 systemImageType = "google_apis_playstore"; } ``` diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml index 278535237c2c..1d307e1d6dcf 100644 --- a/doc/languages-frameworks/beam.xml +++ b/doc/languages-frameworks/beam.xml @@ -68,7 +68,7 @@ <title>How to Install BEAM Packages</title> <para> - BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. + BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>: </para> diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md index 80e1094809ad..3663f962d5f2 100644 --- a/doc/languages-frameworks/emscripten.section.md +++ b/doc/languages-frameworks/emscripten.section.md @@ -21,11 +21,11 @@ Modes of use of `emscripten`: * **Declarative usage**: This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. - * build and install all packages: - * `nix-env -iA emscriptenPackages` - - * dev-shell for zlib implementation hacking: - * `nix-shell -A emscriptenPackages.zlib` + * build and install all packages: + * `nix-env -iA emscriptenPackages` + + * dev-shell for zlib implementation hacking: + * `nix-shell -A emscriptenPackages.zlib` ## Imperative usage @@ -90,7 +90,7 @@ See the `zlib` example: libz.so.${old.version} -I . -o example.js echo "Using node to execute the test" - ${pkgs.nodejs}/bin/node ./example.js + ${pkgs.nodejs}/bi |