From 5d89525367527b659fe9732c4ed90b4e9c2f3658 Mon Sep 17 00:00:00 2001 From: Klaus Aehlig Date: Thu, 5 May 2022 14:26:36 +0200 Subject: Verify conflict-freeness in inputs, artifacts, and runfiles Our maps serve two purposes: on the one hand, they can be a generic key-value association with arbitrary strings as keys. On the other hand, we use them to describe arrangements of files (inputs to actions, artifacts or runfiles generated). In this function, certain keys refer to the same path and hence have to be identifed. Therefore, at places where the keys clearly have to be paths in the file system, implicitly normalize them and check for conflicts. --- doc/concepts/rules.org | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) (limited to 'doc/concepts') diff --git a/doc/concepts/rules.org b/doc/concepts/rules.org index 8c84cb2a..f5cfdd8c 100644 --- a/doc/concepts/rules.org +++ b/doc/concepts/rules.org @@ -150,6 +150,14 @@ archiver, etc. The action function takes the following arguments. not modify the input files in any way. (In-place operations can be simulated by staging, as is shown in the example later in this document.) + + It is an additional requirement that no conflicts occur when + interpreting the keys as paths. For example, ~"foo.txt"~ and + ~"./foo.txt"~ are different as strings and hence legitimately + can be assigned different values in a map. When interpreted as + a path, however, they name the same path; so, if the ~"inputs"~ + map contains both those keys, the corresponding values have + to be equal. - ~"cmd"~ The command to execute, given as ~argv~ vector, i.e., a non-empty list of strings. The 0'th element of that list will also be the program to be executed. @@ -169,12 +177,16 @@ environment with the given inputs). **** ~RESULT~ The ~RESULT~ function is the only way to obtain a result value. -It takes three (evaluated) arguments, ~artifacts~, ~runfiles~, and -~provides~, all of which are optional and default to the empty map. +It takes three (evaluated) arguments, ~"artifacts"~, ~"runfiles"~, and +~"provides"~, all of which are optional and default to the empty map. It defines the result of a target that has the given artifacts, -runfiles, and provided data, respectively. In particular, ~artifacts~ -and ~runfiles~ have to be maps to artifacts, and ~provides~ has -to be a map. +runfiles, and provided data, respectively. In particular, ~"artifacts"~ +and ~"runfiles"~ have to be maps to artifacts, and ~"provides"~ has +to be a map. Moreover, they keys in ~"runfiles"~ and ~"artifacts"~ +are treated as paths; it is an error if this interpretation yields +to conflicts. The keys in the artifacts or runfile maps as seen by +other targets are the normalized paths of the keys given. + Result values themselves are opaque in our expression language and cannot be deconstructed in any way. Their only purpose is to -- cgit v1.2.3