diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f8278d1cbe48..59348b7b27aa 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -61,7 +61,7 @@ /pkgs/build-support/writers @lassulus @Profpatsch # Nixpkgs make-disk-image -/doc/builders/images/makediskimage.section.md @raitobezarius +/doc/build-helpers/images/makediskimage.section.md @raitobezarius /nixos/lib/make-disk-image.nix @raitobezarius # Nixpkgs documentation @@ -219,7 +219,7 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt /nixos/tests/knot.nix @mweinelt # Web servers -/doc/builders/packages/nginx.section.md @raitobezarius +/doc/packages/nginx.section.md @raitobezarius /pkgs/servers/http/nginx/ @raitobezarius /nixos/modules/services/web-servers/nginx/ @raitobezarius @@ -272,7 +272,7 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt # Docker tools /pkgs/build-support/docker @roberth /nixos/tests/docker-tools* @roberth -/doc/builders/images/dockertools.section.md @roberth +/doc/build-helpers/images/dockertools.section.md @roberth # Blockchains /pkgs/applications/blockchains @mmahut @RaghavSood diff --git a/doc/build-helpers.md b/doc/build-helpers.md new file mode 100644 index 000000000000..06737e166760 --- /dev/null +++ b/doc/build-helpers.md @@ -0,0 +1,28 @@ +# Build helpers {#part-builders} + +A build helper is a function that produces derivations. + +:::{.warning} +This is not to be confused with the [`builder` argument of the Nix `derivation` primitive](https://nixos.org/manual/nix/unstable/language/derivations.html), which refers to the executable that produces the build result, or [remote builder](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds.html), which refers to a remote machine that could run such an executable. +::: + +Such a function is usually designed to abstract over a typical workflow for a given programming language or framework. +This allows declaring a build recipe by setting a limited number of options relevant to the particular use case instead of using the `derivation` function directly. + +[`stdenv.mkDerivation`](#part-stdenv) is the most widely used build helper, and serves as a basis for many others. +In addition, it offers various options to customize parts of the builds. + +There is no uniform interface for build helpers. +[Trivial build helpers](#chap-trivial-builders) and [fetchers](#chap-pkgs-fetchers) have various input types for convenience. +[Language- or framework-specific build helpers](#chap-language-support) usually follow the style of `stdenv.mkDerivation`, which accepts an attribute set or a fixed-point function taking an attribute set. + +```{=include=} chapters +build-helpers/fetchers.chapter.md +build-helpers/trivial-build-helpers.chapter.md +build-helpers/testers.chapter.md +build-helpers/special.md +build-helpers/images.md +hooks/index.md +languages-frameworks/index.md +packages/index.md +``` diff --git a/doc/builders/fetchers.chapter.md b/doc/build-helpers/fetchers.chapter.md similarity index 100% rename from doc/builders/fetchers.chapter.md rename to doc/build-helpers/fetchers.chapter.md diff --git a/doc/builders/images.md b/doc/build-helpers/images.md similarity index 100% rename from doc/builders/images.md rename to doc/build-helpers/images.md diff --git a/doc/builders/images/appimagetools.section.md b/doc/build-helpers/images/appimagetools.section.md similarity index 100% rename from doc/builders/images/appimagetools.section.md rename to doc/build-helpers/images/appimagetools.section.md diff --git a/doc/builders/images/binarycache.section.md b/doc/build-helpers/images/binarycache.section.md similarity index 100% rename from doc/builders/images/binarycache.section.md rename to doc/build-helpers/images/binarycache.section.md diff --git a/doc/builders/images/dockertools.section.md b/doc/build-helpers/images/dockertools.section.md similarity index 100% rename from doc/builders/images/dockertools.section.md rename to doc/build-helpers/images/dockertools.section.md diff --git a/doc/builders/images/makediskimage.section.md b/doc/build-helpers/images/makediskimage.section.md similarity index 100% rename from doc/builders/images/makediskimage.section.md rename to doc/build-helpers/images/makediskimage.section.md diff --git a/doc/builders/images/ocitools.section.md b/doc/build-helpers/images/ocitools.section.md similarity index 100% rename from doc/builders/images/ocitools.section.md rename to doc/build-helpers/images/ocitools.section.md diff --git a/doc/builders/images/portableservice.section.md b/doc/build-helpers/images/portableservice.section.md similarity index 100% rename from doc/builders/images/portableservice.section.md rename to doc/build-helpers/images/portableservice.section.md diff --git a/doc/builders/images/snaptools.section.md b/doc/build-helpers/images/snaptools.section.md similarity index 100% rename from doc/builders/images/snaptools.section.md rename to doc/build-helpers/images/snaptools.section.md diff --git a/doc/builders/special.md b/doc/build-helpers/special.md similarity index 56% rename from doc/builders/special.md rename to doc/build-helpers/special.md index 6d07fa87f3f3..f88648207fdc 100644 --- a/doc/builders/special.md +++ b/doc/build-helpers/special.md @@ -1,11 +1,10 @@ -# Special builders {#chap-special} +# Special build helpers {#chap-special} -This chapter describes several special builders. +This chapter describes several special build helpers. ```{=include=} sections special/fhs-environments.section.md special/makesetuphook.section.md special/mkshell.section.md -special/darwin-builder.section.md special/vm-tools.section.md ``` diff --git a/doc/builders/special/fhs-environments.section.md b/doc/build-helpers/special/fhs-environments.section.md similarity index 100% rename from doc/builders/special/fhs-environments.section.md rename to doc/build-helpers/special/fhs-environments.section.md diff --git a/doc/builders/special/makesetuphook.section.md b/doc/build-helpers/special/makesetuphook.section.md similarity index 91% rename from doc/builders/special/makesetuphook.section.md rename to doc/build-helpers/special/makesetuphook.section.md index eb042412137b..e83164b7eb70 100644 --- a/doc/builders/special/makesetuphook.section.md +++ b/doc/build-helpers/special/makesetuphook.section.md @@ -1,6 +1,6 @@ # pkgs.makeSetupHook {#sec-pkgs.makeSetupHook} -`pkgs.makeSetupHook` is a builder that produces hooks that go in to `nativeBuildInputs` +`pkgs.makeSetupHook` is a build helper that produces hooks that go in to `nativeBuildInputs` ## Usage {#sec-pkgs.makeSetupHook-usage} diff --git a/doc/builders/special/mkshell.section.md b/doc/build-helpers/special/mkshell.section.md similarity index 100% rename from doc/builders/special/mkshell.section.md rename to doc/build-helpers/special/mkshell.section.md diff --git a/doc/builders/special/vm-tools.section.md b/doc/build-helpers/special/vm-tools.section.md similarity index 100% rename from doc/builders/special/vm-tools.section.md rename to doc/build-helpers/special/vm-tools.section.md diff --git a/doc/builders/testers.chapter.md b/doc/build-helpers/testers.chapter.md similarity index 100% rename from doc/builders/testers.chapter.md rename to doc/build-helpers/testers.chapter.md diff --git a/doc/builders/trivial-builders.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md similarity index 99% rename from doc/builders/trivial-builders.chapter.md rename to doc/build-helpers/trivial-build-helpers.chapter.md index 2cb1f2debcb8..a0cda86a6607 100644 --- a/doc/builders/trivial-builders.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -1,4 +1,4 @@ -# Trivial builders {#chap-trivial-builders} +# Trivial build helpers {#chap-trivial-builders} Nixpkgs provides a couple of functions that help with building derivations. The most important one, `stdenv.mkDerivation`, has already been documented above. The following functions wrap `stdenv.mkDerivation`, making it easier to use in certain cases. diff --git a/doc/builders.md b/doc/builders.md deleted file mode 100644 index 2e959422405b..000000000000 --- a/doc/builders.md +++ /dev/null @@ -1,12 +0,0 @@ -# Builders {#part-builders} - -```{=include=} chapters -builders/fetchers.chapter.md -builders/trivial-builders.chapter.md -builders/testers.chapter.md -builders/special.md -builders/images.md -hooks/index.md -languages-frameworks/index.md -builders/packages/index.md -``` diff --git a/doc/manual.md.in b/doc/manual.md.in index 6b8d351380f9..52971ff526c2 100644 --- a/doc/manual.md.in +++ b/doc/manual.md.in @@ -9,7 +9,7 @@ preface.chapter.md using-nixpkgs.md lib.md stdenv.md -builders.md +build-helpers.md development.md contributing.md ``` diff --git a/doc/builders/packages/cataclysm-dda.section.md b/doc/packages/cataclysm-dda.section.md similarity index 100% rename from doc/builders/packages/cataclysm-dda.section.md rename to doc/packages/cataclysm-dda.section.md diff --git a/doc/builders/packages/citrix.section.md b/doc/packages/citrix.section.md similarity index 100% rename from doc/builders/packages/citrix.section.md rename to doc/packages/citrix.section.md diff --git a/doc/builders/special/darwin-builder.section.md b/doc/packages/darwin-builder.section.md similarity index 87% rename from doc/builders/special/darwin-builder.section.md rename to doc/packages/darwin-builder.section.md index e37fabe01a35..89c2445667dc 100644 --- a/doc/builders/special/darwin-builder.section.md +++ b/doc/packages/darwin-builder.section.md @@ -1,10 +1,10 @@ # darwin.linux-builder {#sec-darwin-builder} -`darwin.linux-builder` provides a way to bootstrap a Linux builder on a macOS machine. +`darwin.linux-builder` provides a way to bootstrap a Linux remote builder on a macOS machine. This requires macOS version 12.4 or later. -The builder runs on host port 31022 by default. +The remote builder runs on host port 31022 by default. You can change it by overriding `virtualisation.darwin-builder.hostPort`. See the [example](#sec-darwin-builder-example-flake). @@ -15,7 +15,7 @@ words, your `/etc/nix/nix.conf` should have something like: extra-trusted-users = ``` -To launch the builder, run the following flake: +To launch the remote builder, run the following flake: ```ShellSession $ nix run nixpkgs#darwin.linux-builder @@ -57,7 +57,7 @@ builders = ssh-ng://builder@linux-builder ${ARCH}-linux /etc/nix/builder_ed25519 builders-use-substitutes = true ``` -To allow Nix to connect to a builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`: +To allow Nix to connect to a remote builder not running on port 22, you will also need to create a new file at `/etc/ssh/ssh_config.d/100-linux-builder.conf`: ``` Host linux-builder @@ -130,11 +130,11 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon } ``` -## Reconfiguring the builder {#sec-darwin-builder-reconfiguring} +## Reconfiguring the remote builder {#sec-darwin-builder-reconfiguring} -Initially you should not change the builder configuration else you will not be -able to use the binary cache. However, after you have the builder running locally -you may use it to build a modified builder with additional storage or memory. +Initially you should not change the remote builder configuration else you will not be +able to use the binary cache. However, after you have the remote builder running locally +you may use it to build a modified remote builder with additional storage or memory. To do this, you just need to set the `virtualisation.darwin-builder.*` parameters as in the example below and rebuild. diff --git a/doc/builders/packages/dlib.section.md b/doc/packages/dlib.section.md similarity index 100% rename from doc/builders/packages/dlib.section.md rename to doc/packages/dlib.section.md diff --git a/doc/builders/packages/eclipse.section.md b/doc/packages/eclipse.section.md similarity index 100% rename from doc/builders/packages/eclipse.section.md rename to doc/packages/eclipse.section.md diff --git a/doc/builders/packages/elm.section.md b/doc/packages/elm.section.md similarity index 100% rename from doc/builders/packages/elm.section.md rename to doc/packages/elm.section.md diff --git a/doc/builders/packages/emacs.section.md b/doc/packages/emacs.section.md similarity index 100% rename from doc/builders/packages/emacs.section.md rename to doc/packages/emacs.section.md diff --git a/doc/builders/packages/etc-files.section.md b/doc/packages/etc-files.section.md similarity index 100% rename from doc/builders/packages/etc-files.section.md rename to doc/packages/etc-files.section.md diff --git a/doc/builders/packages/firefox.section.md b/doc/packages/firefox.section.md similarity index 100% rename from doc/builders/packages/firefox.section.md rename to doc/packages/firefox.section.md diff --git a/doc/builders/packages/fish.section.md b/doc/packages/fish.section.md similarity index 100% rename from doc/builders/packages/fish.section.md rename to doc/packages/fish.section.md diff --git a/doc/builders/packages/fuse.section.md b/doc/packages/fuse.section.md similarity index 100% rename from doc/builders/packages/fuse.section.md rename to doc/packages/fuse.section.md diff --git a/doc/builders/packages/ibus.section.md b/doc/packages/ibus.section.md similarity index 100% rename from doc/builders/packages/ibus.section.md rename to doc/packages/ibus.section.md diff --git a/doc/builders/packages/index.md b/doc/packages/index.md similarity index 95% rename from doc/builders/packages/index.md rename to doc/packages/index.md index 1f4435702406..1f45018ffc4a 100644 --- a/doc/builders/packages/index.md +++ b/doc/packages/index.md @@ -4,6 +4,7 @@ This chapter contains information about how to use and maintain the Nix expressi ```{=include=} sections citrix.section.md +darwin-builder.section.md dlib.section.md eclipse.section.md elm.section.md diff --git a/doc/builders/packages/kakoune.section.md b/doc/packages/kakoune.section.md similarity index 100% rename from doc/builders/packages/kakoune.section.md rename to doc/packages/kakoune.section.md diff --git a/doc/builders/packages/linux.section.md b/doc/packages/linux.section.md similarity index 100% rename from doc/builders/packages/linux.section.md rename to doc/packages/linux.section.md diff --git a/doc/builders/packages/locales.section.md b/doc/packages/locales.section.md similarity index 100% rename from doc/builders/packages/locales.section.md rename to doc/packages/locales.section.md diff --git a/doc/builders/packages/nginx.section.md b/doc/packages/nginx.section.md similarity index 100% rename from doc/builders/packages/nginx.section.md rename to doc/packages/nginx.section.md diff --git a/doc/builders/packages/opengl.section.md b/doc/packages/opengl.section.md similarity index 100% rename from doc/builders/packages/opengl.section.md rename to doc/packages/opengl.section.md diff --git a/doc/builders/packages/shell-helpers.section.md b/doc/packages/shell-helpers.section.md similarity index 100% rename from doc/builders/packages/shell-helpers.section.md rename to doc/packages/shell-helpers.section.md diff --git a/doc/builders/packages/steam.section.md b/doc/packages/steam.section.md similarity index 100% rename from doc/builders/packages/steam.section.md rename to doc/packages/steam.section.md diff --git a/doc/builders/packages/urxvt.section.md b/doc/packages/urxvt.section.md similarity index 100% rename from doc/builders/packages/urxvt.section.md rename to doc/packages/urxvt.section.md diff --git a/doc/builders/packages/weechat.section.md b/doc/packages/weechat.section.md similarity index 100% rename from doc/builders/packages/weechat.section.md rename to doc/packages/weechat.section.md diff --git a/doc/builders/packages/xorg.section.md b/doc/packages/xorg.section.md similarity index 100% rename from doc/builders/packages/xorg.section.md rename to doc/packages/xorg.section.md diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 1dfe25f02654..53243af5f239 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -528,7 +528,7 @@ If the returned array contains exactly one object (e.g. `[{}]`), all values are ``` ::: -### Recursive attributes in `mkDerivation` {#mkderivation-recursive-attributes} +### Fixed-point arguments of `mkDerivation` {#mkderivation-recursive-attributes} If you pass a function to `mkDerivation`, it will receive as its argument the final arguments, including the overrides when reinvoked via `overrideAttrs`. For example: