From 195fe01e8bd258b5f4475203c9fd72b69c87a22f Mon Sep 17 00:00:00 2001 From: Alex Brandt Date: Mon, 30 Nov 2020 20:56:33 +0000 Subject: nixos/nixpkgs/docs: fix typo in assertOneOf example This example was confusing at first because the element the message indicated wasn't in the list of possible values was but the possible values didn't match up either. This ensures the example is consistent with the logic being presented. --- doc/functions/library/asserts.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/functions') diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml index 10891039e86..7c94222ef13 100644 --- a/doc/functions/library/asserts.xml +++ b/doc/functions/library/asserts.xml @@ -103,7 +103,7 @@ stderr> assert failed Ensuring a user provided a possible value false stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" ]]> -- cgit 1.4.1 From 123045a57056b997165be4963cbf62120a967fec Mon Sep 17 00:00:00 2001 From: Jacek Galowicz Date: Mon, 25 Jan 2021 16:59:46 +0100 Subject: lib/attrsets: add cartesianProductOfSets function --- doc/functions/library/attrsets.xml | 39 ++++++++++++++++++++++ lib/attrsets.nix | 19 ++++++++++- lib/default.nix | 2 +- lib/tests/misc.nix | 67 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 125 insertions(+), 2 deletions(-) (limited to 'doc/functions') diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 3c5823c2589..7ef0d16624c 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -1711,4 +1711,43 @@ recursiveUpdate +
+ <function>lib.attrsets.cartesianProductOfSets</function> + + cartesianProductOfSets :: AttrSet -> [ AttrSet ] + + + + + + Return the cartesian product of attribute set value combinations. + + + + + + set + + + + An attribute set with attributes that carry lists of values. + + + + + + + Creating the cartesian product of a list of attribute values + [ + { a = 1; b = 10; } + { a = 1; b = 20; } + { a = 2; b = 10; } + { a = 2; b = 20; } + ] +]]> + +
+ diff --git a/lib/attrsets.nix b/lib/attrsets.nix index d91d7a0cd47..0ce3aaeca45 100644 --- a/lib/attrsets.nix +++ b/lib/attrsets.nix @@ -183,6 +183,24 @@ rec { else []; + /* Return the cartesian product of attribute set value combinations. + + Example: + cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; } + => [ + { a = 1; b = 10; } + { a = 1; b = 20; } + { a = 2; b = 10; } + { a = 2; b = 20; } + ] + */ + cartesianProductOfSets = attrsOfLists: + lib.foldl' (listOfAttrs: attrName: + concatMap (attrs: + map (listValue: attrs // { ${attrName} = listValue; }) attrsOfLists.${attrName} + ) listOfAttrs + ) [{}] (attrNames attrsOfLists); + /* Utility function that creates a {name, value} pair as expected by builtins.listToAttrs. @@ -493,5 +511,4 @@ rec { zipWithNames = zipAttrsWithNames; zip = builtins.trace "lib.zip is deprecated, use lib.zipAttrsWith instead" zipAttrsWith; - } diff --git a/lib/default.nix b/lib/default.nix index 803f1f76564..50320669e28 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -78,7 +78,7 @@ let zipAttrsWithNames zipAttrsWith zipAttrs recursiveUpdateUntil recursiveUpdate matchAttrs overrideExisting getOutput getBin getLib getDev getMan chooseDevOutputs zipWithNames zip - recurseIntoAttrs dontRecurseIntoAttrs; + recurseIntoAttrs dontRecurseIntoAttrs cartesianProductOfSets; inherit (self.lists) singleton forEach foldr fold foldl foldl' imap0 imap1 concatMap flatten remove findSingle findFirst any all count optional optionals toList range partition zipListsWith zipLists diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix index 35a5801c724..0d249968402 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -660,4 +660,71 @@ runTests { expected = [ [ "foo" ] [ "foo" "" "bar" ] [ "foo" "bar" ] ]; }; + testCartesianProductOfEmptySet = { + expr = cartesianProductOfSets {}; + expected = [ {} ]; + }; + + testCartesianProductOfOneSet = { + expr = cartesianProductOfSets { a = [ 1 2 3 ]; }; + expected = [ { a = 1; } { a = 2; } { a = 3; } ]; + }; + + testCartesianProductOfTwoSets = { + expr = cartesianProductOfSets { a = [ 1 ]; b = [ 10 20 ]; }; + expected = [ + { a = 1; b = 10; } + { a = 1; b = 20; } + ]; + }; + + testCartesianProductOfTwoSetsWithOneEmpty = { + expr = cartesianProductOfSets { a = [ ]; b = [ 10 20 ]; }; + expected = [ ]; + }; + + testCartesianProductOfThreeSets = { + expr = cartesianProductOfSets { + a = [ 1 2 3 ]; + b = [ 10 20 30 ]; + c = [ 100 200 300 ]; + }; + expected = [ + { a = 1; b = 10; c = 100; } + { a = 1; b = 10; c = 200; } + { a = 1; b = 10; c = 300; } + + { a = 1; b = 20; c = 100; } + { a = 1; b = 20; c = 200; } + { a = 1; b = 20; c = 300; } + + { a = 1; b = 30; c = 100; } + { a = 1; b = 30; c = 200; } + { a = 1; b = 30; c = 300; } + + { a = 2; b = 10; c = 100; } + { a = 2; b = 10; c = 200; } + { a = 2; b = 10; c = 300; } + + { a = 2; b = 20; c = 100; } + { a = 2; b = 20; c = 200; } + { a = 2; b = 20; c = 300; } + + { a = 2; b = 30; c = 100; } + { a = 2; b = 30; c = 200; } + { a = 2; b = 30; c = 300; } + + { a = 3; b = 10; c = 100; } + { a = 3; b = 10; c = 200; } + { a = 3; b = 10; c = 300; } + + { a = 3; b = 20; c = 100; } + { a = 3; b = 20; c = 200; } + { a = 3; b = 20; c = 300; } + + { a = 3; b = 30; c = 100; } + { a = 3; b = 30; c = 200; } + { a = 3; b = 30; c = 300; } + ]; + }; } -- cgit 1.4.1 From 7d551ead60f90b8c879bea7ce421f54482406dbb Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 4 Mar 2021 17:54:35 +0100 Subject: doc: Format --- doc/builders/packages/citrix.xml | 2 + doc/contributing/coding-conventions.xml | 12 +- doc/functions/library/attrsets.xml | 6 +- doc/stdenv/multiple-output.xml | 1 - doc/stdenv/stdenv.xml | 12 +- doc/using/configuration.xml | 2 +- doc/using/overlays.xml | 256 +++++++++++++------------------- 7 files changed, 114 insertions(+), 177 deletions(-) (limited to 'doc/functions') diff --git a/doc/builders/packages/citrix.xml b/doc/builders/packages/citrix.xml index 803eb2e4fc4..7a16b79f232 100644 --- a/doc/builders/packages/citrix.xml +++ b/doc/builders/packages/citrix.xml @@ -17,9 +17,11 @@
Citrix Selfservice + The selfservice is an application managing Citrix desktops and applications. Please note that this feature only works with at least citrix_workspace_20_06_0 and later versions. + In order to set this up, you first have to download the .cr file from the Netscaler Gateway. After that you can configure the selfservice like this: diff --git a/doc/contributing/coding-conventions.xml b/doc/contributing/coding-conventions.xml index 9005a9ebafd..9f00942918c 100644 --- a/doc/contributing/coding-conventions.xml +++ b/doc/contributing/coding-conventions.xml @@ -180,17 +180,12 @@ args.stdenv.mkDerivation (args // { - Arguments should be listed in the order they are used, with the - exception of lib, which always goes first. + Arguments should be listed in the order they are used, with the exception of lib, which always goes first. - Prefer using the top-level lib over its alias - stdenv.lib. lib is unrelated to - stdenv, and so stdenv.lib should only - be used as a convenience alias when developing to avoid having to modify - the function inputs just to test something out. + Prefer using the top-level lib over its alias stdenv.lib. lib is unrelated to stdenv, and so stdenv.lib should only be used as a convenience alias when developing to avoid having to modify the function inputs just to test something out. @@ -689,8 +684,7 @@ args.stdenv.mkDerivation (args // { - If it’s a theme for a desktop environment, - a window manager or a display manager: + If it’s a theme for a desktop environment, a window manager or a display manager: diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 7ef0d16624c..9a4e640935f 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -1677,8 +1677,7 @@ recursiveUpdate - Make various Nix tools consider the contents of the resulting - attribute set when looking for what to build, find, etc. + Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc. @@ -1720,7 +1719,7 @@ recursiveUpdate - Return the cartesian product of attribute set value combinations. + Return the cartesian product of attribute set value combinations. @@ -1749,5 +1748,4 @@ cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; } ]]>
- diff --git a/doc/stdenv/multiple-output.xml b/doc/stdenv/multiple-output.xml index f710a9959ad..5f2d2b8cfb9 100644 --- a/doc/stdenv/multiple-output.xml +++ b/doc/stdenv/multiple-output.xml @@ -26,7 +26,6 @@ A number of attributes can be used to work with a derivation with multiple outputs. The attribute outputs is a list of strings, which are the names of the outputs. For each of these names, an identically named attribute is created, corresponding to that output. The attribute meta.outputsToInstall is used to determine the default set of outputs to install when using the derivation name unqualified. -
Installing a split package diff --git a/doc/stdenv/stdenv.xml b/doc/stdenv/stdenv.xml index 21485425f26..b2004270e9b 100644 --- a/doc/stdenv/stdenv.xml +++ b/doc/stdenv/stdenv.xml @@ -1136,9 +1136,9 @@ preBuild = '' Variables controlling the install phase - + - dontInstall + dontInstall @@ -1839,10 +1839,7 @@ addEnvHooks "$hostOffset" myBashFunction - This setup hook moves any systemd user units installed in the lib - subdirectory into share. In addition, a link is provided from share to - lib for compatibility. This is needed for systemd to find user services - when installed into the user profile. + This setup hook moves any systemd user units installed in the lib subdirectory into share. In addition, a link is provided from share to lib for compatibility. This is needed for systemd to find user services when installed into the user profile. @@ -2022,8 +2019,7 @@ addEnvHooks "$hostOffset" myBashFunction This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given buildInputs and nativeBuildInputs. - You can also specify a runtimeDependencies variable which lists dependencies to be unconditionally added to rpath of all executables. - This is useful for programs that use + You can also specify a runtimeDependencies variable which lists dependencies to be unconditionally added to rpath of all executables. This is useful for programs that use dlopen 3 to load libraries at runtime. diff --git a/doc/using/configuration.xml b/doc/using/configuration.xml index 8e63e0072c8..3ef39733458 100644 --- a/doc/using/configuration.xml +++ b/doc/using/configuration.xml @@ -170,7 +170,7 @@ - Note that allowlistedLicenses only applies to unfree licenses unless allowUnfree is enabled. It is not a generic allowlist for all types of licenses. blocklistedLicenses applies to all licenses. + Note that allowlistedLicenses only applies to unfree licenses unless allowUnfree is enabled. It is not a generic allowlist for all types of licenses. blocklistedLicenses applies to all licenses. diff --git a/doc/using/overlays.xml b/doc/using/overlays.xml index 8bda235d43d..1def8b06955 100644 --- a/doc/using/overlays.xml +++ b/doc/using/overlays.xml @@ -28,8 +28,7 @@ - NOTE: DO NOT USE THIS in nixpkgs. - Further overlays can be added by calling the pkgs.extend or pkgs.appendOverlays, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do. + NOTE: DO NOT USE THIS in nixpkgs. Further overlays can be added by calling the pkgs.extend or pkgs.appendOverlays, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do.
@@ -139,98 +138,72 @@ self: super:
- Using overlays to configure alternatives + Using overlays to configure alternatives + + + Certain software packages have different implementations of the same interface. Other distributions have functionality to switch between these. For example, Debian provides DebianAlternatives. Nixpkgs has what we call alternatives, which are configured through overlays. + + +
+ BLAS/LAPACK + - Certain software packages have different implementations of the - same interface. Other distributions have functionality to switch - between these. For example, Debian provides DebianAlternatives. - Nixpkgs has what we call alternatives, which - are configured through overlays. + In Nixpkgs, we have multiple implementations of the BLAS/LAPACK numerical linear algebra interfaces. They are: -
- BLAS/LAPACK + + + - In Nixpkgs, we have multiple implementations of the BLAS/LAPACK - numerical linear algebra interfaces. They are: + OpenBLAS - - - - OpenBLAS - - - The Nixpkgs attribute is openblas for - ILP64 (integer width = 64 bits) and - openblasCompat for LP64 (integer width = - 32 bits). openblasCompat is the default. - - - - - LAPACK - reference (also provides BLAS) - - - The Nixpkgs attribute is lapack-reference. - - - - - Intel - MKL (only works on the x86_64 architecture, unfree) - - - The Nixpkgs attribute is mkl. - - - - - + The Nixpkgs attribute is openblas for ILP64 (integer width = 64 bits) and openblasCompat for LP64 (integer width = 32 bits). openblasCompat is the default. + + + + + LAPACK reference (also provides BLAS) + + + The Nixpkgs attribute is lapack-reference. + + + + + Intel MKL (only works on the x86_64 architecture, unfree) + + + The Nixpkgs attribute is mkl. + + + + + BLIS - - - BLIS, available through the attribute - blis, is a framework for linear algebra kernels. In - addition, it implements the BLAS interface. - - - - - AMD - BLIS/LIBFLAME (optimized for modern AMD x86_64 CPUs) - - - The AMD fork of the BLIS library, with attribute - amd-blis, extends BLIS with optimizations for - modern AMD CPUs. The changes are usually submitted to - the upstream BLIS project after some time. However, AMD BLIS - typically provides some performance improvements on AMD Zen CPUs. - The complementary AMD LIBFLAME library, with attribute - amd-libflame, provides a LAPACK implementation. - - - + - Introduced in PR - #83888, we are able to override the blas - and lapack packages to use different implementations, - through the blasProvider and - lapackProvider argument. This can be used - to select a different provider. BLAS providers will have - symlinks in $out/lib/libblas.so.3 and - $out/lib/libcblas.so.3 to their respective - BLAS libraries. Likewise, LAPACK providers will have symlinks - in $out/lib/liblapack.so.3 and - $out/lib/liblapacke.so.3 to their respective - LAPACK libraries. For example, Intel MKL is both a BLAS and - LAPACK provider. An overlay can be created to use Intel MKL - that looks like: + BLIS, available through the attribute blis, is a framework for linear algebra kernels. In addition, it implements the BLAS interface. - + + + + AMD BLIS/LIBFLAME (optimized for modern AMD x86_64 CPUs) + + + The AMD fork of the BLIS library, with attribute amd-blis, extends BLIS with optimizations for modern AMD CPUs. The changes are usually submitted to the upstream BLIS project after some time. However, AMD BLIS typically provides some performance improvements on AMD Zen CPUs. The complementary AMD LIBFLAME library, with attribute amd-libflame, provides a LAPACK implementation. + + + + + + Introduced in PR #83888, we are able to override the blas and lapack packages to use different implementations, through the blasProvider and lapackProvider argument. This can be used to select a different provider. BLAS providers will have symlinks in $out/lib/libblas.so.3 and $out/lib/libcblas.so.3 to their respective BLAS libraries. Likewise, LAPACK providers will have symlinks in $out/lib/liblapack.so.3 and $out/lib/liblapacke.so.3 to their respective LAPACK libraries. For example, Intel MKL is both a BLAS and LAPACK provider. An overlay can be created to use Intel MKL that looks like: + + + self: super: { @@ -243,46 +216,24 @@ self: super: }; } - - This overlay uses Intel’s MKL library for both BLAS and LAPACK - interfaces. Note that the same can be accomplished at runtime - using LD_LIBRARY_PATH of - libblas.so.3 and - liblapack.so.3. For instance: - + + + This overlay uses Intel’s MKL library for both BLAS and LAPACK interfaces. Note that the same can be accomplished at runtime using LD_LIBRARY_PATH of libblas.so.3 and liblapack.so.3. For instance: + + $ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave - - Intel MKL requires an openmp implementation - when running with multiple processors. By default, - mkl will use Intel’s iomp - implementation if no other is specified, but this is a - runtime-only dependency and binary compatible with the LLVM - implementation. To use that one instead, Intel recommends users - set it with LD_PRELOAD. Note that - mkl is only available on - x86_64-linux and - x86_64-darwin. Moreover, Hydra is not - building and distributing pre-compiled binaries using it. - - - For BLAS/LAPACK switching to work correctly, all packages must - depend on blas or lapack. - This ensures that only one BLAS/LAPACK library is used at one - time. There are two versions versions of BLAS/LAPACK currently - in the wild, LP64 (integer size = 32 bits) - and ILP64 (integer size = 64 bits). Some - software needs special flags or patches to work with - ILP64. You can check if - ILP64 is used in Nixpkgs with - blas.isILP64 and - lapack.isILP64. Some software does NOT work - with ILP64, and derivations need to specify - an assertion to prevent this. You can prevent - ILP64 from being used with the following: - - + + + Intel MKL requires an openmp implementation when running with multiple processors. By default, mkl will use Intel’s iomp implementation if no other is specified, but this is a runtime-only dependency and binary compatible with the LLVM implementation. To use that one instead, Intel recommends users set it with LD_PRELOAD. Note that mkl is only available on x86_64-linux and x86_64-darwin. Moreover, Hydra is not building and distributing pre-compiled binaries using it. + + + + For BLAS/LAPACK switching to work correctly, all packages must depend on blas or lapack. This ensures that only one BLAS/LAPACK library is used at one time. There are two versions versions of BLAS/LAPACK currently in the wild, LP64 (integer size = 32 bits) and ILP64 (integer size = 64 bits). Some software needs special flags or patches to work with ILP64. You can check if ILP64 is used in Nixpkgs with blas.isILP64 and lapack.isILP64. Some software does NOT work with ILP64, and derivations need to specify an assertion to prevent this. You can prevent ILP64 from being used with the following: + + + { stdenv, blas, lapack, ... }: assert (!blas.isILP64) && (!lapack.isILP64); @@ -291,41 +242,38 @@ stdenv.mkDerivation { ... } -
-
- Switching the MPI implementation - - All programs that are built with - MPI - support use the generic attribute mpi - as an input. At the moment Nixpkgs natively provides two different - MPI implementations: - - - - Open MPI - (default), attribute name openmpi - - - - - MPICH, - attribute name mpich - - - - - - To provide MPI enabled applications that use MPICH, instead - of the default Open MPI, simply use the following overlay: - - +
+ +
+ Switching the MPI implementation + + + All programs that are built with MPI support use the generic attribute mpi as an input. At the moment Nixpkgs natively provides two different MPI implementations: + + + + Open MPI (default), attribute name openmpi + + + + + MPICH, attribute name mpich + + + + + + + To provide MPI enabled applications that use MPICH, instead of the default Open MPI, simply use the following overlay: + + + self: super: { mpi = self.mpich; } -
+
-- cgit 1.4.1 From 22cb630a6642985237130ab5d232ee1ec66d52d4 Mon Sep 17 00:00:00 2001 From: Florian Engel Date: Sun, 14 Mar 2021 10:27:26 +0100 Subject: Fix type description for attrByPath The output type was missing --- doc/functions/library/attrsets.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/functions') diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 9a4e640935f..de8414249ab 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -7,7 +7,7 @@
<function>lib.attrset.attrByPath</function> - attrByPath :: [String] -> Any -> AttrSet + attrByPath :: [String] -> Any -> AttrSet -> Any -- cgit 1.4.1 From 3452a739d14dcee962479852760dddd661ba01a0 Mon Sep 17 00:00:00 2001 From: Erlend Pedersen Date: Sat, 8 May 2021 13:55:11 +0200 Subject: nixpkgs-manual: lib.attrsets.mapAttrsToList returns a list (#122179) --- doc/functions/library/attrsets.xml | 2 +- lib/attrsets.nix | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) (limited to 'doc/functions') diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index de8414249ab..912d6d47798 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -855,7 +855,7 @@ lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) <function>lib.attrsets.mapAttrsToList</function> mapAttrsToList :: (String -> Any -> Any) -> - AttrSet -> Any + AttrSet -> [Any] diff --git a/lib/attrsets.nix b/lib/attrsets.nix index 0ce3aaeca45..5c787940cb0 100644 --- a/lib/attrsets.nix +++ b/lib/attrsets.nix @@ -243,6 +243,10 @@ rec { /* Call a function for each attribute in the given set and return the result in a list. + Type: + mapAttrsToList :: + (String -> a -> b) -> AttrSet -> [b] + Example: mapAttrsToList (name: value: name + value) { x = "a"; y = "b"; } -- cgit 1.4.1 From 4a025692d1daf90b3a9cefe2d996e163e1ad05d3 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Sat, 6 Mar 2021 12:26:54 +0100 Subject: lib.sources: Generate docs --- doc/doc-support/lib-function-docs.nix | 1 + doc/functions/library.xml | 2 ++ 2 files changed, 3 insertions(+) (limited to 'doc/functions') diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix index 5199b949e7b..f6d613cac0b 100644 --- a/doc/doc-support/lib-function-docs.nix +++ b/doc/doc-support/lib-function-docs.nix @@ -22,5 +22,6 @@ with pkgs; stdenv.mkDerivation { docgen lists 'List manipulation functions' docgen debug 'Debugging functions' docgen options 'NixOS / nixpkgs option handling' + docgen sources 'Source filtering functions' ''; } diff --git a/doc/functions/library.xml b/doc/functions/library.xml index 6ffb944b5a6..21bcf5b88c9 100644 --- a/doc/functions/library.xml +++ b/doc/functions/library.xml @@ -25,4 +25,6 @@ + +
-- cgit 1.4.1 From 26ac257e4fecc050f28da30399afdfee83d98836 Mon Sep 17 00:00:00 2001 From: Antoine Martin Date: Fri, 4 Jun 2021 18:22:19 +0200 Subject: doc: nix-gitignore to CommonMark Closes #125670 --- doc/functions.xml | 2 +- doc/functions/nix-gitignore.section.md | 49 ++++++++++++++++++++++++ doc/functions/nix-gitignore.xml | 70 ---------------------------------- 3 files changed, 50 insertions(+), 71 deletions(-) create mode 100644 doc/functions/nix-gitignore.section.md delete mode 100644 doc/functions/nix-gitignore.xml (limited to 'doc/functions') diff --git a/doc/functions.xml b/doc/functions.xml index 5a9240ec800..e8ab8d97b91 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -10,5 +10,5 @@ - + diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md new file mode 100644 index 00000000000..2fb833b2300 --- /dev/null +++ b/doc/functions/nix-gitignore.section.md @@ -0,0 +1,49 @@ +# pkgs.nix-gitignore {#sec-pkgs-nix-gitignore} + +`pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format. + +## Usage {#sec-pkgs-nix-gitignore-usage} + +`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string. + +```nix +{ pkgs ? import {} }: + + nix-gitignore.gitignoreSource [] ./source + # Simplest version + + nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source + # This one reads the ./source/.gitignore and concats the auxiliary ignores + + nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source + # Use this string as gitignore, don't read ./source/.gitignore. + + nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source + # It also accepts a list (of strings and paths) that will be concatenated + # once the paths are turned to strings via readFile. +``` + +These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`: + +```nix +gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true); +gitignoreSource = gitignoreFilterSource (_: _: true); +``` + +Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter. + +If you want to make your own filter from scratch, you may use + +```nix +gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; +``` + +## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive} + +If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: + +```nix +gitignoreFilterRecursiveSource = filter: patterns: root: +# OR +gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); +``` diff --git a/doc/functions/nix-gitignore.xml b/doc/functions/nix-gitignore.xml deleted file mode 100644 index 37a82b196cc..00000000000 --- a/doc/functions/nix-gitignore.xml +++ /dev/null @@ -1,70 +0,0 @@ -
- pkgs.nix-gitignore - - - pkgs.nix-gitignore is a function that acts similarly to builtins.filterSource but also allows filtering with the help of the gitignore format. - - -
- Usage - - - pkgs.nix-gitignore exports a number of functions, but you'll most likely need either gitignoreSource or gitignoreSourcePure. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string. - - - {} }: - - nix-gitignore.gitignoreSource [] ./source - # Simplest version - - nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source - # This one reads the ./source/.gitignore and concats the auxiliary ignores - - nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source - # Use this string as gitignore, don't read ./source/.gitignore. - - nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source - # It also accepts a list (of strings and paths) that will be concatenated - # once the paths are turned to strings via readFile. - ]]> - - - These functions are derived from the Filter functions by setting the first filter argument to (_: _: true): - - - - - - Those filter functions accept the same arguments the builtins.filterSource function would pass to its filters, thus fn: gitignoreFilterSourcePure fn "" should be extensionally equivalent to filterSource. The file is blacklisted iff it's blacklisted by either your filter or the gitignoreFilter. - - - - If you want to make your own filter from scratch, you may use - - - -
- -
- gitignore files in subdirectories - - - If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: - - - -
-
-- cgit 1.4.1 From 3c78ad2561a831dcbe6e193465f787019638d56b Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Sun, 6 Jun 2021 13:17:54 +0200 Subject: doc: Use markdown syntax for xrefs Syntax is taken from MyST: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing --- doc/Makefile | 1 + doc/contributing/coding-conventions.chapter.md | 4 ++-- .../contributing-to-documentation.chapter.md | 5 +++++ doc/contributing/quick-start.chapter.md | 2 +- doc/functions/library/attrsets.xml | 4 ++-- doc/labelless-link-is-xref.lua | 24 ++++++++++++++++++++++ doc/stdenv/cross-compilation.chapter.md | 4 ++-- doc/stdenv/multiple-output.chapter.md | 6 +++--- doc/stdenv/stdenv.chapter.md | 14 ++++++------- doc/using/overlays.chapter.md | 2 +- 10 files changed, 48 insertions(+), 18 deletions(-) create mode 100644 doc/labelless-link-is-xref.lua (limited to 'doc/functions') diff --git a/doc/Makefile b/doc/Makefile index a208ce02f0c..85d09f3ddc0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,7 @@ pandoc_media_dir = media pandoc_commonmark_enabled_extensions = +attributes+fenced_divs+footnotes+bracketed_spans+definition_lists+pipe_tables+raw_attribute pandoc_flags = --extract-media=$(pandoc_media_dir) \ --lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \ + --lua-filter=labelless-link-is-xref.lua \ -f commonmark$(pandoc_commonmark_enabled_extensions)+smart .PHONY: all diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index 4fa88895484..e42ba512b98 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -6,7 +6,7 @@ - Do not use tab characters, i.e. configure your editor to use soft tabs. For instance, use `(setq-default indent-tabs-mode nil)` in Emacs. Everybody has different tab settings so it’s asking for trouble. -- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in . +- Use `lowerCamelCase` for variable names, not `UpperCamelCase`. Note, this rule does not apply to package attribute names, which instead follow the rules in [](#sec-package-naming). - Function calls with attribute set arguments are written as @@ -209,7 +209,7 @@ There are a few naming guidelines: - Dashes in the package name _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names. -- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also +- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also [](#sec-versioning) ## File naming and organisation {#sec-organisation} diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 44feac7fbf7..2f7ae32259c 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -47,6 +47,11 @@ Additionally, the following syntax extensions are currently used: - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`. ``` +- []{#ssec-contributing-markup-automatic-links} + If you **omit a link text** for a link pointing to a section, the text will be substituted automatically. For example, `[](#chap-contributing)` will result in [](#chap-contributing). + + This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). + - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. diff --git a/doc/contributing/quick-start.chapter.md b/doc/contributing/quick-start.chapter.md index 85c3897221e..96b30d3822c 100644 --- a/doc/contributing/quick-start.chapter.md +++ b/doc/contributing/quick-start.chapter.md @@ -9,7 +9,7 @@ To add a package to Nixpkgs: $ cd nixpkgs ``` -2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See for some hints on the tree organisation. Create a directory for your package, e.g. +2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See [](#sec-organisation) for some hints on the tree organisation. Create a directory for your package, e.g. ```ShellSession $ mkdir pkgs/development/libraries/libfoo diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 912d6d47798..ef132514da1 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -166,7 +166,7 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3 - Like except without a default, and it will throw if the value doesn't exist. + Like [](#function-library-lib.attrsets.attrByPath) except without a default, and it will throw if the value doesn't exist. @@ -1480,7 +1480,7 @@ lib.attrsets.zipAttrsWith - Merge sets of attributes and combine each attribute value in to a list. Similar to where the merge function returns a list of all values. + Merge sets of attributes and combine each attribute value in to a list. Similar to [](#function-library-lib.attrsets.zipAttrsWith) where the merge function returns a list of all values. diff --git a/doc/labelless-link-is-xref.lua b/doc/labelless-link-is-xref.lua new file mode 100644 index 00000000000..67569b02091 --- /dev/null +++ b/doc/labelless-link-is-xref.lua @@ -0,0 +1,24 @@ +local function starts_with(start, str) + return str:sub(1, #start) == start +end + +local function escape_xml_arg(arg) + amps = arg:gsub('&', '&') + amps_quotes = amps:gsub('"', '"') + amps_quotes_lt = amps_quotes:gsub('<', '<') + + return amps_quotes_lt +end + +function Link(elem) + has_no_content = #elem.content == 0 + targets_anchor = starts_with('#', elem.target) + has_no_attributes = elem.title == '' and elem.identifier == '' and #elem.classes == 0 and #elem.attributes == 0 + + if has_no_content and targets_anchor and has_no_attributes then + -- xref expects idref without the pound-sign + target_without_hash = elem.target:sub(2, #elem.target) + + return pandoc.RawInline('docbook', '') + end +end diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index b27e9cc6fea..53522962a5c 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -65,7 +65,7 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv ### Theory of dependency categorization {#ssec-cross-dependency-categorization} ::: {.note} -This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to `mkDerivation`, see . For a description of how everything is implemented, see . +This is a rather philosophical description that isn't very Nixpkgs-specific. For an overview of all the relevant attributes given to `mkDerivation`, see [](#ssec-stdenv-dependencies). For a description of how everything is implemented, see [](#ssec-cross-dependency-implementation). ::: In this section we explore the relationship between both runtime and build-time dependencies and the 3 Autoconf platforms. @@ -158,7 +158,7 @@ One would think that `localSystem` and `crossSystem` overlap horribly with the t ### Implementation of dependencies {#ssec-cross-dependency-implementation} -The categories of dependencies developed in are specified as lists of derivations given to `mkDerivation`, as documented in . In short, each list of dependencies for "host → target" of "foo → bar" is called `depsFooBar`, with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `depsFooBar` is automatically taken from `pkgsFooBar`. (These `pkgsFooBar`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. +The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for "host → target" of "foo → bar" is called `depsFooBar`, with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `depsFooBar` is automatically taken from `pkgsFooBar`. (These `pkgsFooBar`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. Now, for most of Nixpkgs's history, there were no `pkgsFooBar` attributes, and most packages have not been refactored to use it explicitly. Prior to those, there were just `buildPackages`, `pkgs`, and `targetPackages`. Those are now redefined as aliases to `pkgsBuildHost`, `pkgsHostTarget`, and `pkgsTargetTarget`. It is acceptable, even recommended, to use them for libraries to show that the host platform is irrelevant. diff --git a/doc/stdenv/multiple-output.chapter.md b/doc/stdenv/multiple-output.chapter.md index b8414614279..d04f83302ac 100644 --- a/doc/stdenv/multiple-output.chapter.md +++ b/doc/stdenv/multiple-output.chapter.md @@ -38,7 +38,7 @@ $ nix-env -iA nixpkgs.coreutils.info installs the `"out"` output (`coreutils.meta.outputsToInstall` is `[ "out" ]`) instead of the requested `"info"`. ::: -The only recourse to select an output with `nix-env` is to override the package’s `meta.outputsToInstall`, using the functions described in . For example, the following overlay adds the `"info"` output for the `coreutils` package: +The only recourse to select an output with `nix-env` is to override the package’s `meta.outputsToInstall`, using the functions described in [](#chap-overrides). For example, the following overlay adds the `"info"` output for the `coreutils` package: ```nix self: super: @@ -53,7 +53,7 @@ self: super: In the Nix language the individual outputs can be reached explicitly as attributes, e.g. `coreutils.info`, but the typical case is just using packages as build inputs. -When a multiple-output derivation gets into a build input of another derivation, the `dev` output is added if it exists, otherwise the first output is added. In addition to that, `propagatedBuildOutputs` of that package which by default contain `$outputBin` and `$outputLib` are also added. (See .) +When a multiple-output derivation gets into a build input of another derivation, the `dev` output is added if it exists, otherwise the first output is added. In addition to that, `propagatedBuildOutputs` of that package which by default contain `$outputBin` and `$outputLib` are also added. (See [](#multiple-output-file-type-groups).) In some cases it may be desirable to combine different outputs under a single store path. A function `symlinkJoin` can be used to do this. (Note that it may negate some closure size benefits of using a multiple-output package.) @@ -70,7 +70,7 @@ outputs = [ "bin" "dev" "out" "doc" ]; Often such a single line is enough. For each output an equally named environment variable is passed to the builder and contains the path in nix store for that output. Typically you also want to have the main `out` output, as it catches any files that didn’t get elsewhere. ::: {.note} -There is a special handling of the `debug` output, described at . +There is a special handling of the `debug` output, described at [](#stdenv-separateDebugInfo). ::: ### “Binaries first” {#multiple-output-file-binaries-first-convention} diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 71eb991bbae..4daeaf7c8c2 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -39,9 +39,9 @@ stdenv.mkDerivation { } ``` -This attribute ensures that the `bin` subdirectories of these packages appear in the `PATH` environment variable during the build, that their `include` subdirectories are searched by the C compiler, and so on. (See for details.) +This attribute ensures that the `bin` subdirectories of these packages appear in the `PATH` environment variable during the build, that their `include` subdirectories are searched by the C compiler, and so on. (See [](#ssec-setup-hooks) for details.) -Often it is necessary to override or modify some aspect of the build. To make this easier, the standard environment breaks the package build into a number of *phases*, all of which can be overridden or modified individually: unpacking the sources, applying patches, configuring, building, and installing. (There are some others; see .) For instance, a package that doesn’t supply a makefile but instead has to be compiled "manually" could be handled like this: +Often it is necessary to override or modify some aspect of the build. To make this easier, the standard environment breaks the package build into a number of *phases*, all of which can be overridden or modified individually: unpacking the sources, applying patches, configuring, building, and installing. (There are some others; see [](#sec-stdenv-phases).) For instance, a package that doesn’t supply a makefile but instead has to be compiled "manually" could be handled like this: ```nix stdenv.mkDerivation { @@ -59,7 +59,7 @@ stdenv.mkDerivation { (Note the use of `''`-style string literals, which are very convenient for large multi-line script fragments because they don’t need escaping of `"` and `\`, and because indentation is intelligently removed.) -There are many other attributes to customise the build. These are listed in . +There are many other attributes to customise the build. These are listed in [](#ssec-stdenv-attributes). While the standard environment provides a generic builder, you can still supply your own build script: @@ -116,9 +116,9 @@ On Linux, `stdenv` also includes the `patchelf` utility. ## Specifying dependencies {#ssec-stdenv-dependencies} -As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to, between them, include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See for details. +As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to, between them, include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See [](#ssec-setup-hooks) for details. -Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation’s, and whether they are propagated. The platform distinctions are motivated by cross compilation; see for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case. +Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation’s, and whether they are propagated. The platform distinctions are motivated by cross compilation; see [](#chap-cross) for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case. The extension of `PATH` with dependencies, alluded to above, proceeds according to the relative platforms alone. The process is carried out only for dependencies whose host platform matches the new derivation’s build platform i.e. dependencies which run on the platform where the new derivation will be built. [^footnote-stdenv-native-dependencies-in-path] For each dependency \ of those dependencies, `dep/bin`, if present, is added to the `PATH` environment variable. @@ -911,7 +911,7 @@ This verifies that no references are left from the install binaries to the direc ### `multiple-outputs.sh` {#multiple-outputs.sh} -This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See for more information. +This setup hook adds configure flags that tell packages to install files into any one of the proper outputs listed in `outputs`. This behavior can be turned off by setting `setOutputFlags` to false in the derivation environment. See [](#chap-multiple-output) for more information. ### `move-sbin.sh` {#move-sbin.sh} @@ -991,7 +991,7 @@ Creates a temporary package database and registers every Haskell build input in ### GNOME platform {#gnome-platform} -Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in . +Hooks related to GNOME platform and related libraries like GLib, GTK and GStreamer are described in [](#sec-language-gnome). ### autoPatchelfHook {#setup-hook-autopatchelfhook} diff --git a/doc/using/overlays.chapter.md b/doc/using/overlays.chapter.md index 537d031bcdb..037580583b6 100644 --- a/doc/using/overlays.chapter.md +++ b/doc/using/overlays.chapter.md @@ -63,7 +63,7 @@ The second argument (`super`) corresponds to the result of the evaluation of the The value returned by this function should be a set similar to `pkgs/top-level/all-packages.nix`, containing overridden and/or new packages. -Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in. Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute. +Overlays are similar to other methods for customizing Nixpkgs, in particular the `packageOverrides` attribute described in [](#sec-modify-via-packageOverrides). Indeed, `packageOverrides` acts as an overlay with only the `super` argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute. ## Using overlays to configure alternatives {#sec-overlays-alternatives} -- cgit 1.4.1 From fbfdc8fc0b9ad81115e86cc48f97dc666d57b444 Mon Sep 17 00:00:00 2001 From: Ryan Mulligan Date: Sun, 6 Jun 2021 07:45:53 -0700 Subject: doc/functions/debug: convert to CommonMark --- doc/functions.xml | 2 +- doc/functions/debug.section.md | 5 +++++ doc/functions/debug.xml | 14 -------------- 3 files changed, 6 insertions(+), 15 deletions(-) create mode 100644 doc/functions/debug.section.md delete mode 100644 doc/functions/debug.xml (limited to 'doc/functions') diff --git a/doc/functions.xml b/doc/functions.xml index e8ab8d97b91..f2d06402317 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -8,7 +8,7 @@ - + diff --git a/doc/functions/debug.section.md b/doc/functions/debug.section.md new file mode 100644 index 00000000000..b2d8589431a --- /dev/null +++ b/doc/functions/debug.section.md @@ -0,0 +1,5 @@ +# Debugging Nix Expressions {#sec-debug} + +Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions. + +In the `lib/debug.nix` file you will find a number of functions that help (pretty-)printing values while evaluation is running. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in `lib/debug.nix` for usage information. diff --git a/doc/functions/debug.xml b/doc/functions/debug.xml deleted file mode 100644 index c27421f12e7..00000000000 --- a/doc/functions/debug.xml +++ /dev/null @@ -1,14 +0,0 @@ -
- Debugging Nix Expressions - - - Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions. - - - - In the lib/debug.nix file you will find a number of functions that help (pretty-)printing values while evaluation is runnnig. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in lib/debug.nix for usage information. - -
-- cgit 1.4.1 From c682532fceff80170e427a4383ae6e474165dd2b Mon Sep 17 00:00:00 2001 From: Ryan Mulligan Date: Sun, 6 Jun 2021 13:19:33 -0700 Subject: doc/functions/prefer-remote-fetch: convert to CommonMark --- doc/functions.xml | 2 +- doc/functions/prefer-remote-fetch.section.md | 17 +++++++++++++++++ doc/functions/prefer-remote-fetch.xml | 21 --------------------- 3 files changed, 18 insertions(+), 22 deletions(-) create mode 100644 doc/functions/prefer-remote-fetch.section.md delete mode 100644 doc/functions/prefer-remote-fetch.xml (limited to 'doc/functions') diff --git a/doc/functions.xml b/doc/functions.xml index f2d06402317..dd91d705aa9 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -9,6 +9,6 @@ - + diff --git a/doc/functions/prefer-remote-fetch.section.md b/doc/functions/prefer-remote-fetch.section.md new file mode 100644 index 00000000000..8760c100224 --- /dev/null +++ b/doc/functions/prefer-remote-fetch.section.md @@ -0,0 +1,17 @@ +# prefer-remote-fetch overlay {#sec-prefer-remote-fetch} + +`prefer-remote-fetch` is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay: + +```nix +self: super: + (super.prefer-remote-fetch self super) +``` + +A full configuration example for that sets the overlay up for your own account, could look like this + +```ShellSession +$ mkdir ~/.config/nixpkgs/overlays/ +$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix < - prefer-remote-fetch overlay - - - prefer-remote-fetch is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay: - -self: super: - (super.prefer-remote-fetch self super) - - A full configuration example for that sets the overlay up for your own account, could look like this - -$ mkdir ~/.config/nixpkgs/overlays/ -$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF - self: super: super.prefer-remote-fetch self super -EOF - - - -- cgit 1.4.1 From 606bf6dc17b6cdc5217a27d9bc703bc0f43f8c58 Mon Sep 17 00:00:00 2001 From: Ryan Mulligan Date: Sun, 6 Jun 2021 13:11:11 -0700 Subject: doc/functions/generators: convert to CommonMark --- doc/functions.xml | 2 +- doc/functions/generators.section.md | 56 ++++++++++++++++++++++++++++ doc/functions/generators.xml | 74 ------------------------------------- 3 files changed, 57 insertions(+), 75 deletions(-) create mode 100644 doc/functions/generators.section.md delete mode 100644 doc/functions/generators.xml (limited to 'doc/functions') diff --git a/doc/functions.xml b/doc/functions.xml index dd91d705aa9..8ef530d307c 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -7,7 +7,7 @@ The nixpkgs repository has several utility functions to manipulate Nix expressions. - + diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md new file mode 100644 index 00000000000..bb8426d8087 --- /dev/null +++ b/doc/functions/generators.section.md @@ -0,0 +1,56 @@ +# Generators {#sec-generators} +Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML` + +All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash. + +Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted: + +```nix +with lib; +let + customToINI = generators.toINI { + # specifies how to format a key/value pair + mkKeyValue = generators.mkKeyValueDefault { + # specifies the generated string for a subset of nix values + mkValueString = v: + if v == true then ''"yes"'' + else if v == false then ''"no"'' + else if isString v then ''"${v}"'' + # and delegats all other values to the default generator + else generators.mkValueStringDefault {} v; + } ":"; + }; + +# the INI file can now be given as plain old nix values +in customToINI { + main = { + pushinfo = true; + autopush = false; + host = "localhost"; + port = 42; + }; + mergetool = { + merge = "diff3"; + }; +} +``` + +This will produce the following INI file as nix string: + +```INI +[main] +autopush:"no" +host:"localhost" +port:42 +pushinfo:"yes" +str\:ange:"very::strange" + +[mergetool] +merge:"diff3" +``` + +::: note +Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`. +::: + +Detailed documentation for each generator can be found in `lib/generators.nix`. diff --git a/doc/functions/generators.xml b/doc/functions/generators.xml deleted file mode 100644 index 9ce1f85eb17..00000000000 --- a/doc/functions/generators.xml +++ /dev/null @@ -1,74 +0,0 @@ -
- Generators - - - Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: INI, JSON and YAML - - - - All generators follow a similar call interface: generatorName configFunctions data, where configFunctions is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is mkSectionName ? (name: libStr.escape [ "[" "]" ] name) from the INI generator. It receives the name of a section and sanitizes it. The default mkSectionName escapes [ and ] with a backslash. - - - - Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses : as separator, the strings "yes"/"no" as boolean values and requires all string values to be quoted: - - - -with lib; -let - customToINI = generators.toINI { - # specifies how to format a key/value pair - mkKeyValue = generators.mkKeyValueDefault { - # specifies the generated string for a subset of nix values - mkValueString = v: - if v == true then ''"yes"'' - else if v == false then ''"no"'' - else if isString v then ''"${v}"'' - # and delegats all other values to the default generator - else generators.mkValueStringDefault {} v; - } ":"; - }; - -# the INI file can now be given as plain old nix values -in customToINI { - main = { - pushinfo = true; - autopush = false; - host = "localhost"; - port = 42; - }; - mergetool = { - merge = "diff3"; - }; -} - - - - This will produce the following INI file as nix string: - - - -[main] -autopush:"no" -host:"localhost" -port:42 -pushinfo:"yes" -str\:ange:"very::strange" - -[mergetool] -merge:"diff3" - - - - - Nix store paths can be converted to strings by enclosing a derivation attribute like so: "${drv}". - - - - - Detailed documentation for each generator can be found in lib/generators.nix. - -
-- cgit 1.4.1 From ad5deab11a9c2304d5a8b3497b092bcbd2015d6c Mon Sep 17 00:00:00 2001 From: rnhmjoj Date: Tue, 22 Jun 2021 14:01:18 +0200 Subject: doc/functions/generators: fix code block Small fixup of 606bf6d. --- doc/functions/generators.section.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/functions') diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md index bb8426d8087..d54e5027c79 100644 --- a/doc/functions/generators.section.md +++ b/doc/functions/generators.section.md @@ -49,7 +49,7 @@ str\:ange:"very::strange" merge:"diff3" ``` -::: note +::: {.note} Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`. ::: -- cgit 1.4.1