bbjubjub2494/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

manual: remove "Writing Nix Expressions" chapter

Browse source 
it is out of date, all over the place in level of detail, is really
about `nixpkgs`, and in general instructions should not be part of
a reference manual.

also:
- update redirects and internal links
- use "Nix language" consistently
This commit is contained in:
Valentin Gagarin 2022-08-04 11:36:32 +02:00
parent 075bf6e556
commit 499ed26508
25 changed files with 124 additions and 543 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/manual/local.mk
View file

@ -61,10 +61,10 @@ $(d)/conf-file.json: $(bindir)/nix
$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp $(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
@mv $@.tmp $@ @mv $@.tmp $@
$(d)/src/expressions/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/expressions/builtins-prefix.md $(bindir)/nix $(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
@cat doc/manual/src/expressions/builtins-prefix.md > $@.tmp @cat doc/manual/src/language/builtins-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
@cat doc/manual/src/expressions/builtins-suffix.md >> $@.tmp @cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
@mv $@.tmp $@ @mv $@.tmp $@
$(d)/builtins.json: $(bindir)/nix $(d)/builtins.json: $(bindir)/nix
@ -97,7 +97,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
done done
@touch $@ @touch $@
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md $(call rwildcard, $(d)/src, *.md) $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(call rwildcard, $(d)/src, *.md)
$(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual $(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual
endif endif

207
doc/manual/redirects.js
View file

@ -132,113 +132,106 @@ var redirects = {
"#sec-common-options": "command-ref/opt-common.html", "#sec-common-options": "command-ref/opt-common.html",
"#ch-utilities": "command-ref/utilities.html", "#ch-utilities": "command-ref/utilities.html",
"#chap-hacking": "contributing/hacking.html", "#chap-hacking": "contributing/hacking.html",
"#adv-attr-allowSubstitutes": "expressions/advanced-attributes.html#adv-attr-allowSubstitutes", "#adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
"#adv-attr-allowedReferences": "expressions/advanced-attributes.html#adv-attr-allowedReferences", "#adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
"#adv-attr-allowedRequisites": "expressions/advanced-attributes.html#adv-attr-allowedRequisites", "#adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
"#adv-attr-disallowedReferences": "expressions/advanced-attributes.html#adv-attr-disallowedReferences", "#adv-attr-disallowedReferences": "language/advanced-attributes.html#adv-attr-disallowedReferences",
"#adv-attr-disallowedRequisites": "expressions/advanced-attributes.html#adv-attr-disallowedRequisites", "#adv-attr-disallowedRequisites": "language/advanced-attributes.html#adv-attr-disallowedRequisites",
"#adv-attr-exportReferencesGraph": "expressions/advanced-attributes.html#adv-attr-exportReferencesGraph", "#adv-attr-exportReferencesGraph": "language/advanced-attributes.html#adv-attr-exportReferencesGraph",
"#adv-attr-impureEnvVars": "expressions/advanced-attributes.html#adv-attr-impureEnvVars", "#adv-attr-impureEnvVars": "language/advanced-attributes.html#adv-attr-impureEnvVars",
"#adv-attr-outputHash": "expressions/advanced-attributes.html#adv-attr-outputHash", "#adv-attr-outputHash": "language/advanced-attributes.html#adv-attr-outputHash",
"#adv-attr-outputHashAlgo": "expressions/advanced-attributes.html#adv-attr-outputHashAlgo", "#adv-attr-outputHashAlgo": "language/advanced-attributes.html#adv-attr-outputHashAlgo",
"#adv-attr-outputHashMode": "expressions/advanced-attributes.html#adv-attr-outputHashMode", "#adv-attr-outputHashMode": "language/advanced-attributes.html#adv-attr-outputHashMode",
"#adv-attr-passAsFile": "expressions/advanced-attributes.html#adv-attr-passAsFile", "#adv-attr-passAsFile": "language/advanced-attributes.html#adv-attr-passAsFile",
"#adv-attr-preferLocalBuild": "expressions/advanced-attributes.html#adv-attr-preferLocalBuild", "#adv-attr-preferLocalBuild": "language/advanced-attributes.html#adv-attr-preferLocalBuild",
"#fixed-output-drvs": "expressions/advanced-attributes.html#adv-attr-outputHash", "#fixed-output-drvs": "language/advanced-attributes.html#adv-attr-outputHash",
"#sec-advanced-attributes": "expressions/advanced-attributes.html", "#sec-advanced-attributes": "language/advanced-attributes.html",
"#sec-arguments": "expressions/arguments-variables.html", "#builtin-abort": "language/builtins.html#builtins-abort",
"#sec-build-script": "expressions/build-script.html", "#builtin-add": "language/builtins.html#builtins-add",
"#builtin-abort": "expressions/builtins.html#builtins-abort", "#builtin-all": "language/builtins.html#builtins-all",
"#builtin-add": "expressions/builtins.html#builtins-add", "#builtin-any": "language/builtins.html#builtins-any",
"#builtin-all": "expressions/builtins.html#builtins-all", "#builtin-attrNames": "language/builtins.html#builtins-attrNames",
"#builtin-any": "expressions/builtins.html#builtins-any", "#builtin-attrValues": "language/builtins.html#builtins-attrValues",
"#builtin-attrNames": "expressions/builtins.html#builtins-attrNames", "#builtin-baseNameOf": "language/builtins.html#builtins-baseNameOf",
"#builtin-attrValues": "expressions/builtins.html#builtins-attrValues", "#builtin-bitAnd": "language/builtins.html#builtins-bitAnd",
"#builtin-baseNameOf": "expressions/builtins.html#builtins-baseNameOf", "#builtin-bitOr": "language/builtins.html#builtins-bitOr",
"#builtin-bitAnd": "expressions/builtins.html#builtins-bitAnd", "#builtin-bitXor": "language/builtins.html#builtins-bitXor",
"#builtin-bitOr": "expressions/builtins.html#builtins-bitOr", "#builtin-builtins": "language/builtins.html#builtins-builtins",
"#builtin-bitXor": "expressions/builtins.html#builtins-bitXor", "#builtin-compareVersions": "language/builtins.html#builtins-compareVersions",
"#builtin-builtins": "expressions/builtins.html#builtins-builtins", "#builtin-concatLists": "language/builtins.html#builtins-concatLists",
"#builtin-compareVersions": "expressions/builtins.html#builtins-compareVersions", "#builtin-concatStringsSep": "language/builtins.html#builtins-concatStringsSep",
"#builtin-concatLists": "expressions/builtins.html#builtins-concatLists", "#builtin-currentSystem": "language/builtins.html#builtins-currentSystem",
"#builtin-concatStringsSep": "expressions/builtins.html#builtins-concatStringsSep", "#builtin-deepSeq": "language/builtins.html#builtins-deepSeq",
"#builtin-currentSystem": "expressions/builtins.html#builtins-currentSystem", "#builtin-derivation": "language/builtins.html#builtins-derivation",
"#builtin-deepSeq": "expressions/builtins.html#builtins-deepSeq", "#builtin-dirOf": "language/builtins.html#builtins-dirOf",
"#builtin-derivation": "expressions/builtins.html#builtins-derivation", "#builtin-div": "language/builtins.html#builtins-div",
"#builtin-dirOf": "expressions/builtins.html#builtins-dirOf", "#builtin-elem": "language/builtins.html#builtins-elem",
"#builtin-div": "expressions/builtins.html#builtins-div", "#builtin-elemAt": "language/builtins.html#builtins-elemAt",
"#builtin-elem": "expressions/builtins.html#builtins-elem", "#builtin-fetchGit": "language/builtins.html#builtins-fetchGit",
"#builtin-elemAt": "expressions/builtins.html#builtins-elemAt", "#builtin-fetchTarball": "language/builtins.html#builtins-fetchTarball",
"#builtin-fetchGit": "expressions/builtins.html#builtins-fetchGit", "#builtin-fetchurl": "language/builtins.html#builtins-fetchurl",
"#builtin-fetchTarball": "expressions/builtins.html#builtins-fetchTarball", "#builtin-filterSource": "language/builtins.html#builtins-filterSource",
"#builtin-fetchurl": "expressions/builtins.html#builtins-fetchurl", "#builtin-foldl-prime": "language/builtins.html#builtins-foldl-prime",
"#builtin-filterSource": "expressions/builtins.html#builtins-filterSource", "#builtin-fromJSON": "language/builtins.html#builtins-fromJSON",
"#builtin-foldl-prime": "expressions/builtins.html#builtins-foldl-prime", "#builtin-functionArgs": "language/builtins.html#builtins-functionArgs",
"#builtin-fromJSON": "expressions/builtins.html#builtins-fromJSON", "#builtin-genList": "language/builtins.html#builtins-genList",
"#builtin-functionArgs": "expressions/builtins.html#builtins-functionArgs", "#builtin-getAttr": "language/builtins.html#builtins-getAttr",
"#builtin-genList": "expressions/builtins.html#builtins-genList", "#builtin-getEnv": "language/builtins.html#builtins-getEnv",
"#builtin-getAttr": "expressions/builtins.html#builtins-getAttr", "#builtin-hasAttr": "language/builtins.html#builtins-hasAttr",
"#builtin-getEnv": "expressions/builtins.html#builtins-getEnv", "#builtin-hashFile": "language/builtins.html#builtins-hashFile",
"#builtin-hasAttr": "expressions/builtins.html#builtins-hasAttr", "#builtin-hashString": "language/builtins.html#builtins-hashString",
"#builtin-hashFile": "expressions/builtins.html#builtins-hashFile", "#builtin-head": "language/builtins.html#builtins-head",
"#builtin-hashString": "expressions/builtins.html#builtins-hashString", "#builtin-import": "language/builtins.html#builtins-import",
"#builtin-head": "expressions/builtins.html#builtins-head", "#builtin-intersectAttrs": "language/builtins.html#builtins-intersectAttrs",
"#builtin-import": "expressions/builtins.html#builtins-import", "#builtin-isAttrs": "language/builtins.html#builtins-isAttrs",
"#builtin-intersectAttrs": "expressions/builtins.html#builtins-intersectAttrs", "#builtin-isBool": "language/builtins.html#builtins-isBool",
"#builtin-isAttrs": "expressions/builtins.html#builtins-isAttrs", "#builtin-isFloat": "language/builtins.html#builtins-isFloat",
"#builtin-isBool": "expressions/builtins.html#builtins-isBool", "#builtin-isFunction": "language/builtins.html#builtins-isFunction",
"#builtin-isFloat": "expressions/builtins.html#builtins-isFloat", "#builtin-isInt": "language/builtins.html#builtins-isInt",
"#builtin-isFunction": "expressions/builtins.html#builtins-isFunction", "#builtin-isList": "language/builtins.html#builtins-isList",
"#builtin-isInt": "expressions/builtins.html#builtins-isInt", "#builtin-isNull": "language/builtins.html#builtins-isNull",
"#builtin-isList": "expressions/builtins.html#builtins-isList", "#builtin-isString": "language/builtins.html#builtins-isString",
"#builtin-isNull": "expressions/builtins.html#builtins-isNull", "#builtin-length": "language/builtins.html#builtins-length",
"#builtin-isString": "expressions/builtins.html#builtins-isString", "#builtin-lessThan": "language/builtins.html#builtins-lessThan",
"#builtin-length": "expressions/builtins.html#builtins-length", "#builtin-listToAttrs": "language/builtins.html#builtins-listToAttrs",
"#builtin-lessThan": "expressions/builtins.html#builtins-lessThan", "#builtin-map": "language/builtins.html#builtins-map",
"#builtin-listToAttrs": "expressions/builtins.html#builtins-listToAttrs", "#builtin-match": "language/builtins.html#builtins-match",
"#builtin-map": "expressions/builtins.html#builtins-map", "#builtin-mul": "language/builtins.html#builtins-mul",
"#builtin-match": "expressions/builtins.html#builtins-match", "#builtin-parseDrvName": "language/builtins.html#builtins-parseDrvName",
"#builtin-mul": "expressions/builtins.html#builtins-mul", "#builtin-path": "language/builtins.html#builtins-path",
"#builtin-parseDrvName": "expressions/builtins.html#builtins-parseDrvName", "#builtin-pathExists": "language/builtins.html#builtins-pathExists",
"#builtin-path": "expressions/builtins.html#builtins-path", "#builtin-placeholder": "language/builtins.html#builtins-placeholder",
"#builtin-pathExists": "expressions/builtins.html#builtins-pathExists", "#builtin-readDir": "language/builtins.html#builtins-readDir",
"#builtin-placeholder": "expressions/builtins.html#builtins-placeholder", "#builtin-readFile": "language/builtins.html#builtins-readFile",
"#builtin-readDir": "expressions/builtins.html#builtins-readDir", "#builtin-removeAttrs": "language/builtins.html#builtins-removeAttrs",
"#builtin-readFile": "expressions/builtins.html#builtins-readFile", "#builtin-replaceStrings": "language/builtins.html#builtins-replaceStrings",
"#builtin-removeAttrs": "expressions/builtins.html#builtins-removeAttrs", "#builtin-seq": "language/builtins.html#builtins-seq",
"#builtin-replaceStrings": "expressions/builtins.html#builtins-replaceStrings", "#builtin-sort": "language/builtins.html#builtins-sort",
"#builtin-seq": "expressions/builtins.html#builtins-seq", "#builtin-split": "language/builtins.html#builtins-split",
"#builtin-sort": "expressions/builtins.html#builtins-sort", "#builtin-splitVersion": "language/builtins.html#builtins-splitVersion",
"#builtin-split": "expressions/builtins.html#builtins-split", "#builtin-stringLength": "language/builtins.html#builtins-stringLength",
"#builtin-splitVersion": "expressions/builtins.html#builtins-splitVersion", "#builtin-sub": "language/builtins.html#builtins-sub",
"#builtin-stringLength": "expressions/builtins.html#builtins-stringLength", "#builtin-substring": "language/builtins.html#builtins-substring",
"#builtin-sub": "expressions/builtins.html#builtins-sub", "#builtin-tail": "language/builtins.html#builtins-tail",
"#builtin-substring": "expressions/builtins.html#builtins-substring", "#builtin-throw": "language/builtins.html#builtins-throw",
"#builtin-tail": "expressions/builtins.html#builtins-tail", "#builtin-toFile": "language/builtins.html#builtins-toFile",
"#builtin-throw": "expressions/builtins.html#builtins-throw", "#builtin-toJSON": "language/builtins.html#builtins-toJSON",
"#builtin-toFile": "expressions/builtins.html#builtins-toFile", "#builtin-toPath": "language/builtins.html#builtins-toPath",
"#builtin-toJSON": "expressions/builtins.html#builtins-toJSON", "#builtin-toString": "language/builtins.html#builtins-toString",
"#builtin-toPath": "expressions/builtins.html#builtins-toPath", "#builtin-toXML": "language/builtins.html#builtins-toXML",
"#builtin-toString": "expressions/builtins.html#builtins-toString", "#builtin-trace": "language/builtins.html#builtins-trace",
"#builtin-toXML": "expressions/builtins.html#builtins-toXML", "#builtin-tryEval": "language/builtins.html#builtins-tryEval",
"#builtin-trace": "expressions/builtins.html#builtins-trace", "#builtin-typeOf": "language/builtins.html#builtins-typeOf",
"#builtin-tryEval": "expressions/builtins.html#builtins-tryEval", "#ssec-builtins": "language/builtins.html",
"#builtin-typeOf": "expressions/builtins.html#builtins-typeOf", "#attr-system": "language/derivations.html#attr-system",
"#ssec-builtins": "expressions/builtins.html", "#ssec-derivation": "language/derivations.html",
"#attr-system": "expressions/derivations.html#attr-system", "#ch-expression-language": "language/index.html",
"#ssec-derivation": "expressions/derivations.html", "#sec-constructs": "language/constructs.html",
"#ch-expression-language": "expressions/expression-language.html", "#sect-let-language": "language/constructs.html#let-language",
"#sec-expression-syntax": "expressions/expression-syntax.html", "#ss-functions": "language/constructs.html#functions",
"#sec-generic-builder": "expressions/generic-builder.html", "#sec-language-operators": "language/operators.html",
"#sec-constructs": "expressions/language-constructs.html", "#table-operators": "language/operators.html",
"#sect-let-expressions": "expressions/language-constructs.html#let-expressions", "#ssec-values": "language/values.html",
"#ss-functions": "expressions/language-constructs.html#functions",
"#sec-language-operators": "expressions/language-operators.html",
"#table-operators": "expressions/language-operators.html",
"#ssec-values": "expressions/language-values.html",
"#sec-building-simple": "expressions/simple-building-testing.html",
"#ch-simple-expression": "expressions/simple-expression.html",
"#chap-writing-nix-expressions": "expressions/writing-nix-expressions.html",
"#gloss-closure": "glossary.html#gloss-closure", "#gloss-closure": "glossary.html#gloss-closure",
"#gloss-derivation": "glossary.html#gloss-derivation", "#gloss-derivation": "glossary.html#gloss-derivation",
"#gloss-deriver": "glossary.html#gloss-deriver", "#gloss-deriver": "glossary.html#gloss-deriver",

23
doc/manual/src/SUMMARY.md.in
View file

@ -26,21 +26,14 @@
- [Copying Closures via SSH](package-management/copy-closure.md) - [Copying Closures via SSH](package-management/copy-closure.md)
- [Serving a Nix store via SSH](package-management/ssh-substituter.md) - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
- [Serving a Nix store via S3](package-management/s3-substituter.md) - [Serving a Nix store via S3](package-management/s3-substituter.md)
- [Writing Nix Expressions](expressions/writing-nix-expressions.md) - [Nix Language](language/index.md)
- [A Simple Nix Expression](expressions/simple-expression.md) - [Data Types](language/values.md)
- [Expression Syntax](expressions/expression-syntax.md) - [Language Constructs](language/constructs.md)
- [Build Script](expressions/build-script.md) - [Operators](language/operators.md)
- [Arguments and Variables](expressions/arguments-variables.md) - [Derivations](language/derivations.md)
- [Building and Testing](expressions/simple-building-testing.md) - [Advanced Attributes](language/advanced-attributes.md)
- [Generic Builder Syntax](expressions/generic-builder.md) - [Built-in Constants](language/builtin-constants.md)
- [Nix Expression Language](expressions/expression-language.md) - [Built-in Functions](language/builtins.md)
- [Data Types](expressions/language-values.md)
- [Language Constructs](expressions/language-constructs.md)
- [Operators](expressions/language-operators.md)
- [Derivations](expressions/derivations.md)
- [Advanced Attributes](expressions/advanced-attributes.md)
- [Built-in Constants](expressions/builtin-constants.md)
- [Built-in Functions](expressions/builtins.md)
- [Advanced Topics](advanced-topics/advanced-topics.md) - [Advanced Topics](advanced-topics/advanced-topics.md)
- [Remote Builds](advanced-topics/distributed-builds.md) - [Remote Builds](advanced-topics/distributed-builds.md)
- [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md) - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)

2
doc/manual/src/command-ref/nix-env.md
View file

@ -198,7 +198,7 @@ a number of possible ways:
another. another.
- If `--from-expression` is given, *args* are Nix - If `--from-expression` is given, *args* are Nix
[functions](../expressions/language-constructs.md#functions) [functions](../language/constructs.md#functions)
that are called with the active Nix expression as their single that are called with the active Nix expression as their single
argument. The derivations returned by those function calls are argument. The derivations returned by those function calls are
installed. This allows derivations to be specified in an installed. This allows derivations to be specified in an

4
doc/manual/src/command-ref/nix-instantiate.md
View file

@ -51,7 +51,7 @@ standard input.
- `--strict`\ - `--strict`\
When used with `--eval`, recursively evaluate list elements and When used with `--eval`, recursively evaluate list elements and
attributes. Normally, such sub-expressions are left unevaluated attributes. Normally, such sub-expressions are left unevaluated
(since the Nix expression language is lazy). (since the Nix language is lazy).
> **Warning** > **Warning**
> >
@ -66,7 +66,7 @@ standard input.
When used with `--eval`, print the resulting value as an XML When used with `--eval`, print the resulting value as an XML
representation of the abstract syntax tree rather than as an ATerm. representation of the abstract syntax tree rather than as an ATerm.
The schema is the same as that used by the [`toXML` The schema is the same as that used by the [`toXML`
built-in](../expressions/builtins.md). built-in](../language/builtins.md).
- `--read-write-mode`\ - `--read-write-mode`\
When used with `--eval`, perform evaluation in read/write mode so When used with `--eval`, perform evaluation in read/write mode so

2
doc/manual/src/command-ref/nix-store.md
View file

@ -121,7 +121,7 @@ Special exit codes:
- `102`\ - `102`\
Hash mismatch, the build output was rejected because it does not Hash mismatch, the build output was rejected because it does not
match the [`outputHash` attribute of the match the [`outputHash` attribute of the
derivation](../expressions/advanced-attributes.md). derivation](../language/advanced-attributes.md).
- `104`\ - `104`\
Not deterministic, the build succeeded in check mode but the Not deterministic, the build succeeded in check mode but the

4
doc/manual/src/command-ref/opt-common.md
View file

@ -145,7 +145,7 @@ Most Nix commands accept the following command-line options:
expression evaluator will automatically try to call functions that expression evaluator will automatically try to call functions that
it encounters. It can automatically call functions for which every it encounters. It can automatically call functions for which every
argument has a [default argument has a [default
value](../expressions/language-constructs.md#functions) (e.g., value](../language/constructs.md#functions) (e.g.,
`{ argName ? defaultValue }: ...`). With `--arg`, you can also `{ argName ? defaultValue }: ...`). With `--arg`, you can also
call functions that have arguments without a default value (or call functions that have arguments without a default value (or
override a default value). That is, if the evaluator encounters a override a default value). That is, if the evaluator encounters a
@ -164,7 +164,7 @@ Most Nix commands accept the following command-line options:
So if you call this Nix expression (e.g., when you do `nix-env -iA So if you call this Nix expression (e.g., when you do `nix-env -iA
pkgname`), the function will be called automatically using the pkgname`), the function will be called automatically using the
value [`builtins.currentSystem`](../expressions/builtins.md) for value [`builtins.currentSystem`](../language/builtins.md) for
the `system` argument. You can override this using `--arg`, e.g., the `system` argument. You can override this using `--arg`, e.g.,
`nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that `nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that
since the argument is a Nix string literal, you have to escape the since the argument is a Nix string literal, you have to escape the

80
doc/manual/src/expressions/arguments-variables.md
View file

@ -1,80 +0,0 @@
# Arguments and Variables
The [Nix expression for GNU Hello](expression-syntax.md) is a
function; it is missing some arguments that have to be filled in
somewhere. In the Nix Packages collection this is done in the file
`pkgs/top-level/all-packages.nix`, where all Nix expressions for
packages are imported and called with the appropriate arguments. Here
are some fragments of `all-packages.nix`, with annotations of what
they mean:
```nix
...
rec { ①
hello = import ../applications/misc/hello/ex-1 ② { ③
inherit fetchurl stdenv perl;
};
perl = import ../development/interpreters/perl { ④
inherit fetchurl stdenv;
};
fetchurl = import ../build-support/fetchurl {
inherit stdenv; ...
};
stdenv = ...;
}
```
1. This file defines a set of attributes, all of which are concrete
derivations (i.e., not functions). In fact, we define a *mutually
recursive* set of attributes. That is, the attributes can refer to
each other. This is precisely what we want since we want to “plug”
the various packages into each other.
2. Here we *import* the Nix expression for GNU Hello. The import
operation just loads and returns the specified Nix expression. In
fact, we could just have put the contents of the Nix expression
for GNU Hello in `all-packages.nix` at this point. That would be
completely equivalent, but it would make `all-packages.nix` rather
bulky.
Note that we refer to `../applications/misc/hello/ex-1`, not
`../applications/misc/hello/ex-1/default.nix`. When you try to
import a directory, Nix automatically appends `/default.nix` to the
file name.
3. This is where the actual composition takes place. Here we *call* the
function imported from `../applications/misc/hello/ex-1` with a set
containing the things that the function expects, namely `fetchurl`,
`stdenv`, and `perl`. We use inherit again to use the attributes
defined in the surrounding scope (we could also have written
`fetchurl = fetchurl;`, etc.).
The result of this function call is an actual derivation that can be
built by Nix (since when we fill in the arguments of the function,
what we get is its body, which is the call to `stdenv.mkDerivation`
in the [Nix expression for GNU Hello](expression-syntax.md)).
> **Note**
>
> Nixpkgs has a convenience function `callPackage` that imports and
> calls a function, filling in any missing arguments by passing the
> corresponding attribute from the Nixpkgs set, like this:
>
> ```nix
> hello = callPackage ../applications/misc/hello/ex-1 { };
> ```
>
> If necessary, you can set or override arguments:
>
> ```nix
> hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
> ```
4. Likewise, we have to instantiate Perl, `fetchurl`, and the standard
environment.

70
doc/manual/src/expressions/build-script.md
View file

@ -1,70 +0,0 @@
# Build Script
Here is the builder referenced from Hello's Nix expression (stored in
`pkgs/applications/misc/hello/ex-1/builder.sh`):
```bash
source $stdenv/setup ①
PATH=$perl/bin:$PATH ②
tar xvfz $src ③
cd hello-*
./configure --prefix=$out ④
make ⑤
make install
```
The builder can actually be made a lot shorter by using the *generic
builder* functions provided by `stdenv`, but here we write out the build
steps to elucidate what a builder does. It performs the following steps:
1. When Nix runs a builder, it initially completely clears the
environment (except for the attributes declared in the derivation).
This is done to prevent undeclared inputs from being used in the
build process. If for example the `PATH` contained `/usr/bin`, then
you might accidentally use `/usr/bin/gcc`.
So the first step is to set up the environment. This is done by
calling the `setup` script of the standard environment. The
environment variable `stdenv` points to the location of the
standard environment being used. (It wasn't specified explicitly
as an attribute in Hello's Nix expression, but `mkDerivation` adds
it automatically.)
2. Since Hello needs Perl, we have to make sure that Perl is in the
`PATH`. The `perl` environment variable points to the location of
the Perl package (since it was passed in as an attribute to the
derivation), so `$perl/bin` is the directory containing the Perl
interpreter.
3. Now we have to unpack the sources. The `src` attribute was bound to
the result of fetching the Hello source tarball from the network, so
the `src` environment variable points to the location in the Nix
store to which the tarball was downloaded. After unpacking, we `cd`
to the resulting source directory.
The whole build is performed in a temporary directory created in
`/tmp`, by the way. This directory is removed after the builder
finishes, so there is no need to clean up the sources afterwards.
Also, the temporary directory is always newly created, so you don't
have to worry about files from previous builds interfering with the
current build.
4. GNU Hello is a typical Autoconf-based package, so we first have to
run its `configure` script. In Nix every package is stored in a
separate location in the Nix store, for instance
`/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
computes this path by cryptographically hashing all attributes of
the derivation. The path is passed to the builder through the `out`
environment variable. So here we give `configure` the parameter
`--prefix=$out` to cause Hello to be installed in the expected
location.
5. Finally we build Hello (`make`) and install it into the location
specified by `out` (`make install`).
If you are wondering about the absence of error checking on the result
of various commands called in the builder: this is because the shell
script is evaluated with Bash's `-e` option, which causes the script to
be aborted if any command fails without an error check.

93
doc/manual/src/expressions/expression-syntax.md
View file

@ -1,93 +0,0 @@
# Expression Syntax
Here is a Nix expression for GNU Hello:
```nix
{ stdenv, fetchurl, perl }: ①
stdenv.mkDerivation { ②
name = "hello-2.1.1"; ③
builder = ./builder.sh; ④
src = fetchurl { ⑤
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
};
inherit perl; ⑥
}
```
This file is actually already in the Nix Packages collection in
`pkgs/applications/misc/hello/ex-1/default.nix`. It is customary to
place each package in a separate directory and call the single Nix
expression in that directory `default.nix`. The file has the following
elements (referenced from the figure by number):
1. This states that the expression is a *function* that expects to be
called with three arguments: `stdenv`, `fetchurl`, and `perl`. They
are needed to build Hello, but we don't know how to build them here;
that's why they are function arguments. `stdenv` is a package that
is used by almost all Nix Packages; it provides a
“standard” environment consisting of the things you would expect
in a basic Unix environment: a C/C++ compiler (GCC, to be precise),
the Bash shell, fundamental Unix tools such as `cp`, `grep`, `tar`,
etc. `fetchurl` is a function that downloads files. `perl` is the
Perl interpreter.
Nix functions generally have the form `{ x, y, ..., z }: e` where
`x`, `y`, etc. are the names of the expected arguments, and where
*e* is the body of the function. So here, the entire remainder of
the file is the body of the function; when given the required
arguments, the body should describe how to build an instance of
the Hello package.
2. So we have to build a package. Building something from other stuff
is called a *derivation* in Nix (as opposed to sources, which are
built by humans instead of computers). We perform a derivation by
calling `stdenv.mkDerivation`. `mkDerivation` is a function
provided by `stdenv` that builds a package from a set of
*attributes*. A set is just a list of key/value pairs where each
key is a string and each value is an arbitrary Nix
expression. They take the general form `{ name1 = expr1; ...
nameN = exprN; }`.
3. The attribute `name` specifies the symbolic name and version of
the package. Nix doesn't really care about these things, but they
are used by for instance `nix-env -q` to show a “human-readable”
name for packages. This attribute is required by `mkDerivation`.
4. The attribute `builder` specifies the builder. This attribute can
sometimes be omitted, in which case `mkDerivation` will fill in a
default builder (which does a `configure; make; make install`, in
essence). Hello is sufficiently simple that the default builder
would suffice, but in this case, we will show an actual builder
for educational purposes. The value `./builder.sh` refers to the
shell script shown in the [next section](build-script.md),
discussed below.
5. The builder has to know what the sources of the package are. Here,
the attribute `src` is bound to the result of a call to the
`fetchurl` function. Given a URL and a SHA-256 hash of the expected
contents of the file at that URL, this function builds a derivation
that downloads the file and checks its hash. So the sources are a
dependency that like all other dependencies is built before Hello
itself is built.
Instead of `src` any other name could have been used, and in fact
there can be any number of sources (bound to different attributes).
However, `src` is customary, and it's also expected by the default
builder (which we don't use in this example).
6. Since the derivation requires Perl, we have to pass the value of the
`perl` function argument to the builder. All attributes in the set
are actually passed as environment variables to the builder, so
declaring an attribute
```nix
perl = perl;
```
will do the trick: it binds an attribute `perl` to the function
argument which also happens to be called `perl`. However, it looks a
bit silly, so there is a shorter syntax. The `inherit` keyword
causes the specified attributes to be bound to whatever variables
with the same name happen to be in scope.

66
doc/manual/src/expressions/generic-builder.md
View file

@ -1,66 +0,0 @@
# Generic Builder Syntax
Recall that the [build script for GNU Hello](build-script.md) looked
something like this:
```bash
PATH=$perl/bin:$PATH
tar xvfz $src
cd hello-*
./configure --prefix=$out
make
make install
```
The builders for almost all Unix packages look like this — set up some
environment variables, unpack the sources, configure, build, and
install. For this reason the standard environment provides some Bash
functions that automate the build process. Here is what a builder using
the generic build facilities looks like:
```bash
buildInputs="$perl" ①
source $stdenv/setup ②
genericBuild ③
```
Here is what each line means:
1. The `buildInputs` variable tells `setup` to use the indicated
packages as “inputs”. This means that if a package provides a `bin`
subdirectory, it's added to `PATH`; if it has a `include`
subdirectory, it's added to GCC's header search path; and so on.
(This is implemented in a modular way: `setup` tries to source the
file `pkg/nix-support/setup-hook` of all dependencies. These “setup
hooks” can then set up whatever environment variables they want; for
instance, the setup hook for Perl sets the `PERL5LIB` environment
variable to contain the `lib/site_perl` directories of all inputs.)
2. The function `genericBuild` is defined in the file `$stdenv/setup`.
3. The final step calls the shell function `genericBuild`, which
performs the steps that were done explicitly in the previous build
script. The generic builder is smart enough to figure out whether
to unpack the sources using `gzip`, `bzip2`, etc. It can be
customised in many ways; see the Nixpkgs manual for details.
Discerning readers will note that the `buildInputs` could just as well
have been set in the Nix expression, like this:
```nix
buildInputs = [ perl ];
```
The `perl` attribute can then be removed, and the builder becomes even
shorter:
```bash
source $stdenv/setup
genericBuild
```
In fact, `mkDerivation` provides a default builder that looks exactly
like that, so it is actually possible to omit the builder for Hello
entirely.

61
doc/manual/src/expressions/simple-building-testing.md
View file

@ -1,61 +0,0 @@
# Building and Testing
You can now try to build Hello. Of course, you could do `nix-env -f . -iA
hello`, but you may not want to install a possibly broken package just
yet. The best way to test the package is by using the command
`nix-build`, which builds a Nix expression and creates a symlink named
`result` in the current directory:
```console
$ nix-build -A hello
building path `/nix/store/632d2b22514d...-hello-2.1.1'
hello-2.1.1/
hello-2.1.1/intl/
hello-2.1.1/intl/ChangeLog
...
$ ls -l result
lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
$ ./result/bin/hello
Hello, world!
```
The `-A` option selects the `hello` attribute. This is faster than
using the symbolic package name specified by the `name` attribute
(which also happens to be `hello`) and is unambiguous (there can be
multiple packages with the symbolic name `hello`, but there can be
only one attribute in a set named `hello`).
`nix-build` registers the `./result` symlink as a garbage collection
root, so unless and until you delete the `./result` symlink, the output
of the build will be safely kept on your system. You can use
`nix-build`’s `-o` switch to give the symlink another name.
Nix has transactional semantics. Once a build finishes successfully, Nix
makes a note of this in its database: it registers that the path denoted
by `out` is now “valid”. If you try to build the derivation again, Nix
will see that the path is already valid and finish immediately. If a
build fails, either because it returns a non-zero exit code, because Nix
or the builder are killed, or because the machine crashes, then the
output paths will not be registered as valid. If you try to build the
derivation again, Nix will remove the output paths if they exist (e.g.,
because the builder died half-way through `make
install`) and try again. Note that there is no “negative caching”: Nix
doesn't remember that a build failed, and so a failed build can always
be repeated. This is because Nix cannot distinguish between permanent
failures (e.g., a compiler error due to a syntax error in the source)
and transient failures (e.g., a disk full condition).
Nix also performs locking. If you run multiple Nix builds
simultaneously, and they try to build the same derivation, the first Nix
instance that gets there will perform the build, while the others block
(or perform other derivations if available) until the build finishes:
```console
$ nix-build -A hello
waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'
```
So it is always safe to run multiple instances of Nix in parallel (which
isn’t the case with, say, `make`).

23
doc/manual/src/expressions/simple-expression.md
View file

@ -1,23 +0,0 @@
# A Simple Nix Expression
This section shows how to add and test the [GNU Hello
package](http://www.gnu.org/software/hello/hello.html) to the Nix
Packages collection. Hello is a program that prints out the text “Hello,
world\!”.
To add a package to the Nix Packages collection, you generally need to
do three things:
1. Write a Nix expression for the package. This is a file that
describes all the inputs involved in building the package, such as
dependencies, sources, and so on.
2. Write a *builder*. This is a shell script that builds the package
from the inputs. (In fact, it can be written in any language, but
typically it's a `bash` shell script.)
3. Add the package to the file `pkgs/top-level/all-packages.nix`. The
Nix expression written in the first step is a *function*; it
requires other packages in order to build it. In this step you put
it all together, i.e., you call the function with the right
arguments to build the actual package.

12
doc/manual/src/expressions/writing-nix-expressions.md
View file

@ -1,12 +0,0 @@
This chapter shows you how to write Nix expressions, which instruct Nix
how to build packages. It starts with a simple example (a Nix expression
for GNU Hello), and then moves on to a more in-depth look at the Nix
expression language.
> **Note**
>
> This chapter is mostly about the Nix expression language. For more
> extensive information on adding packages to the Nix Packages
> collection (such as functions in the standard environment and coding
> conventions), please consult [its
> manual](http://nixos.org/nixpkgs/manual/).

2
doc/manual/src/glossary.md
View file

@ -3,7 +3,7 @@
- [derivation]{#gloss-derivation}\ - [derivation]{#gloss-derivation}\
A description of a build action. The result of a derivation is a A description of a build action. The result of a derivation is a
store object. Derivations are typically specified in Nix expressions store object. Derivations are typically specified in Nix expressions
using the [`derivation` primitive](expressions/derivations.md). These are using the [`derivation` primitive](language/derivations.md). These are
translated into low-level *store derivations* (implicitly by translated into low-level *store derivations* (implicitly by
`nix-env` and `nix-build`, or explicitly by `nix-instantiate`). `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).

0
doc/manual/src/expressions/advanced-attributes.md → doc/manual/src/language/advanced-attributes.md
View file

0
doc/manual/src/expressions/builtin-constants.md → doc/manual/src/language/builtin-constants.md
View file

0
doc/manual/src/expressions/builtins-prefix.md → doc/manual/src/language/builtins-prefix.md
View file

0
doc/manual/src/expressions/builtins-suffix.md → doc/manual/src/language/builtins-suffix.md
View file

0
doc/manual/src/expressions/language-constructs.md → doc/manual/src/language/constructs.md
View file

0
doc/manual/src/expressions/derivations.md → doc/manual/src/language/derivations.md
View file

5
doc/manual/src/expressions/expression-language.md → doc/manual/src/language/index.md
View file

@ -1,6 +1,6 @@
# Nix Expression Language # Nix Language
The Nix expression language is a pure, lazy, functional language. Purity The Nix language is a pure, lazy, functional language. Purity
means that operations in the language don't have side-effects (for means that operations in the language don't have side-effects (for
instance, there is no variable assignment). Laziness means that instance, there is no variable assignment). Laziness means that
arguments to functions are evaluated only when they are needed. arguments to functions are evaluated only when they are needed.
@ -10,3 +10,4 @@ full-featured, general purpose language. Its main job is to describe
packages, compositions of packages, and the variability within packages. packages, compositions of packages, and the variability within packages.
This section presents the various features of the language. This section presents the various features of the language.

2
doc/manual/src/expressions/language-operators.md → doc/manual/src/language/operators.md
View file

@ -1,6 +1,6 @@
# Operators # Operators
The table below lists the operators in the Nix expression language, in The table below lists the operators in the Nix language, in
order of precedence (from strongest to weakest binding). order of precedence (from strongest to weakest binding).
| Name | Syntax | Associativity | Description | Precedence | | Name | Syntax | Associativity | Description | Precedence |

0
doc/manual/src/expressions/language-values.md → doc/manual/src/language/values.md
View file

3
doc/manual/src/package-management/package-management.md
View file

@ -1,5 +1,4 @@
This chapter discusses how to do package management with Nix, i.e., This chapter discusses how to do package management with Nix, i.e.,
how to obtain, install, upgrade, and erase packages. This is the how to obtain, install, upgrade, and erase packages. This is the
“user’s” perspective of the Nix system — people who want to *create* “user’s” perspective of the Nix system — people who want to *create*
packages should consult the [chapter on writing Nix packages should consult the chapter on the [Nix language](../language/index.md).
expressions](../expressions/writing-nix-expressions.md).