diff options
| author | Yueh-Shun Li <shamrocklee@posteo.net> | 2023-05-28 21:48:43 +0800 |
|---|---|---|
| committer | Yueh-Shun Li <shamrocklee@posteo.net> | 2023-11-07 19:58:54 +0000 |
| commit | 8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066 (patch) | |
| tree | 3dd33f2d9a23cb0ce439477e7462d4ef731ca014 /doc/build-helpers.md | |
| parent | 9963ad5c5fbbe55fb310e9477cab2fa685afaac2 (diff) | |
| download | nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar.gz nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar.bz2 nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar.lz nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar.xz nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.tar.zst nixlib-8cd8a5152eba81fbee4ccef18f98a9d8f2a1a066.zip | |
doc: add introduction to build helpers
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Diffstat (limited to 'doc/build-helpers.md')
| -rw-r--r-- | doc/build-helpers.md | 16 |
1 files changed, 16 insertions, 0 deletions
diff --git a/doc/build-helpers.md b/doc/build-helpers.md index 40ce7173a221..06737e166760 100644 --- a/doc/build-helpers.md +++ b/doc/build-helpers.md @@ -1,5 +1,21 @@ # 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 |