Merge pull request #294944 from hercules-ci/docs-dedup-trivial-builders
trivial-builders: Deduplicate docs
This commit is contained in:
Silvan Mosberger
GitHub
commit
1d14cc5182
3 changed files with 60 additions and 101 deletions
|
|
@ -262,6 +262,10 @@ or
|
|||
|
||||
***
|
||||
```
|
||||
|
||||
This function should only be used by non-redistributable software with an unfree license that we need to require the user to download manually.
|
||||
It produces packages that cannot be built automatically.
|
||||
|
||||
## `fetchtorrent` {#fetchtorrent}
|
||||
|
||||
`fetchtorrent` expects two arguments. `url` which can either be a Magnet URI (Magnet Link) such as `magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c` or an HTTP URL pointing to a `.torrent` file. It can also take a `config` argument which will craft a `settings.json` configuration file and give it to `transmission`, the underlying program that is performing the fetch. The available config options for `transmission` can be found [here](https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md#options)
|
||||
|
|
|
|||
|
|
@ -7,7 +7,9 @@ Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers cre
|
|||
|
||||
`runCommand :: String -> AttrSet -> String -> Derivation`
|
||||
|
||||
`runCommand name drvAttrs buildCommand` returns a derivation that is built by running the specified shell commands.
|
||||
The result of `runCommand name drvAttrs buildCommand` is a derivation that is built by running the specified shell commands.
|
||||
|
||||
By default `runCommand` runs in a stdenv with no compiler environment, whereas [`runCommandCC`](#trivial-builder-runCommandCC) uses the default stdenv, `pkgs.stdenv`.
|
||||
|
||||
`name :: String`
|
||||
: The name that Nix will append to the store path in the same way that `stdenv.mkDerivation` uses its `name` attribute.
|
||||
|
|
@ -153,6 +155,12 @@ Write a text file to the Nix store.
|
|||
|
||||
Default: `true`
|
||||
|
||||
`derivationArgs` (Attribute set, _optional_)
|
||||
|
||||
: Extra arguments to pass to the underlying call to `stdenv.mkDerivation`.
|
||||
|
||||
Default: `{}`
|
||||
|
||||
The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory.
|
||||
|
||||
::: {.example #ex-writeTextFile}
|
||||
|
|
|
|||
|
|
@ -9,55 +9,24 @@ in
|
|||
|
||||
rec {
|
||||
|
||||
/*
|
||||
Run the shell command `buildCommand` to produce a store path named `name`.
|
||||
|
||||
The attributes in `env` are added to the environment prior to running the command.
|
||||
Environment variables set by `stdenv.mkDerivation` take precedence.
|
||||
|
||||
By default `runCommand` runs in a stdenv with no compiler environment.
|
||||
`runCommandCC` uses the default stdenv, `pkgs.stdenv`.
|
||||
|
||||
Example:
|
||||
|
||||
```nix
|
||||
runCommand "name" {envVariable = true;} ''echo hello > $out'';
|
||||
```
|
||||
|
||||
```nix
|
||||
runCommandCC "name" {} ''gcc -o myfile myfile.c; cp myfile $out'';
|
||||
```
|
||||
|
||||
The `*Local` variants force a derivation to be built locally,
|
||||
it is not substituted.
|
||||
|
||||
This is intended for very cheap commands (<1s execution time).
|
||||
It saves on the network roundrip and can speed up a build.
|
||||
|
||||
It is the same as adding the special fields
|
||||
|
||||
```nix
|
||||
{
|
||||
preferLocalBuild = true;
|
||||
allowSubstitutes = false;
|
||||
}
|
||||
```
|
||||
|
||||
to a derivation’s attributes.
|
||||
*/
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-runCommand
|
||||
runCommand = name: env: runCommandWith {
|
||||
stdenv = stdenvNoCC;
|
||||
runLocal = false;
|
||||
inherit name;
|
||||
derivationArgs = env;
|
||||
};
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-runCommandLocal
|
||||
runCommandLocal = name: env: runCommandWith {
|
||||
stdenv = stdenvNoCC;
|
||||
runLocal = true;
|
||||
inherit name;
|
||||
derivationArgs = env;
|
||||
};
|
||||
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-runCommandCC
|
||||
runCommandCC = name: env: runCommandWith {
|
||||
stdenv = stdenv;
|
||||
runLocal = false;
|
||||
|
|
@ -67,6 +36,7 @@ rec {
|
|||
# `runCommandCCLocal` left out on purpose.
|
||||
# We shouldn’t force the user to have a cc in scope.
|
||||
|
||||
# TODO: Move documentation for runCommandWith to the Nixpkgs manual
|
||||
/*
|
||||
Generalized version of the `runCommand`-variants
|
||||
which does customized behavior via a single
|
||||
|
|
@ -112,47 +82,18 @@ rec {
|
|||
// builtins.removeAttrs derivationArgs [ "passAsFile" ]);
|
||||
|
||||
|
||||
/*
|
||||
Writes a text file to the nix store.
|
||||
The contents of text is added to the file in the store.
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
# Writes my-file to /nix/store/<store path>
|
||||
writeTextFile {
|
||||
name = "my-file";
|
||||
text = ''
|
||||
Contents of File
|
||||
'';
|
||||
}
|
||||
|
||||
|
||||
See also the `writeText` helper function below.
|
||||
|
||||
|
||||
# Writes executable my-file to /nix/store/<store path>/bin/my-file
|
||||
writeTextFile {
|
||||
name = "my-file";
|
||||
text = ''
|
||||
Contents of File
|
||||
'';
|
||||
executable = true;
|
||||
destination = "/bin/my-file";
|
||||
}
|
||||
|
||||
|
||||
*/
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeTextFile
|
||||
writeTextFile =
|
||||
{ name # the name of the derivation
|
||||
{ name
|
||||
, text
|
||||
, executable ? false # run chmod +x ?
|
||||
, destination ? "" # relative path appended to $out eg "/bin/foo"
|
||||
, checkPhase ? "" # syntax checks, e.g. for scripts
|
||||
, executable ? false
|
||||
, destination ? ""
|
||||
, checkPhase ? ""
|
||||
, meta ? { }
|
||||
, allowSubstitutes ? false
|
||||
, preferLocalBuild ? true
|
||||
, derivationArgs ? { } # Extra arguments to pass to `stdenv.mkDerivation`
|
||||
, derivationArgs ? { }
|
||||
}:
|
||||
let
|
||||
matches = builtins.match "/bin/([^/]+)" destination;
|
||||
|
|
@ -240,8 +181,9 @@ rec {
|
|||
meta.mainProgram = name;
|
||||
};
|
||||
|
||||
# TODO: move parameter documentation to the Nixpkgs manual
|
||||
# See doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing
|
||||
# or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeShellApplication
|
||||
writeShellApplication =
|
||||
{
|
||||
/*
|
||||
|
|
@ -357,6 +299,7 @@ rec {
|
|||
};
|
||||
|
||||
# Create a C binary
|
||||
# TODO: add to writers? pkgs/build-support/writers
|
||||
writeCBin = pname: code:
|
||||
runCommandCC pname
|
||||
{
|
||||
|
|
@ -377,7 +320,9 @@ rec {
|
|||
$CC -x c code.c -o "$n"
|
||||
'';
|
||||
|
||||
|
||||
# TODO: deduplicate with documentation in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# see also https://github.com/NixOS/nixpkgs/pull/249721
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-concatText
|
||||
/* concat a list of files to the nix store.
|
||||
The contents of files are added to the file in the store.
|
||||
|
||||
|
|
@ -426,7 +371,9 @@ rec {
|
|||
eval "$checkPhase"
|
||||
'';
|
||||
|
||||
|
||||
# TODO: deduplicate with documentation in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# see also https://github.com/NixOS/nixpkgs/pull/249721
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-concatText
|
||||
/*
|
||||
Writes a text file to nix store with no optional parameters available.
|
||||
|
||||
|
|
@ -440,6 +387,9 @@ rec {
|
|||
*/
|
||||
concatText = name: files: concatTextFile { inherit name files; };
|
||||
|
||||
# TODO: deduplicate with documentation in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# see also https://github.com/NixOS/nixpkgs/pull/249721
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-concatText
|
||||
/*
|
||||
Writes a text file to nix store with and mark it as executable.
|
||||
|
||||
|
|
@ -452,6 +402,10 @@ rec {
|
|||
|
||||
|
||||
/*
|
||||
TODO: Deduplicate this documentation.
|
||||
More docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-symlinkJoin
|
||||
|
||||
Create a forest of symlinks to the files in `paths`.
|
||||
|
||||
This creates a single derivation that replicates the directory structure
|
||||
|
|
@ -528,6 +482,7 @@ rec {
|
|||
${postBuild}
|
||||
'';
|
||||
|
||||
# TODO: move linkFarm docs to the Nixpkgs manual
|
||||
/*
|
||||
Quickly create a set of symlinks to derivations.
|
||||
|
||||
|
|
@ -584,6 +539,7 @@ rec {
|
|||
${lib.concatStrings linkCommands}
|
||||
'';
|
||||
|
||||
# TODO: move linkFarmFromDrvs docs to the Nixpkgs manual
|
||||
/*
|
||||
Easily create a linkFarm from a set of derivations.
|
||||
|
||||
|
|
@ -609,6 +565,7 @@ rec {
|
|||
let mkEntryFromDrv = drv: { name = drv.name; path = drv; };
|
||||
in linkFarm name (map mkEntryFromDrv drvs);
|
||||
|
||||
# TODO: move onlyBin docs to the Nixpkgs manual
|
||||
/*
|
||||
Produce a derivation that links to the target derivation's `/bin`,
|
||||
and *only* `/bin`.
|
||||
|
|
@ -623,7 +580,8 @@ rec {
|
|||
'';
|
||||
|
||||
|
||||
# docs in doc/builders/special/makesetuphook.section.md
|
||||
# Docs in doc/builders/special/makesetuphook.section.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#sec-pkgs.makeSetupHook
|
||||
makeSetupHook =
|
||||
{ name ? lib.warn "calling makeSetupHook without passing a name is deprecated." "hook"
|
||||
, deps ? [ ]
|
||||
|
|
@ -665,8 +623,8 @@ rec {
|
|||
'');
|
||||
|
||||
|
||||
# Write the references (i.e. the runtime dependencies in the Nix store) of `path` to a file.
|
||||
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeReferencesToFile
|
||||
writeReferencesToFile = path: runCommand "runtime-deps"
|
||||
{
|
||||
exportReferencesGraph = [ "graph" path ];
|
||||
|
|
@ -681,11 +639,8 @@ rec {
|
|||
done < graph
|
||||
'';
|
||||
|
||||
/*
|
||||
Write the set of references to a file, that is, their immediate dependencies.
|
||||
|
||||
This produces the equivalent of `nix-store -q --references`.
|
||||
*/
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeDirectReferencesToFile
|
||||
writeDirectReferencesToFile = path: runCommand "runtime-references"
|
||||
{
|
||||
exportReferencesGraph = [ "graph" path ];
|
||||
|
|
@ -710,7 +665,7 @@ rec {
|
|||
sort ./references >$out
|
||||
'';
|
||||
|
||||
|
||||
# TODO: move writeStringReferencesToFile docs to the Nixpkgs manual
|
||||
/*
|
||||
Extract a string's references to derivations and paths (its
|
||||
context) and write them to a text file, removing the input string
|
||||
|
|
@ -793,21 +748,8 @@ rec {
|
|||
writeDirectReferencesToFile (writeText "string-file" string);
|
||||
|
||||
|
||||
/* Print an error message if the file with the specified name and
|
||||
hash doesn't exist in the Nix store. This function should only
|
||||
be used by non-redistributable software with an unfree license
|
||||
that we need to require the user to download manually. It produces
|
||||
packages that cannot be built automatically.
|
||||
|
||||
Example:
|
||||
|
||||
requireFile {
|
||||
name = "my-file";
|
||||
url = "http://example.com/download/";
|
||||
sha256 = "ffffffffffffffffffffffffffffffffffffffffffffffffffff";
|
||||
}
|
||||
|
||||
*/
|
||||
# Docs in doc/build-helpers/fetchers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#requirefile
|
||||
requireFile =
|
||||
{ name ? null
|
||||
, sha256 ? null
|
||||
|
|
@ -863,6 +805,7 @@ rec {
|
|||
};
|
||||
|
||||
|
||||
# TODO: move copyPathToStore docs to the Nixpkgs manual
|
||||
/*
|
||||
Copy a path to the Nix store.
|
||||
Nix automatically copies files to the store before stringifying paths.
|
||||
|
|
@ -872,11 +815,13 @@ rec {
|
|||
copyPathToStore = builtins.filterSource (p: t: true);
|
||||
|
||||
|
||||
# TODO: move copyPathsToStore docs to the Nixpkgs manual
|
||||
/*
|
||||
Copy a list of paths to the Nix store.
|
||||
*/
|
||||
copyPathsToStore = builtins.map copyPathToStore;
|
||||
|
||||
# TODO: move applyPatches docs to the Nixpkgs manual
|
||||
/* Applies a list of patches to a source directory.
|
||||
|
||||
Example:
|
||||
|
|
@ -922,6 +867,7 @@ rec {
|
|||
// (optionalAttrs (src?meta) { inherit (src) meta; })
|
||||
// (removeAttrs args [ "src" "name" "patches" "prePatch" "postPatch" ]));
|
||||
|
||||
# TODO: move docs to Nixpkgs manual
|
||||
/* An immutable file in the store with a length of 0 bytes. */
|
||||
emptyFile = runCommand "empty-file"
|
||||
{
|
||||
|
|
@ -931,6 +877,7 @@ rec {
|
|||
preferLocalBuild = true;
|
||||
} "touch $out";
|
||||
|
||||
# TODO: move docs to Nixpkgs manual
|
||||
/* An immutable empty directory in the store. */
|
||||
emptyDirectory = runCommand "empty-directory"
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue