diff --git a/source/nix-language/derivations.adoc b/source/nix-language/derivations.adoc new file mode 100644 index 0000000..2572630 --- /dev/null +++ b/source/nix-language/derivations.adoc @@ -0,0 +1,20 @@ +[#derivations] += Derivations + +Derivations can be created using the primitive built-in `derivation` function. +It takes the following arguments. + +- `system` (e.g. `x86_64-linux`). +- `name`, the package name. +- `builder`, the executable that builds the package. + Attributes are passed to the builder as environment variables. +- `args` (optional), command line arguments to be passed to the builder. +- `outputs` (optional, defaults to `out`), output names. + Nix will pass them to the builder as environment variables containing + the output paths. + + d = derivation { name = "myname"; builder = "mybuilder"; system = "mysystem"; } + +In place of using `derivation`, it is generally more convenient to use +`stdenv.mkDerivation`, which will be be introduced in +<<#mkDerivation>> diff --git a/source/nix-language/import.adoc b/source/nix-language/import.adoc new file mode 100644 index 0000000..8d56770 --- /dev/null +++ b/source/nix-language/import.adoc @@ -0,0 +1,70 @@ += Import + +The built-in `import` function provides a way to parse a `.nix` file. + +[source,nix] +.a.nix +.... +{ + message = "You successfully imported me!"; + b = 12; +} +.... + +[source] +.Example +.... +nix-repl> a = import ./a.nix + +nix-repl> a.message +"You successfully imported me!" + +nix-repl> a.b +12 +.... + +The scope of the imported file does not inherit the scope of the importer. + +[source,nix] +.b.nix +.... +x + 7 +.... + +[source] +.Example +.... +nix-repl> x = 12 + +nix-repl> y = import ./b.nix + +nix-repl> y +error: + … while calling the 'import' builtin + at «string»:1:2: + 1| import ./b.nix + | ^ + + error: undefined variable 'x' + at /home/amy/codeberg/nix-book/b.nix:1:1: + 1| x + 7 + | ^ + 2| +.... + +So to pass information when importing something, use a function. + +[source,nix] +.c.nix +.... +x: x + 7 +.... + +[source] +.Example +.... +nix-repl> f = import ./c.nix + +nix-repl> f 12 +19 +.... diff --git a/source/nix-language/inherit.adoc b/source/nix-language/inherit.adoc new file mode 100644 index 0000000..ba67ba4 --- /dev/null +++ b/source/nix-language/inherit.adoc @@ -0,0 +1,30 @@ += Inherit + +The `inherit` keyword causes the specified attributes to be bound to +whatever variables with the same name happen to be in scope. + +When defining a set or in a let-expression it is often convenient to copy variables +from the surrounding lexical scope (e.g., when you want to propagate attributes). +This can be shortened using `inherit`. + +For instance, + +[source,nix] +.... +let x = 123; in +{ + inherit x; + y = 456; +} +.... + +is equivalent to + +[source,nix] +.... +let x = 123; in +{ + x = x; + y = 456; +} +.... diff --git a/source/nixpkgs/main.adoc b/source/nixpkgs/main.adoc new file mode 100644 index 0000000..6c7d1b2 --- /dev/null +++ b/source/nixpkgs/main.adoc @@ -0,0 +1,99 @@ += Nixpkgs + +As discussed in <<#type-path>>, enclosing a path in angle brackets, e.g. causes the directories +listed in the environment variable NIX_PATH to be searched for the given +file or directory name. +In the REPL, the command `:l ` will load `nixpkgs`. + +[source] +.Example +.... +nix-repl> :l +Added 25694 variables. +.... + +This gives you access to many more functions and tools. +Alternatively, you can automatically load nixpkgs when you enter the REPL +using the command `nix repl ''`. + +Within a Nix flake +//// +TODO: Add a cross-reference to where we discuss the `lib` functions. +TODO: discuss the `lib` functions +TODO: discuss the `import` directive +TODO: Mention that... In a file, the counterpart to :l is with (import {}); at the beginning of the file. +//// + +== Nixpkgs library function + +In this section, we will look at a few especially useful Nixpkgs library functions. +You can find a full list in the +https://nixos.org/manual/nixpkgs/unstable/#sec-functions-library[Nixpkgs manual]. + +[#genAttrs] +=== `lib.genAttrs` + +The function +https://nixos.org/manual/nixpkgs/stable/#function-library-lib.attrsets.genAttrs[`lib.genAttrs`] +generates an attribute set by mapping a function over a list of attribute names. +It is an alias for `lib.attrsets.genAttrs`. + +It takes two arguments: +- names of values in the resulting attribute set +- a function, given the name of the attribute, returns the attribute's value + +[source] +.Example +.... +nix-repl> lib.genAttrs [ "x86_64-linux" "aarch64-linux" ] (system: "some definitions for ${system}") +{ + aarch64-linux = "some definitions for aarch64-linux"; + x86_64-linux = "some definitions for x86_64-linux"; +} +.... + +As we shall see later, this is very useful when writing flakes. + +[#getExe] +=== `lib.getExe` and `lib.getExe'` + +The function +https://nixos.org/manual/nixpkgs/stable/#function-library-lib.meta.getExe[`lib.getExe`] +returns the path to the main program of a package. +It is an alias for `lib.meta.getExe`. + +[source] +.Example +.... +nix-repl> system = "x86_64-linux" + +nix-repl> pkgs = import { inherit system; } + +nix-repl> lib.getExe pkgs.hello +"/nix/store/s9p0adfpzarzfa5kcnqhwargfwiq8qmj-hello-2.12.2/bin/hello" +.... + +The function +https://nixos.org/manual/nixpkgs/stable/#function-library-lib.meta.getExe[`lib.getExe'`] +returns the path to the specified program of a package. +It is an alias for `lib.meta.getExe'`. + +[source] +.Example +.... +nix-repl> lib.getExe' pkgs.imagemagick "convert" +"/nix/store/rn6ck85zkpkgdnm00jmn762z22wz86w6-imagemagick-7.1.2-3/bin/convert" +.... + +[#mkShell] +=== `pkgs.mkShell` + +The function +https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell[`pkgs.mkShell`] +is a wrapper around `stenv.mkDerivation` + +[#flakeExposed] +=== `lib.systems.flakeExposed` + +[#mkDerivation] +=== `stdenv.mkDerivation`