Unverified Commit 200aa036 authored by Silvan Mosberger's avatar Silvan Mosberger Committed by GitHub
Browse files

Merge pull request #262301 from ShamrockLee/doc-lib-customisation 

Generate and refine documentation for `lib.customisation`
parents 32e8db24 0695d3e8

doc/default.nix

+1 −0
Original line number Diff line number Diff line
@@ -23,6 +23,7 @@ let 
      { name = "sources"; description = "source filtering functions"; }

      { name = "cli"; description = "command-line serialization functions"; }

      { name = "gvariant"; description = "GVariant formatted string serialization functions"; }

      { name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; }

    ];

  };

lib/customisation.nix

+69 −19
Original line number Diff line number Diff line
@@ -13,16 +13,7 @@ rec { 
     scenarios (e.g. in ~/.config/nixpkgs/config.nix).  For instance,

     if you want to "patch" the derivation returned by a package

     function in Nixpkgs to build another version than what the

     function itself provides, you can do something like this:



       mySed = overrideDerivation pkgs.gnused (oldAttrs: {

         name = "sed-4.2.2-pre";

         src = fetchurl {

           url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;

           hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";

         };

         patches = [];

       });

     function itself provides.



     For another application, see build-support/vm, where this

     function is used to build arbitrary derivations inside a QEMU
@@ -35,6 +26,19 @@ rec { 


     You should in general prefer `drv.overrideAttrs` over this function;

     see the nixpkgs manual for more information on overriding.



     Example:

       mySed = overrideDerivation pkgs.gnused (oldAttrs: {

         name = "sed-4.2.2-pre";

         src = fetchurl {

           url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;

           hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";

         };

         patches = [];

       });



     Type:

       overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation

  */

  overrideDerivation = drv: f:

    let
@@ -55,6 +59,10 @@ rec { 
     injects `override` attribute which can be used to override arguments of

     the function.



     Please refer to  documentation on [`<pkg>.overrideDerivation`](#sec-pkg-overrideDerivation) to learn about `overrideDerivation` and caveats

     related to its use.



     Example:

       nix-repl> x = {a, b}: { result = a + b; }



       nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }
@@ -65,9 +73,8 @@ rec { 
       nix-repl> y.override { a = 10; }

       { override = «lambda»; overrideDerivation = «lambda»; result = 12; }



     Please refer to "Nixpkgs Contributors Guide" section

     "<pkg>.overrideDerivation" to learn about `overrideDerivation` and caveats

     related to its use.

     Type:

       makeOverridable :: (AttrSet -> a) -> AttrSet -> a

  */

  makeOverridable = f: lib.setFunctionArgs

    (origArgs: let
@@ -105,20 +112,29 @@ rec { 
    `autoArgs`.  This function is intended to be partially

    parameterised, e.g.,



      ```nix

      callPackage = callPackageWith pkgs;

      pkgs = {

        libfoo = callPackage ./foo.nix { };

        libbar = callPackage ./bar.nix { };

      };

      ```



    If the `libbar` function expects an argument named `libfoo`, it is

    automatically passed as an argument.  Overrides or missing

    arguments can be supplied in `args`, e.g.



      ```nix

      libbar = callPackage ./bar.nix {

        libfoo = null;

        enableX11 = true;

      };

      ```



    <!-- TODO: Apply "Example:" tag to the examples above -->



    Type:

      callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a

  */

  callPackageWith = autoArgs: fn: args:

    let
@@ -129,7 +145,7 @@ rec { 
      # This includes automatic ones and ones passed explicitly

      allArgs = builtins.intersectAttrs fargs autoArgs // args;



      # A list of argument names that the function requires, but

      # a list of argument names that the function requires, but

      # wouldn't be passed to it

      missingArgs = lib.attrNames

        # Filter out arguments that have a default value
@@ -176,7 +192,11 @@ rec { 


  /* Like callPackage, but for a function that returns an attribute

     set of derivations. The override function is added to the

     individual attributes. */

     individual attributes.



     Type:

       callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet

  */

  callPackagesWith = autoArgs: fn: args:

    let

      f = if lib.isFunction fn then fn else import fn;
@@ -193,7 +213,11 @@ rec { 




  /* Add attributes to each output of a derivation without changing

     the derivation itself and check a given condition when evaluating. */

     the derivation itself and check a given condition when evaluating.



     Type:

       extendDerivation :: Bool -> Any -> Derivation -> Derivation

  */

  extendDerivation = condition: passthru: drv:

    let

      outputs = drv.outputs or [ "out" ];
@@ -227,7 +251,11 @@ rec { 
  /* Strip a derivation of all non-essential attributes, returning

     only those needed by hydra-eval-jobs. Also strictly evaluate the

     result to ensure that there are no thunks kept alive to prevent

     garbage collection. */

     garbage collection.



     Type:

       hydraJob :: (Derivation | Null) -> (Derivation | Null)

  */

  hydraJob = drv:

    let

      outputs = drv.outputs or ["out"];
@@ -265,7 +293,11 @@ rec { 
     called with the overridden packages. The package sets may be

     hierarchical: the packages in the set are called with the scope

     provided by `newScope` and the set provides a `newScope` attribute

     which can form the parent scope for later package sets. */

     which can form the parent scope for later package sets.



     Type:

       makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> AttrSet

  */

  makeScope = newScope: f:

    let self = f self // {

          newScope = scope: newScope (self // scope);
@@ -287,7 +319,25 @@ rec { 
    { inherit otherSplices keep extra f; };



  /* Like makeScope, but aims to support cross compilation. It's still ugly, but

     hopefully it helps a little bit. */

     hopefully it helps a little bit.



     Type:

       makeScopeWithSplicing' ::

         { splicePackages :: Splice -> AttrSet

         , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a

         }

         -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }

         -> AttrSet



       Splice ::

         { pkgsBuildBuild :: AttrSet

         , pkgsBuildHost :: AttrSet

         , pkgsBuildTarget :: AttrSet

         , pkgsHostHost :: AttrSet

         , pkgsHostTarget :: AttrSet

         , pkgsTargetTarget :: AttrSet

         }

  */

  makeScopeWithSplicing' =

    { splicePackages

    , newScope