initial commit

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>>

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
+....

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;
+}
+....

source/nixpkgs/main.adoc

@@ -0,0 +1,99 @@
+= Nixpkgs
+
+As discussed in <<#type-path>>, enclosing a path in angle brackets, e.g. <nixpkgs> 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 <nixpkgs>` will load `nixpkgs`.
+
+[source]
+.Example
+....
+nix-repl> :l <nixpkgs>
+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 '<nixpkgs>'`.
+
+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 <nixpkgs> is with (import <nixpkgs> {}); 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 <nixpkgs> { 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`