diff options
Diffstat (limited to 'doc/concepts')
| -rw-r--r-- | doc/concepts/anonymous-targets.org | 16 | ||||
| -rw-r--r-- | doc/concepts/built-in-rules.org | 6 | ||||
| -rw-r--r-- | doc/concepts/cache-pragma.org | 4 | ||||
| -rw-r--r-- | doc/concepts/doc-strings.org | 10 | ||||
| -rw-r--r-- | doc/concepts/expressions.org | 22 | ||||
| -rw-r--r-- | doc/concepts/multi-repo.org | 14 | ||||
| -rw-r--r-- | doc/concepts/overview.org | 2 | ||||
| -rw-r--r-- | doc/concepts/rules.org | 28 | ||||
| -rw-r--r-- | doc/concepts/target-cache.org | 8 |
9 files changed, 55 insertions, 55 deletions
diff --git a/doc/concepts/anonymous-targets.org b/doc/concepts/anonymous-targets.org index 5e9079e2..98d194c7 100644 --- a/doc/concepts/anonymous-targets.org +++ b/doc/concepts/anonymous-targets.org @@ -8,7 +8,7 @@ from which APIs for various languages can be generated. As protocol buffers can contain other protocol buffers, the description files themselves have a dependency structure. -From a software-engeneering point of view, the challenge is to +From a software-engineering point of view, the challenge is to ensure that the author of the description files does not have to be aware of the languages for which APIs will be generated later. In fact, the main benefit of the language-independent description @@ -32,7 +32,7 @@ dependencies; as those targets will have an appropriate notion of equality, no duplicate work is done and hence, as a side effect, staging or symbol conflicts are avoided as well. -** Prelimanary remark: action identifiers +** Preliminary remark: action identifiers Actions are defined as Merkle-tree hash of the contents. As all components (input tree, list of output strings, command vector, @@ -46,7 +46,7 @@ long as the values for all duplicate keys are equal). When constructing the action graph for traversal, we can drop duplicates (i.e., actions with the same identifier, and hence the same description). For the serialization of the graph as part of -the analyse command, we can afford the preperatory step to compute +the analyse command, we can afford the preparatory step to compute a map from action id to list of origins. ** Equality @@ -203,7 +203,7 @@ As a graph node can only be defined with all data given, the defined dependency structure is cycle-free by construction. However, the tree unfolding will usually be exponentially larger. For internal handling, this is not a problem: our shared-pointer implementation -can efficently represent a directed acyclic graph and since we +can efficiently represent a directed acyclic graph and since we cache hashes in expressions, we can compute the overall hash without folding the structure to a tree. When presenting nodes to the user, we only show the map of identifier to definition, to avoid that @@ -255,7 +255,7 @@ the abstract node-type specifying strings to rule names. So, in the implementation these are just two expression pointers (with their defined notion of equality, i.e., equality of the respective Merkle-tree hashes). Such a pair of pointers also forms an additional -variant of a name value, refering to such an anonymous target. +variant of a name value, referring to such an anonymous target. It should be noted that such an anonymous target contains all the information needed to evaluate it in the same way as a regular (named) @@ -269,7 +269,7 @@ We keep the property that a user can only request named targets. So anonymous targets have to be requested by other targets. We also keep the property that other targets are only requested at certain fixed steps in the evaluation of a target. To still achieve -a meaningful use of anonymous targets our rule language hanldes +a meaningful use of anonymous targets our rule language handles anonymous targets in the following way. ***** Rules parameter ~"anonymous"~ @@ -319,8 +319,8 @@ The evaluation of a target defined by a user-defined rule is handled as follows. After the target fields are evaluated as usual, an additional step is carried out. -For each anymous-target field, i.e., for each key in the ~"anonymous"~ -map, a list of anymous targets is generated from the corresponding +For each anonymous-target field, i.e., for each key in the ~"anonymous"~ +map, a list of anonymous targets is generated from the corresponding value: take all targets from the specified ~"target"~ field in all their specified configuration transitions (they have already been evaluated) and take the values provided for the specified ~"provider"~ diff --git a/doc/concepts/built-in-rules.org b/doc/concepts/built-in-rules.org index 117761fc..9463b10c 100644 --- a/doc/concepts/built-in-rules.org +++ b/doc/concepts/built-in-rules.org @@ -77,7 +77,7 @@ map. Any provided information of the dependencies is discarded. The ~"generic"~ rules allows to define artifacts as the output of an action. This is mainly useful for ad-hoc constructions; for -anything occuring more often, a proper user-defined rule is usually +anything occurring more often, a proper user-defined rule is usually the better choice. The ~"deps"~ argument is evaluated and has to evaluate to a list @@ -132,7 +132,7 @@ and artifacts are overlayed in an artifacts-win fashion and the union of the resulting stages is taken; it is an error if conflicts arise in this way. The resulting stage is transformed into a tree. Both, artifacts and runfiles of the ~"tree"~ target are a singleton map -with the key the result of evaluting ~"name"~ (which has to evalutate to +with the key the result of evaluating ~"name"~ (which has to evaluate to a single string) and value that tree. @@ -158,7 +158,7 @@ to the project. In any case, when using non-internal targets as dependencies (i.e., targets that a caller of the ~"configure"~ potentially might use as well), care should be taken that those are only used in the initial configuration. Such preservation of -the configuraiton is necessary to avoid conflicts, if the targets +the configuration is necessary to avoid conflicts, if the targets depended upon are visible in the ~"configure"~ target itself, e.g., as link dependency (which almost always happens when depending on a library). Even if a non-internal target depended upon is not visible diff --git a/doc/concepts/cache-pragma.org b/doc/concepts/cache-pragma.org index 3d445257..11953702 100644 --- a/doc/concepts/cache-pragma.org +++ b/doc/concepts/cache-pragma.org @@ -49,7 +49,7 @@ To make everybody aware of their special nature, they are clearly marked as such: tainted targets not generated by a tainted rule (e.g., a test rule) have to explicitly state their taintedness in their attributes. This declaration also gives a natural way to mark targets -that are techincally pure, but still should be used only in test, +that are technically pure, but still should be used only in test, e.g., a mock version of a larger library. Besides being for tests only, there might be other reasons why a @@ -79,7 +79,7 @@ report the set of strings the target is tainted with. *** ~"may_fail"~ and ~"no_cache"~ properties of ~"ACTION"~ -The ~"ACTION"~ function in the definining expression of a rule +The ~"ACTION"~ function in the defining expression of a rule have two additional (besides inputs, etc) parameters ~"may_fail"~ and ~"no_cache"~. Those are not evaluated and have to be lists of strings (with empty assumed if the respective parameter is not diff --git a/doc/concepts/doc-strings.org b/doc/concepts/doc-strings.org index 00ecea27..e82cef2b 100644 --- a/doc/concepts/doc-strings.org +++ b/doc/concepts/doc-strings.org @@ -13,7 +13,7 @@ we add documentation directly into the respective definitions. ** Multi-line strings in JSON In JSON, the newline character is encoded specially and not taken -literally; also, there is not implict joining of string literals. +literally; also, there is not implicit joining of string literals. So, in order to also have documentation readable in the JSON representation itself, instead of single strings, we take arrays of strings, with the understanding that they describe the strings @@ -24,7 +24,7 @@ obtained by joining the entries with newline characters. While documentation is highly recommended, it still remains optional. Therefore, when in the following we state that a key is for a list or a map, it is always implied that it may be absent; in this case, -the empy array or the empty map is taken as default, respectively. +the empty array or the empty map is taken as default, respectively. ** Rules @@ -55,14 +55,14 @@ documentation on the provided data. , "" , "Define a library that can be used to be statically linked to a" , "binary. To do so, the target can simply be specified in the deps" - , "field of a binary; it can also be a dependecy of another library" + , "field of a binary; it can also be a dependency of another library" , "and the information is then propagated to the corresponding binary." ] , "string_fields": ["name"] , "target_fields": ["srcs", "hdrs", "private-hdrs", "deps"] , "field_doc": { "name": - ["The base name of the libary (i.e., the name without the leading lib)."] + ["The base name of the library (i.e., the name without the leading lib)."] , "srcs": ["The source files (i.e., *.c files) of the library."] , "hdrs": [ "The public header files of this library. Targets depending on" @@ -122,7 +122,7 @@ As export targets play the role of interfaces between repositories, it is important that they be documented as well. Again, export targets are described as a JSON object with fixed set of keys amd we use the keys ~doc~ and ~config_doc~ for documentation. Here ~doc~ is an -array of strings describing the targted in general and ~config_doc~ +array of strings describing the targeted in general and ~config_doc~ is a map from (some of) the variables of the ~flexible_config~ to an array of strings describing this parameter. diff --git a/doc/concepts/expressions.org b/doc/concepts/expressions.org index d5d3340c..2d10d9ff 100644 --- a/doc/concepts/expressions.org +++ b/doc/concepts/expressions.org @@ -8,7 +8,7 @@ our expression language. All expressions are given by JSON values. One can think of expressions as abstract syntax trees serialized to JSON; nevertheless, the precise -semantics is given by the evaluation mechanism decribed later. +semantics is given by the evaluation mechanism described later. ** Semantic Values @@ -41,8 +41,8 @@ mechanism; the precise evaluation is as follows. - For JSON objects (wich can be understood as maps, or dicts), the key ~"type"~ has be be present and has to be a literal string. That string determines the syntactical construct (sloppily also - referred to as "function") the object represents, and the remaning - evaluation depends on the syntactial construct. The syntactical + referred to as "function") the object represents, and the remaining + evaluation depends on the syntactical construct. The syntactical construct has to be either one of the built-in ones or a special function available in the given context (e.g., ~"ACTION"~ within the expression defining a rule). @@ -75,11 +75,11 @@ a literal string. For each pair in ~"bindings"~ the second component is evaluated, in the order the pairs occur. After each evaluation, a new environment -is taken for the subesequent evaluations; the new environment is +is taken for the subsequent evaluations; the new environment is like the old one but amended at the position given by the first component of the pair to now map to the value just obtained. -Finally, the ~"body"~ is evaluated in the final environemnt (after +Finally, the ~"body"~ is evaluated in the final environment (after evaluating all binding entries) and the result of evaluating the ~"body"~ is the value for the whole ~"let*"~ expression. @@ -132,10 +132,10 @@ expression. If the key ~"case"~ is present, it has to be a list of pairs. In this case, the key ~"expr"~ is evaluated. It is an error if that evaluates -to a name-containg value. The result of that evaluation +to a name-containing value. The result of that evaluation is sequentially compared to the evaluation of the first components of the ~"case"~ list until an equal value is found. In this case, -the evalaution of the second component of the pair is the value of +the evaluation of the second component of the pair is the value of the ~"case*"~ expression. If the ~"case"~ key is absent, or no equality is found, the result of @@ -154,7 +154,7 @@ evaluates to ~true~. For disjunction, the evaluation mechanism is the same, but the truth values and connective are taken dually. So, ~"and"~ and ~"or"~ are -logical conjunction and disjuction, respectively, using short-cut +logical conjunction and disjunction, respectively, using short-cut evaluation if syntactically admissible (i.e., if the argument is syntactically a list). @@ -192,7 +192,7 @@ last value obtained. **** Regular functions -First ~"$1"~ is evaluated; for binary functions ~"$2"~ is evaluted +First ~"$1"~ is evaluated; for binary functions ~"$2"~ is evaluated next. For functions that accept keyword arguments, those are evaluated as well. Finally the function is applied to this (or those) argument(s) to obtain the final result. @@ -202,7 +202,7 @@ those) argument(s) to obtain the final result. - ~"nub_right"~ The argument has to be a list. It is an error if that list contains (directly or indirectly) a name. The result is the input list, except that for all duplicate values, all but the - rightmost occurence is removed. + rightmost occurrence is removed. - ~"basename"~ The argument has to be a string. This string is interpreted as a path, and the file name thereof is returned. @@ -322,7 +322,7 @@ reported together with a stack trace. This, however, might not be the most informative way to present a problem to the user, especially if the underlying problem is a proper user error, e.g., in rule usage (leaving out mandatory arguments, violating semantical -prerequisits, etc). To allow proper error reporting, the following +prerequisites, etc). To allow proper error reporting, the following functions are available. All of them have an optional argument ~"msg"~ that is evaluated (only) in case of error and the result of that evaluation included in the error message presented to the user. diff --git a/doc/concepts/multi-repo.org b/doc/concepts/multi-repo.org index c0f7df15..f1ad736f 100644 --- a/doc/concepts/multi-repo.org +++ b/doc/concepts/multi-repo.org @@ -13,7 +13,7 @@ this repository as a function of the referenced external targets. *** Binding in a separate repository configuration The actual binding of the free repository names is specified in a -separte repository-configuration file, which is specified on the +separate repository-configuration file, which is specified on the command line (via the ~-C~ option); this command-line argument is optional and the default is that the repository worked on has no external dependencies. Typically (but not necessarily), this @@ -31,14 +31,14 @@ of the repository worked upon. Additional roots file names (for target, rule, and expression) can be specified. For keys not given, the same rules for default values apply as for the corresponding command-line arguments. Additionally, for each repository, the -key "bindings" specifies the map of the open respository names to +key "bindings" specifies the map of the open repository names to the global names that provide these dependencies. Repositories may depend on each other (or even themselves), but the resulting global target graph has to be cycle free. Whenever a location has to be specified, the value has to be a list, with the first entry being specifying the naming scheme; the -semantics of the remaning entries depends on the scheme (see "Root +semantics of the remaining entries depends on the scheme (see "Root Naming Schemes" below). Additionally, the key ~"main"~ (with default ~""~) specifies @@ -92,7 +92,7 @@ In the following, we assume it is located at ~/etc/just/repos.json~. } #+END_SRC -It specifes 3 repositories, with global names ~foobar~, ~barimpl~, +It specifies 3 repositories, with global names ~foobar~, ~barimpl~, and ~env~. Within ~foobar~, the repository name ~base~ refers to ~barimpl~, the repository that can be found at ~/opt/barimpl~. @@ -100,7 +100,7 @@ The repository ~env~ is the main repository and there is no workspace root defined for it, so it only provides bindings for external repositories ~foo~ and ~bar~, but the actual repository is taken from the working directory (unless ~-w~ is specified). In this way, -it provides an environment for developping applications based on +it provides an environment for developing applications based on ~foo~ and ~bar~. For example, the invocation ~just build -C /etc/just/repos.conf @@ -115,9 +115,9 @@ taking ~base~ refer to the repository at ~/opt/barimpl~) and *** Reference in target files In addition to the normal target references (string for a target in -the name module, moudle-target pair for a target in same repository, +the name module, module-target pair for a target in same repository, ~["./", relpath, target]~ relative addressing, ~["FILE", null, -name]~ explicit file refence in the same moudle), references of the +name]~ explicit file reference in the same module), references of the form ~["@", repo, module, target]~ can be specified, where ~repo~ is string referring to an open name. That open repository name is resolved to the global name by the ~"bindings"~ parameter of the diff --git a/doc/concepts/overview.org b/doc/concepts/overview.org index a7230066..5dc7ad20 100644 --- a/doc/concepts/overview.org +++ b/doc/concepts/overview.org @@ -122,7 +122,7 @@ rule, or expression is expected, they use the same naming scheme. all other names given by lists have length at least 3. - A list ~["./", relative-module-path, name]~ refers to a target with the given name in the module that has the specified path - relative to the current moudle (in the current repository). + relative to the current module (in the current repository). - A list ~["@", repository, module, name]~ refers to the target with the specified name in the specified module of the specified repository. diff --git a/doc/concepts/rules.org b/doc/concepts/rules.org index ad31ae71..d4c61b5e 100644 --- a/doc/concepts/rules.org +++ b/doc/concepts/rules.org @@ -68,7 +68,7 @@ declared as ~"target_fields"~ or as ~"implicit"~) to a configuration expression. Here, a configuration expression is any expression in our language. It has access to the ~"config_vars"~ and the ~"config_fields"~ and has to evaluate to a list of maps. Each map -specifies a transition to the current configuration by ammending +specifies a transition to the current configuration by amending it on the domain of that map to the given value. *** ~"imports"~ @@ -82,7 +82,7 @@ Expressions themselves are defined in expression files, the default name being ~EXPRESSIONS~. Each expression is a JSON object. The only mandatory key is -~"expression"~ wich has to be an expression in our language. It +~"expression"~ which has to be an expression in our language. It optionally can have a key ~"vars"~ where the value has to be a list of strings (and the default is the empty list). Additionally, it can have another optional key ~"imports"~ following the same scheme @@ -109,8 +109,8 @@ expect names as inputs. **** ~DEP_ARTIFACTS~ and ~DEP_RUNFILES~ -These functions give access to the artifacts, or runfiles, respecitively, -of one of the targets depended upon. It takes two (evalutated) +These functions give access to the artifacts, or runfiles, respectively, +of one of the targets depended upon. It takes two (evaluated) arguments, the mandatory ~"dep"~ and the optional ~"transition"~. The argument ~"dep"~ has to evaluate to an abstract name (as can be @@ -130,7 +130,7 @@ is the mandatory argument ~"provider"~ which has to evaluate to a string. The function returns the value of the provides map of the target at the given provider. If the key is not in the provides map (or the value at that key is ~null~), the optional argument -~"default"~ is evaluted and returned. The default for ~"default"~ +~"default"~ is evaluated and returned. The default for ~"default"~ is the empty list. **** ~BLOB~ @@ -208,14 +208,14 @@ be the result of the evaluation of the defining expression of a target. This function takes one mandatory argument ~"name"~ which is unevaluated; it has to a be a string literal. The expression imported by that name through the imports field is evaluated in the current -enviroment restricted to the variables of that expression. The result +environment restricted to the variables of that expression. The result of that evaluation is the result of the ~CALL_EXPRESSION~ statement. -During the evaluation of an expression, rule fields can stil be +During the evaluation of an expression, rule fields can still be accessed through the functions ~FIELD~, ~DEP_ARTIFACTS~, etc. In particular, even an expression with no variables (that, hence, is always evaluated in the empty environment) can carry out non-trivial -compuations and be non-constant. The special functions ~BLOB~, +computations and be non-constant. The special functions ~BLOB~, ~ACTION~, and ~RESULT~ are also available. If inside the evaluation of an expression the function ~CALL_EXPRESSION~ is used, the name argument refers to the ~"imports"~ map of that expression. So the @@ -248,7 +248,7 @@ following way. effectively has used of the configuration the variables used by the ~arguments_config~ in the rule invocation, the ~config_vars~ the rule specified, and the parts of the configuration used by - a target dependend upon. For a target dependend upon, all parts + a target dependent upon. For a target dependent upon, all parts it used of its configuration are relevant expect for those fixed by the configuration transition. @@ -258,7 +258,7 @@ following way. ** Example of developing a rule Let's consider step by step an example of writing a rule. Say we want -to write a rule that programatically patches some files. +to write a rule that programmatically patches some files. *** Framework: The minimal rule @@ -281,7 +281,7 @@ strings. In the defining expression we can access them directly via the ~FIELD~ function. Strings can be used when defining maps, but we can also create artifacts from them, using the ~BLOB~ function. To create a map, we can use the ~singleton_map~ function. We define -values step by setp, using the ~let*~ construct. +values step by step, using the ~let*~ construct. #+BEGIN_SRC { "script only": @@ -327,7 +327,7 @@ with ~foreach_map~. Next, we have to keep in mind that targets may place their artifacts at arbitrary logical locations. For us that means that first -we have to make a decission at which logical locations we want +we have to make a decision at which logical locations we want to place the output artifacts. As one thinks of patching as an in-place operation, we chose to logically place the outputs where the inputs have been. Of course, we do not modify the input files @@ -451,7 +451,7 @@ A typical invocation of that rule would be a target file like the following. } #+END_SRC As the input file has the same name as a target (in the same module), -we use the explict file reference in the specification of the sources. +we use the explicit file reference in the specification of the sources. *** Implicit dependencies and config transitions @@ -462,7 +462,7 @@ generator. Then we have to do some additional considerations. on the targets the user specifies. Additionally, our code generator is also an implicit dependency. And as it is under active development, we certainly do not want it to be taken from - the ambient build environment (as we did in the previous exmaple + the ambient build environment (as we did in the previous example with ~ed~ which, however, is a pretty stable tool). So we use an ~implicit~ target for this. - Next, we notice that our code generator is used during the diff --git a/doc/concepts/target-cache.org b/doc/concepts/target-cache.org index dccbd5e7..591a66af 100644 --- a/doc/concepts/target-cache.org +++ b/doc/concepts/target-cache.org @@ -61,7 +61,7 @@ Additionally, repositories can reach additional repositories via bindings. Moreover, this repository-level dependency relation is not necessarily cycle free. In particular, we cannot use the tree unfolding as canonical representation of that graph up to -bisumlation, as we do with most other data structures. To still get +bisimulation, as we do with most other data structures. To still get a canonical representation, we factor out the largest bisimulation, i.e., minimize the respective automaton (with repositories as states, local data as locally observable properties, and the binding @@ -74,7 +74,7 @@ edges are traversed in lexicographical order. The entry point is hence recognisable as repository ~"0"~. The repository key content-identifier of the canonically formatted -canonical serialisaiton of the JSON encoding of the obtain +canonical serialisation of the JSON encoding of the obtain multi-repository configuration (with repository-free git-root descriptions). The serialisation itself is stored in CAS. @@ -131,7 +131,7 @@ for caching. An export target is then fully described by - the target name of the export target within that repository, described as module-name pair, and - the effective configuration. -More precisely, the canoncical description is the JSON object with +More precisely, the canonical description is the JSON object with those values for the keys ~"repo_key"~, ~"target_name"~, and ~"effective_config"~, respectively. The repository key is the blob identifier of the canonical serialisation (including sorted keys, etc) of the just @@ -214,6 +214,6 @@ used through the same export target. For a well-structured repository, this should not be a natural property anyway. The forwarding of artifacts are the reason we chose that in the -non-cached anlysis of an export target the artifacts are passed on +non-cached analysis of an export target the artifacts are passed on as received and are not wrapped in an "add to cache" action. The latter choice would violate that projection property we rely upon. |