doc/build-helpers.md

   1 # Build helpers {#part-builders}
   2
   3 A build helper is a function that produces derivations.
   4
   5 :::{.warning}
   6 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.
   7 :::
   8
   9 Such a function is usually designed to abstract over a typical workflow for a given programming language or framework.
  10 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.
  11
  12 [`stdenv.mkDerivation`](#part-stdenv) is the most widely used build helper, and serves as a basis for many others.
  13 In addition, it offers various options to customize parts of the builds.
  14
  15 There is no uniform interface for build helpers.
  16 [Trivial build helpers](#chap-trivial-builders) and [fetchers](#chap-pkgs-fetchers) have various input types for convenience.
  17 [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.
  18
  19 ```{=include=} chapters
  20 build-helpers/fetchers.chapter.md
  21 build-helpers/trivial-build-helpers.chapter.md
  22 build-helpers/testers.chapter.md
  23 build-helpers/dev-shell-tools.chapter.md
  24 build-helpers/special.md
  25 build-helpers/images.md
  26 hooks/index.md
  27 languages-frameworks/index.md
  28 packages/index.md
  29 ```