From cba561d1a8b71d5bd9eb6d600feddfe106620eea Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Thu, 1 Jul 2021 19:35:48 +0800 Subject: [PATCH 1/3] nixos: nixos/doc/manual/configuration/adding-custom-packages.xml to CommonMark --- .../adding-custom-packages.section.md | 74 +++++++++++++++++ .../configuration/adding-custom-packages.xml | 73 ----------------- .../configuration/declarative-packages.xml | 2 +- .../adding-custom-packages.section.xml | 81 +++++++++++++++++++ 4 files changed, 156 insertions(+), 74 deletions(-) create mode 100644 nixos/doc/manual/configuration/adding-custom-packages.section.md delete mode 100644 nixos/doc/manual/configuration/adding-custom-packages.xml create mode 100644 nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md new file mode 100644 index 000000000000..14370c891260 --- /dev/null +++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md @@ -0,0 +1,74 @@ +# Adding Custom Packages {#sec-custom-packages} + +It's possible that a package you need is not available in NixOS. In that +case, you can do two things. First, you can clone the Nixpkgs +repository, add the package to your clone, and (optionally) submit a +patch or pull request to have it accepted into the main Nixpkgs repository. +This is described in detail in the [Nixpkgs manual](https://nixos.org/nixpkgs/manual). +In short, you clone Nixpkgs: + +```ShellSession +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs +``` + +Then you write and test the package as described in the Nixpkgs manual. +Finally, you add it to [`environment.systemPackages`](options.html#opt-environment.systemPackages), e.g. + +```nix +environment.systemPackages = [ pkgs.my-package ]; +``` + +and you run `nixos-rebuild`, specifying your own Nixpkgs tree: + +```ShellSession +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs +``` + +The second possibility is to add the package outside of the Nixpkgs +tree. For instance, here is how you specify a build of the +[GNU Hello](https://www.gnu.org/software/hello/) package directly in +`configuration.nix`: + +```nix +environment.systemPackages = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; +``` + +Of course, you can also move the definition of `my-hello` into a +separate Nix expression, e.g. + +```nix +environment.systemPackages = [ (import ./my-hello.nix) ]; +``` + +where `my-hello.nix` contains: + +```nix +with import {}; # bring all of Nixpkgs into scope + +stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; +} +``` + +This allows testing the package easily: + +```ShellSession +$ nix-build my-hello.nix +$ ./result/bin/hello +Hello, world! +``` diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml deleted file mode 100644 index 19eb2429d0a0..000000000000 --- a/nixos/doc/manual/configuration/adding-custom-packages.xml +++ /dev/null @@ -1,73 +0,0 @@ -
- Adding Custom Packages - - - It’s possible that a package you need is not available in NixOS. In that - case, you can do two things. First, you can clone the Nixpkgs repository, add - the package to your clone, and (optionally) submit a patch or pull request to - have it accepted into the main Nixpkgs repository. This is described in - detail in the Nixpkgs - manual. In short, you clone Nixpkgs: - -$ git clone https://github.com/NixOS/nixpkgs -$ cd nixpkgs - - Then you write and test the package as described in the Nixpkgs manual. - Finally, you add it to environment.systemPackages, e.g. - - = [ pkgs.my-package ]; - - and you run nixos-rebuild, specifying your own Nixpkgs - tree: - -# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs - - - - The second possibility is to add the package outside of the Nixpkgs tree. For - instance, here is how you specify a build of the - GNU Hello - package directly in configuration.nix: - - = - let - my-hello = with pkgs; stdenv.mkDerivation rec { - name = "hello-2.8"; - src = fetchurl { - url = "mirror://gnu/hello/${name}.tar.gz"; - sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; - }; - }; - in - [ my-hello ]; - - Of course, you can also move the definition of my-hello - into a separate Nix expression, e.g. - - = [ (import ./my-hello.nix) ]; - - where my-hello.nix contains: - -with import <nixpkgs> {}; # bring all of Nixpkgs into scope - -stdenv.mkDerivation rec { - name = "hello-2.8"; - src = fetchurl { - url = "mirror://gnu/hello/${name}.tar.gz"; - sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; - }; -} - - This allows testing the package easily: - -$ nix-build my-hello.nix -$ ./result/bin/hello -Hello, world! - - -
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml index cd84d1951d24..648bb76cf3b2 100644 --- a/nixos/doc/manual/configuration/declarative-packages.xml +++ b/nixos/doc/manual/configuration/declarative-packages.xml @@ -50,5 +50,5 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded - + diff --git a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml new file mode 100644 index 000000000000..80e3aa692128 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml @@ -0,0 +1,81 @@ +
+ Adding Custom Packages + + It’s possible that a package you need is not available in NixOS. In + that case, you can do two things. First, you can clone the Nixpkgs + repository, add the package to your clone, and (optionally) submit a + patch or pull request to have it accepted into the main Nixpkgs + repository. This is described in detail in the + Nixpkgs + manual. In short, you clone Nixpkgs: + + +$ git clone https://github.com/NixOS/nixpkgs +$ cd nixpkgs + + + Then you write and test the package as described in the Nixpkgs + manual. Finally, you add it to + environment.systemPackages, + e.g. + + +environment.systemPackages = [ pkgs.my-package ]; + + + and you run nixos-rebuild, specifying your own + Nixpkgs tree: + + +# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs + + + The second possibility is to add the package outside of the Nixpkgs + tree. For instance, here is how you specify a build of the + GNU + Hello package directly in + configuration.nix: + + +environment.systemPackages = + let + my-hello = with pkgs; stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; + }; + in + [ my-hello ]; + + + Of course, you can also move the definition of + my-hello into a separate Nix expression, e.g. + + +environment.systemPackages = [ (import ./my-hello.nix) ]; + + + where my-hello.nix contains: + + +with import <nixpkgs> {}; # bring all of Nixpkgs into scope + +stdenv.mkDerivation rec { + name = "hello-2.8"; + src = fetchurl { + url = "mirror://gnu/hello/${name}.tar.gz"; + sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"; + }; +} + + + This allows testing the package easily: + + +$ nix-build my-hello.nix +$ ./result/bin/hello +Hello, world! + +
From 9f4535ff162f55b2a3a3620de068352382dfcd58 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Thu, 1 Jul 2021 19:36:41 +0800 Subject: [PATCH 2/3] nixos: nixos/doc/manual/configuration/customizing-packages.xml to CommonMark --- .../customizing-packages.section.md | 74 +++++++++++++++ .../configuration/customizing-packages.xml | 86 ------------------ .../configuration/declarative-packages.xml | 2 +- .../customizing-packages.section.xml | 90 +++++++++++++++++++ 4 files changed, 165 insertions(+), 87 deletions(-) create mode 100644 nixos/doc/manual/configuration/customizing-packages.section.md delete mode 100644 nixos/doc/manual/configuration/customizing-packages.xml create mode 100644 nixos/doc/manual/from_md/configuration/customizing-packages.section.xml diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md new file mode 100644 index 000000000000..480aed61211e --- /dev/null +++ b/nixos/doc/manual/configuration/customizing-packages.section.md @@ -0,0 +1,74 @@ +# Customising Packages {#sec-customising-packages} + +Some packages in Nixpkgs have options to enable or disable optional +functionality or change other aspects of the package. For instance, the +Firefox wrapper package (which provides Firefox with a set of plugins +such as the Adobe Flash player) has an option to enable the Google Talk +plugin. It can be set in `configuration.nix` as follows: +`nixpkgs.config.firefox.enableGoogleTalkPlugin = true;` + +::: {.warning} +Unfortunately, Nixpkgs currently lacks a way to query available +configuration options. +::: + +Apart from high-level options, it's possible to tweak a package in +almost arbitrary ways, such as changing or disabling dependencies of a +package. For instance, the Emacs package in Nixpkgs by default has a +dependency on GTK 2. If you want to build it against GTK 3, you can +specify that as follows: + +```nix +environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; +``` + +The function `override` performs the call to the Nix function that +produces Emacs, with the original arguments amended by the set of +arguments specified by you. So here the function argument `gtk` gets the +value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses +are necessary because in Nix, function application binds more weakly +than list construction, so without them, +[`environment.systemPackages`](options.html#opt-environment.systemPackages) +would be a list with two elements.) + +Even greater customisation is possible using the function +`overrideAttrs`. While the `override` mechanism above overrides the +arguments of a package function, `overrideAttrs` allows changing the +*attributes* passed to `mkDerivation`. This permits changing any aspect +of the package, such as the source code. For instance, if you want to +override the source code of Emacs, you can say: + +```nix +environment.systemPackages = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; +``` + +Here, `overrideAttrs` takes the Nix derivation specified by `pkgs.emacs` +and produces a new derivation in which the original's `name` and `src` +attribute have been replaced by the given values by re-calling +`stdenv.mkDerivation`. The original attributes are accessible via the +function argument, which is conventionally named `oldAttrs`. + +The overrides shown above are not global. They do not affect the +original package; other packages in Nixpkgs continue to depend on the +original rather than the customised package. This means that if another +package in your system depends on the original package, you end up with +two instances of the package. If you want to have everything depend on +your customised instance, you can apply a *global* override as follows: + +```nix +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; +``` + +The effect of this definition is essentially equivalent to modifying the +`emacs` attribute in the Nixpkgs source tree. Any package in Nixpkgs +that depends on `emacs` will be passed your customised instance. +(However, the value `pkgs.emacs` in `nixpkgs.config.packageOverrides` +refers to the original rather than overridden instance, to prevent an +infinite recursion.) diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml deleted file mode 100644 index 34e6ab4b24d6..000000000000 --- a/nixos/doc/manual/configuration/customizing-packages.xml +++ /dev/null @@ -1,86 +0,0 @@ -
- Customising Packages - - - Some packages in Nixpkgs have options to enable or disable optional - functionality or change other aspects of the package. For instance, the - Firefox wrapper package (which provides Firefox with a set of plugins such as - the Adobe Flash player) has an option to enable the Google Talk plugin. It - can be set in configuration.nix as follows: - nixpkgs.config.firefox.enableGoogleTalkPlugin = true; - - - - - Unfortunately, Nixpkgs currently lacks a way to query available - configuration options. - - - - - Apart from high-level options, it’s possible to tweak a package in almost - arbitrary ways, such as changing or disabling dependencies of a package. For - instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2. - If you want to build it against GTK 3, you can specify that as follows: - - = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; - - The function override performs the call to the Nix - function that produces Emacs, with the original arguments amended by the set - of arguments specified by you. So here the function argument - gtk gets the value pkgs.gtk3, causing - Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, - function application binds more weakly than list construction, so without - them, would be a list with - two elements.) - - - - Even greater customisation is possible using the function - overrideAttrs. While the override - mechanism above overrides the arguments of a package function, - overrideAttrs allows changing the - attributes passed to mkDerivation. - This permits changing any aspect of the package, such as the source code. For - instance, if you want to override the source code of Emacs, you can say: - - = [ - (pkgs.emacs.overrideAttrs (oldAttrs: { - name = "emacs-25.0-pre"; - src = /path/to/my/emacs/tree; - })) -]; - - Here, overrideAttrs takes the Nix derivation specified by - pkgs.emacs and produces a new derivation in which the - original’s name and src attribute - have been replaced by the given values by re-calling - stdenv.mkDerivation. The original attributes are - accessible via the function argument, which is conventionally named - oldAttrs. - - - - The overrides shown above are not global. They do not affect the original - package; other packages in Nixpkgs continue to depend on the original rather - than the customised package. This means that if another package in your - system depends on the original package, you end up with two instances of the - package. If you want to have everything depend on your customised instance, - you can apply a global override as follows: - -nixpkgs.config.packageOverrides = pkgs: - { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; - }; - - The effect of this definition is essentially equivalent to modifying the - emacs attribute in the Nixpkgs source tree. Any package in - Nixpkgs that depends on emacs will be passed your - customised instance. (However, the value pkgs.emacs in - nixpkgs.config.packageOverrides refers to the original - rather than overridden instance, to prevent an infinite recursion.) - -
diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml index 648bb76cf3b2..8d321929f3f0 100644 --- a/nixos/doc/manual/configuration/declarative-packages.xml +++ b/nixos/doc/manual/configuration/declarative-packages.xml @@ -48,7 +48,7 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded nixos-rebuild switch. - + diff --git a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml new file mode 100644 index 000000000000..661fb8475b38 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml @@ -0,0 +1,90 @@ +
+ Customising Packages + + Some packages in Nixpkgs have options to enable or disable optional + functionality or change other aspects of the package. For instance, + the Firefox wrapper package (which provides Firefox with a set of + plugins such as the Adobe Flash player) has an option to enable the + Google Talk plugin. It can be set in + configuration.nix as follows: + nixpkgs.config.firefox.enableGoogleTalkPlugin = true; + + + + Unfortunately, Nixpkgs currently lacks a way to query available + configuration options. + + + + Apart from high-level options, it’s possible to tweak a package in + almost arbitrary ways, such as changing or disabling dependencies of + a package. For instance, the Emacs package in Nixpkgs by default has + a dependency on GTK 2. If you want to build it against GTK 3, you + can specify that as follows: + + +environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; + + + The function override performs the call to the + Nix function that produces Emacs, with the original arguments + amended by the set of arguments specified by you. So here the + function argument gtk gets the value + pkgs.gtk3, causing Emacs to depend on GTK 3. (The + parentheses are necessary because in Nix, function application binds + more weakly than list construction, so without them, + environment.systemPackages + would be a list with two elements.) + + + Even greater customisation is possible using the function + overrideAttrs. While the + override mechanism above overrides the arguments + of a package function, overrideAttrs allows + changing the attributes passed to + mkDerivation. This permits changing any aspect of + the package, such as the source code. For instance, if you want to + override the source code of Emacs, you can say: + + +environment.systemPackages = [ + (pkgs.emacs.overrideAttrs (oldAttrs: { + name = "emacs-25.0-pre"; + src = /path/to/my/emacs/tree; + })) +]; + + + Here, overrideAttrs takes the Nix derivation + specified by pkgs.emacs and produces a new + derivation in which the original’s name and + src attribute have been replaced by the given + values by re-calling stdenv.mkDerivation. The + original attributes are accessible via the function argument, which + is conventionally named oldAttrs. + + + The overrides shown above are not global. They do not affect the + original package; other packages in Nixpkgs continue to depend on + the original rather than the customised package. This means that if + another package in your system depends on the original package, you + end up with two instances of the package. If you want to have + everything depend on your customised instance, you can apply a + global override as follows: + + +nixpkgs.config.packageOverrides = pkgs: + { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; }; + }; + + + The effect of this definition is essentially equivalent to modifying + the emacs attribute in the Nixpkgs source tree. + Any package in Nixpkgs that depends on emacs will + be passed your customised instance. (However, the value + pkgs.emacs in + nixpkgs.config.packageOverrides refers to the + original rather than overridden instance, to prevent an infinite + recursion.) + +
From 45a5a6815c90cddd21b358a6bd314f777b01821f Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sun, 4 Jul 2021 10:12:05 +0800 Subject: [PATCH 3/3] nixos: use only URI fragment in manual options links --- .../manual/configuration/adding-custom-packages.section.md | 2 +- .../doc/manual/configuration/customizing-packages.section.md | 2 +- .../from_md/configuration/adding-custom-packages.section.xml | 3 +-- .../from_md/configuration/customizing-packages.section.xml | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md index 14370c891260..5d1198fb0f41 100644 --- a/nixos/doc/manual/configuration/adding-custom-packages.section.md +++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md @@ -13,7 +13,7 @@ $ cd nixpkgs ``` Then you write and test the package as described in the Nixpkgs manual. -Finally, you add it to [`environment.systemPackages`](options.html#opt-environment.systemPackages), e.g. +Finally, you add it to [](#opt-environment.systemPackages), e.g. ```nix environment.systemPackages = [ pkgs.my-package ]; diff --git a/nixos/doc/manual/configuration/customizing-packages.section.md b/nixos/doc/manual/configuration/customizing-packages.section.md index 480aed61211e..bceeeb2d7a16 100644 --- a/nixos/doc/manual/configuration/customizing-packages.section.md +++ b/nixos/doc/manual/configuration/customizing-packages.section.md @@ -28,7 +28,7 @@ arguments specified by you. So here the function argument `gtk` gets the value `pkgs.gtk3`, causing Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, function application binds more weakly than list construction, so without them, -[`environment.systemPackages`](options.html#opt-environment.systemPackages) +[](#opt-environment.systemPackages) would be a list with two elements.) Even greater customisation is possible using the function diff --git a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml index 80e3aa692128..4fa40d61966e 100644 --- a/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml +++ b/nixos/doc/manual/from_md/configuration/adding-custom-packages.section.xml @@ -16,8 +16,7 @@ $ cd nixpkgs Then you write and test the package as described in the Nixpkgs manual. Finally, you add it to - environment.systemPackages, - e.g. + , e.g. environment.systemPackages = [ pkgs.my-package ]; diff --git a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml index 661fb8475b38..f78b5dc5460c 100644 --- a/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml +++ b/nixos/doc/manual/from_md/configuration/customizing-packages.section.xml @@ -33,8 +33,8 @@ environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; pkgs.gtk3, causing Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, function application binds more weakly than list construction, so without them, - environment.systemPackages - would be a list with two elements.) + would be a list + with two elements.) Even greater customisation is possible using the function