Commit e99021ff authored by Robert Hensing's avatar Robert Hensing
Browse files

trivial-builders: Deduplicate docs 

I didn't have the opportunity to do all work at once, so I've added
TODOs to bring attention to the situation.
parent 71866028

doc/build-helpers/fetchers.chapter.md

+4 −0
Original line number Diff line number Diff line
@@ -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)

doc/build-helpers/trivial-build-helpers.chapter.md

+9 −1
Original line number Diff line number Diff line
@@ -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}

pkgs/build-support/trivial-builders/default.nix

+47 −100
Original line number Diff line number Diff line
@@ -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"

    {