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 00000000000..480aed61211 --- /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 34e6ab4b24d..00000000000 --- 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 648bb76cf3b..8d321929f3f 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 00000000000..661fb8475b3 --- /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.) + +