From 0fd55565d3204fbb152166c2186ba70f6cf38222 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Fri, 23 Apr 2021 12:46:02 +0800 Subject: doc/contributing/*.xml: Convert to markdown --- doc/contributing/quick-start.chapter.md | 77 +++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 doc/contributing/quick-start.chapter.md (limited to 'doc/contributing/quick-start.chapter.md') diff --git a/doc/contributing/quick-start.chapter.md b/doc/contributing/quick-start.chapter.md new file mode 100644 index 00000000000..85c3897221e --- /dev/null +++ b/doc/contributing/quick-start.chapter.md @@ -0,0 +1,77 @@ +# Quick Start to Adding a Package {#chap-quick-start} + +To add a package to Nixpkgs: + +1. Checkout the Nixpkgs source tree: + + ```ShellSession + $ git clone https://github.com/NixOS/nixpkgs + $ cd nixpkgs + ``` + +2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See for some hints on the tree organisation. Create a directory for your package, e.g. + + ```ShellSession + $ mkdir pkgs/development/libraries/libfoo + ``` + +3. In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called `default.nix`. + + ```ShellSession + $ emacs pkgs/development/libraries/libfoo/default.nix + $ git add pkgs/development/libraries/libfoo/default.nix + ``` + + You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done. Here are some good ones: + + - GNU Hello: [`pkgs/applications/misc/hello/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice. + + - GNU cpio: [`pkgs/tools/archivers/cpio/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix). Also a simple package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`. + + - GNU Multiple Precision arithmetic library (GMP): [`pkgs/development/libraries/gmp/5.1.x.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix). Also done by the generic builder, but has a dependency on `m4`. + + - Pan, a GTK-based newsreader: [`pkgs/applications/networking/newsreaders/pan/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix). Has an optional dependency on `gtkspell`, which is only built if `spellCheck` is `true`. + + - Apache HTTPD: [`pkgs/servers/http/apache-httpd/2.4.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix). A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery. + + - Thunderbird: [`pkgs/applications/networking/mailreaders/thunderbird/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix). Lots of dependencies. + + - JDiskReport, a Java utility: [`pkgs/tools/misc/jdiskreport/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc. + + - XML::Simple, a Perl module: [`pkgs/top-level/perl-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix) (search for the `XMLSimple` attribute). Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them. + + - Adobe Reader: [`pkgs/applications/misc/adobe-reader/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix). Shows how binary-only packages can be supported. In particular the [builder](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh) uses `patchelf` to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime. + + Some notes: + + - All [`meta`](#chap-meta) attributes are optional, but it’s still a good idea to provide at least the `description`, `homepage` and [`license`](#sec-meta-license). + + - You can use `nix-prefetch-url url` to get the SHA-256 hash of source distributions. There are similar commands as `nix-prefetch-git` and `nix-prefetch-hg` available in `nix-prefetch-scripts` package. + + - A list of schemes for `mirror://` URLs can be found in [`pkgs/build-support/fetchurl/mirrors.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix). + + The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the [chapter on writing Nix expressions](https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions). + +4. Add a call to the function defined in the previous step to [`pkgs/top-level/all-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix) with some descriptive name for the variable, e.g. `libfoo`. + + ```ShellSession + $ emacs pkgs/top-level/all-packages.nix + ``` + + The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name. + +5. To test whether the package builds, run the following command from the root of the nixpkgs source tree: + + ```ShellSession + $ nix-build -A libfoo + ``` + + where `libfoo` should be the variable name defined in the previous step. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created. + +6. If you want to install the package into your profile (optional), do + + ```ShellSession + $ nix-env -f . -iA libfoo + ``` + +7. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account. -- cgit 1.4.1 From 3c78ad2561a831dcbe6e193465f787019638d56b Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sun, 6 Jun 2021 13:17:54 +0200 Subject: doc: Use markdown syntax for xrefs Syntax is taken from MyST: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing --- doc/Makefile | 1 + doc/contributing/coding-conventions.chapter.md | 4 ++-- .../contributing-to-documentation.chapter.md | 5 +++++ doc/contributing/quick-start.chapter.md | 2 +- doc/functions/library/attrsets.xml | 4 ++-- doc/labelless-link-is-xref.lua | 24 ++++++++++++++++++++++ doc/stdenv/cross-compilation.chapter.md | 4 ++-- doc/stdenv/multiple-output.chapter.md | 6 +++--- doc/stdenv/stdenv.chapter.md | 14 ++++++------- doc/using/overlays.chapter.md | 2 +- 10 files changed, 48 insertions(+), 18 deletions(-) create mode 100644 doc/labelless-link-is-xref.lua (limited to 'doc/contributing/quick-start.chapter.md') diff --git a/doc/Makefile b/doc/Makefile index a208ce02f0c..85d09f3ddc0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,7 @@ pandoc_media_dir = media pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute pandoc_flags = --extract-media=$(pandoc_media_dir) \ --lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \ + --lua-filter=labelless-link-is-xref.lua \ -f commonmark$(pandoc_commonmark_enabled_extensions)+smart .PHONY: all diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index 4fa88895484..e42ba512b98 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -6,7 +6,7 @@ - Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use `(setq-default indent-tabs-mode nil)` in Emacs. Everybody has different tab settings so it’s asking for trouble. -- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in . +- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [](#sec-package-naming). - Function calls with attribute set arguments are written as @@ -209,7 +209,7 @@ There are a few naming guidelines: - Dashes in the package name _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names. -- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also +- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also [](#sec-versioning) ## File naming and organisation {#sec-organisation} diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 44feac7fbf7..2f7ae32259c 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -47,6 +47,11 @@ Additionally, the following syntax extensions are currently used: - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`. ``` +- []{#ssec-contributing-markup-automatic-links} + If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing). + + This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). + - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. diff --git a/doc/contributing/quick-start.chapter.md b/doc/contributing/quick-start.chapter.md index 85c3897221e..96b30d3822c 100644 --- a/doc/contributing/quick-start.chapter.md +++ b/doc/contributing/quick-start.chapter.md @@ -9,7 +9,7 @@ To add a package to Nixpkgs: $ cd nixpkgs ``` -2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See for some hints on the tree organisation. Create a directory for your package, e.g. +2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See [](#sec-organisation) for some hints on the tree organisation. Create a directory for your package, e.g. ```ShellSession $ mkdir pkgs/development/libraries/libfoo diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 912d6d47798..ef132514da1 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -166,7 +166,7 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3 - Like except without a default, and it will throw if the value doesn't exist. + Like [](#function-library-lib.attrsets.attrByPath) except without a default, and it will throw if the value doesn't exist. @@ -1480,7 +1480,7 @@ lib.attrsets.zipAttrsWith - Merge sets of attributes and combine each attribute value in to a list. Similar to where the merge function returns a list of all values. + Merge sets of attributes and combine each attribute value in to a list. Similar to [](#function-library-lib.attrsets.zipAttrsWith) where the merge function returns a list of all values. diff --git a/doc/labelless-link-is-xref.lua b/doc/labelless-link-is-xref.lua new file mode 100644 index 00000000000..67569b02091 --- /dev/null +++ b/doc/labelless-link-is-xref.lua @@ -0,0 +1,24 @@ +local function starts_with(start, str) + return str:sub(1, #start) == start +end + +local function escape_xml_arg(arg) + amps = arg:gsub('&', '&') + amps_quotes = amps:gsub('"', '"') + amps_quotes_lt = amps_quotes:gsub('<', '<') + + return amps_quotes_lt +end + +function Link(elem) + has_no_content = #elem.content == 0 + targets_anchor = starts_with('#', elem.target) + has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0 + + if has_no_content and targets_anchor and has_no_attributes then + -- xref expects idref without the pound-sign + target_without_hash = elem.target:sub(2, #elem.target) + + return pandoc.RawInline('docbook', '') + end +end diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index b27e9cc6fea..53522962a5c 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -65,7 +65,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv ### Theory of dependency categorization {#ssec-cross-dependency-categorization} ::: {.note} -This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to `mkDerivation`, see . For a description of how everything is implemented, see . +This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to `mkDerivation`, see [](#ssec-stdenv-dependencies). For a description of how everything is implemented, see [](#ssec-cross-dependency-implementation). ::: In this section we explore the relationship between both runtime and build-time dependencies and the 3 Autoconf platforms. @@ -158,7 +158,7 @@ One would think that `localSystem` and `crossSystem` overlap horribly with the t ### Implementation of dependencies {#ssec-cross-dependency-implementation} -The categories of dependencies developed in are specified as lists of derivations given to `mkDerivation`, as documented in . In short, each list of dependencies for "host → target" of "foo → bar" is called `depsFooBar`, with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `depsFooBar` is automatically taken from `pkgsFooBar`. (These `pkgsFooBar`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. +The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for "host → target" of "foo → bar" is called `depsFooBar`, with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `depsFooBar` is automatically taken from `pkgsFooBar`. (These `pkgsFooBar`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. Now, for most of Nixpkgs's history, there were no `pkgsFooBar` attributes, and most packages have not been refactored to use it explicitly. Prior to those, there were just `buildPackages`, `pkgs`, and `targetPackages`. Those are now redefined as aliases to `pkgsBuildHost`, `pkgsHostTarget`, and `pkgsTargetTarget`. It is acceptable, even recommended, to use them for libraries to show that the host platform is irrelevant. diff --git a/doc/stdenv/multiple-output.chapter.md b/doc/stdenv/multiple-output.chapter.md index b8414614279..d04f83302ac 100644 --- a/doc/stdenv/multiple-output.chapter.md +++ b/doc/stdenv/multiple-output.chapter.md @@ -38,7 +38,7 @@ $ nix-env -iA nixpkgs.coreutils.info installs the `"out"` output (`coreutils.meta.outputsToInstall` is `[ "out" ]`) instead of the requested `"info"`. ::: -The only recourse to select an output with `nix-env` is to override the package’s `meta.outputsToInstall`, using the functions described in . For example, the following overlay adds the `"info"` output for the `coreutils` package: +The only recourse to select an output with `nix-env` is to override the package’s `meta.outputsToInstall`, using the functions described in [](#chap-overrides). For example, the following overlay adds the `"info"` output for the `coreutils` package: ```nix self: super: @@ -53,7 +53,7 @@ self: super: In the Nix language the individual outputs can be reached explicitly as attributes, e.g. `coreutils.info`, but the typical case is just using packages as build inputs. -When a multiple-output derivation gets into a build input of another derivation, the `dev` output is added if it exists, otherwise the first output is added. In addition to that, `propagatedBuildOutputs` of that package which by default contain `$outputBin` and `$outputLib` are also added. (See .) +When a multiple-output derivation gets into a build input of another derivation, the `dev` output is added if it exists, otherwise the first output is added. In addition to that, `propagatedBuildOutputs` of that package which by default contain `$outputBin` and `$outputLib` are also added. (See [](#multiple-output-file-type-groups).) In some cases it may be desirable to combine different outputs under a single store path. A function `symlinkJoin` can be used to do this. (Note that it may negate some closure size benefits of using a multiple-output package.) @@ -70,7 +70,7 @@ outputs = [ "bin" "dev" "out" "doc" ]; Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main `out` output, as it catches any files that didn’t get elsewhere. ::: {.note} -There is a special handling of the `debug` output, described at . +There is a special handling of the `debug` output, described at [](#stdenv-separateDebugInfo). ::: ### “Binaries first” {#multiple-output-file-binaries-first-convention} diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 71eb991bbae..4daeaf7c8c2 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -39,9 +39,9 @@ stdenv.mkDerivation { } ``` -This attribute ensures that the `bin` subdirectories of these packages appear in the `PATH` environment variable during the build, that their `include` subdirectories are searched by the C compiler, and so on. (See for details.) +This attribute ensures that the `bin` subdirectories of these packages appear in the `PATH` environment variable during the build, that their `include` subdirectories are searched by the C compiler, and so on. (See [](#ssec-setup-hooks) for details.) -Often it is necessary to override or modify some aspect of the build. To make this easier, the standard environment breaks the package build into a number of *phases*, all of which can be overridden or modified individually: unpacking the sources, applying patches, configuring, building, and installing. (There are some others; see .) For instance, a package that doesn’t supply a makefile but instead has to be compiled "manually" could be handled like this: +Often it is necessary to override or modify some aspect of the build. To make this easier, the standard environment breaks the package build into a number of *phases*, all of which can be overridden or modified individually: unpacking the sources, applying patches, configuring, building, and installing. (There are some others; see [](#sec-stdenv-phases).) For instance, a package that doesn’t supply a makefile but instead has to be compiled "manually" could be handled like this: ```nix stdenv.mkDerivation { @@ -59,7 +59,7 @@ stdenv.mkDerivation { (Note the use of `''`-style string literals, which are very convenient for large multi-line script fragments because they don’t need escaping of `"` and `\`, and because indentation is intelligently removed.) -There are many other attributes to customise the build. These are listed in . +There are many other attributes to customise the build. These are listed in [](#ssec-stdenv-attributes). While the standard environment provides a generic builder, you can still supply your own build script: @@ -116,9 +116,9 @@ On Linux, `stdenv` also includes the `patchelf` utility. ## Specifying dependencies {#ssec-stdenv-dependencies} -As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to, between them, include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See for details. +As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to, between them, include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See [](#ssec-setup-hooks) for details. -Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation’s, and whether they are propagated. The platform distinctions are motivated by cross compilation; see for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case. +Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation’s, and whether they are propagated. The platform distinctions are motivated by cross compilation; see [](#chap-cross) for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case. The extension of `PATH` with dependencies, alluded to above, proceeds according to the relative platforms alone. The process is carried out only for dependencies whose host platform matches the new derivation’s build platform i.e. dependencies which run on the platform where the new derivation will be built. [^footnote-stdenv-native-dependencies-in-path] For each dependency \ of those dependencies, `dep/bin`, if present, is added to the `PATH` environment variable. @@ -911,7 +911,7 @@ This verifies that no references are left from the install binaries to the direc ### `multiple-outputs.sh` {#multiple-outputs.sh} -This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See for more information. +This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See [](#chap-multiple-output) for more information. ### `move-sbin.sh` {#move-sbin.sh} @@ -991,7 +991,7 @@ Creates a temporary package database and registers every Haskell build input in ### GNOME platform {#gnome-platform} -Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in . +Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome). ### autoPatchelfHook {#setup-hook-autopatchelfhook} diff --git a/doc/using/overlays.chapter.md b/doc/using/overlays.chapter.md index 537d031bcdb..037580583b6 100644 --- a/doc/using/overlays.chapter.md +++ b/doc/using/overlays.chapter.md @@ -63,7 +63,7 @@ The second argument (`super`) corresponds to the result of the evaluation of the The value returned by this function should be a set similar to `pkgs/top-level/all-packages.nix`, containing overridden and/or new packages. -Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in. Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute. +Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in [](#sec-modify-via-packageOverrides). Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute. ## Using overlays to configure alternatives {#sec-overlays-alternatives} -- cgit 1.4.1