about summary refs log tree commit diff
path: root/src/libexpr/nixexpr-ast.def
diff options
context:
space:
mode:
Diffstat (limited to 'src/libexpr/nixexpr-ast.def')
-rw-r--r--src/libexpr/nixexpr-ast.def32
1 files changed, 30 insertions, 2 deletions
diff --git a/src/libexpr/nixexpr-ast.def b/src/libexpr/nixexpr-ast.def
index b797fcfc440e..fe5fe71b0a05 100644
--- a/src/libexpr/nixexpr-ast.def
+++ b/src/libexpr/nixexpr-ast.def
@@ -24,8 +24,37 @@ Call | Expr Expr | Expr |
 Select | Expr string | Expr |
 Var | string | Expr |
 Int | int | Expr |
-Str | string | Expr |
+
+# Strings in the evaluator carry a so-called `context' (the ATermList)
+# which is a list of strings representing store paths.  This is to
+# allow users to write things like
+#
+#   "--with-freetype2-library=" + freetype + "/lib"
+#
+# where `freetype' is a derivation (or a source to be copied to the
+# store).  If we just concatenated the strings without keeping track
+# of the referenced store paths, then if the string is used as a
+# derivation attribute, the derivation will not have the correct
+# dependencies in its inputDrvs and inputSrcs.
+#
+# The semantics of the context is as follows: when a string with
+# context C is used as a derivation attribute, then the derivations in
+# C will be added to the inputDrvs of the derivation, and the other
+# store paths in C will be added to the inputSrcs of the derivations.
+#
+# For canonicity, the store paths should be in sorted order.
+Str | string ATermList | Expr |
+
+# A path is a reference to a file system object that is to be copied
+# to the Nix store when used as a derivation attribute.  When it is
+# concatenated to a string (i.e., `str + path'), it is also copied and
+# the resulting store path is concatenated to the string (with the
+# store path in the context).  If a string or path is concatenated to
+# a path (i.e., `path + str' or `path + path'), the result is a new
+# path (if the right-hand side is a string, the context must be
+# empty).
 Path | string | Expr |
+
 List | ATermList | Expr |
 BlackHole | | Expr |
 Undefined | | Expr |
@@ -36,7 +65,6 @@ Closed | Expr | Expr |
 Rec | ATermList ATermList | Expr |
 Bool | ATerm | Expr |
 Null | | Expr |
-Context | ATermList Expr | Expr |
 
 Bind | string Expr Pos | ATerm |
 Bind | string Expr | ATerm | Bind2