diff options
| -rw-r--r-- | share/man/just-graph-file.5.md | 152 | ||||
| -rw-r--r-- | share/man/just-graph-file.5.org | 147 | ||||
| -rw-r--r-- | share/man/just-import-git.1.md | 80 | ||||
| -rw-r--r-- | share/man/just-import-git.1.org | 81 | ||||
| -rw-r--r-- | share/man/just-mr-repository-config.5.md | 196 | ||||
| -rw-r--r-- | share/man/just-mr-repository-config.5.org | 182 | ||||
| -rw-r--r-- | share/man/just-mr.1.md | 259 | ||||
| -rw-r--r-- | share/man/just-mr.1.org | 230 | ||||
| -rw-r--r-- | share/man/just-mrrc.5.md | 127 | ||||
| -rw-r--r-- | share/man/just-mrrc.5.org | 118 | ||||
| -rw-r--r-- | share/man/just-repository-config.5.md | 106 | ||||
| -rw-r--r-- | share/man/just-repository-config.5.org | 91 | ||||
| -rw-r--r-- | share/man/just.1.md | 670 | ||||
| -rw-r--r-- | share/man/just.1.org | 631 |
14 files changed, 1590 insertions, 1480 deletions
diff --git a/share/man/just-graph-file.5.md b/share/man/just-graph-file.5.md new file mode 100644 index 00000000..66c3f8ae --- /dev/null +++ b/share/man/just-graph-file.5.md @@ -0,0 +1,152 @@ +% JUST GRAPH FILE(5) | File Formats Manual + +NAME +==== + +just graph file -- The format of the action graph used by **just(1)** + +DESCRIPTION +=========== + +The file is read as JSON. Any other serialization describing the same +JSON object is equivalent. We assume, that in JSON objects, each key +occurs at most once; it is implementation defined how repetitions of the +same key are treated. + +Artifacts and their serialization +--------------------------------- + +There are four different kind of artifacts. The serialization of the +artifact is always a JSON object with two keys: `"type"` and `"data"`. +The value for `"type"` is always on of the strings `"LOCAL"`, `"KNOWN"`, +`"ACTION"`, or `"TREE"`. The value for `"data"` is a JSON object with +keys depending on which type the artifact is of. + + - `"LOCAL"` artifacts refer to source files in a logical repository. + The describing data are + - the `"repository"`, given as its global name, and + - the `"path"`, given as path relative to the root of that + repository. + - `"KNOWN"` artifacts are described by the hash of their content. The + describing data are + - the `"file_type"`, which is a one-letter string, + - `"f"` for regular, non-executable files, + - `"x"` for executable files, or + - `"t"` for trees. + - the `"id"` specifying the (applicable) hash of the file given as + its hexadecimal encoding, a string, and + - the `"size"` of the artifact, a number, in bytes. + - `"ACTION"` artifacts are the outputs of actions. The defining data + are + - the `"id"`, a string with the name of the action, and + - the `"path"`, specifying the path of this output artifact, + relative to the root of the action directory + - `"TREE"` artifacts refer to trees defined in the action graph. The + defining data are + - the `"id"`, a string with the name of the tree. + +Actions and their serialization +------------------------------- + +Actions are given by the data described in the following sections. For +each item a key is associated and the serialization of the action is a +JSON object mapping those keys to the respective serialization of the +values. For some data items default values are given; if the value for +the respective item equals the default, the respective key-value pair +may be omitted in the serialization. + + - `"command"` specifies the command to be executed. It is a non-empty + list of strings that forms the argument vector; the first entry is + taken as program. This key is mandatory. + + - `"env"` specifies the environment variables the command should be + executed with. It is given as map from strings to strings. The + default is the empty map. + + - `"input"` describes the files available to the action. The action + must not modify them in any way. They are specified as map from + paths to artifacts (the latter serialized as described). Paths have + to be relative paths and are taken relative to the working directory + of the action. The default is the empty map. + + - `"output"` describes the files the action is supposed to generate, + if any. It is given as a list of strings, each specifying a file + name by a path relative to the working directory of the action. The + default is the empty list. However, every action has to produce some + form of output, so if `"output"` is empty, `"output_dirs"` cannot be + empty. + + - `"output_dirs"` describes the directory output of the action, if + any. It is given as a list of strings, each specifying the a + directory name by a path relative to the working directory of the + action. The `"output_dirs"` may also specify directories from which + individual files are specified as `"output"`. The default value for + `"output_dirs"` is the empty list. However, every action to produce + some form of output, so if `"output_dirs"` is empty, `"output"` + cannot be empty. + + - `"may_fail"` can either be `null` or a string. If it is a string, + the build should be continued, even if that action returns a + non-zero exit state. If the action returns a non-zero exit code, + that string should be shown to the user in a suitable way (e.g., + printing on the console). Otherwise (i.e., if no `"may_fail"` string + is given), the build should be aborted if the action returns a + non-zero exit code. The default for `"may_fail"` is `null`, i.e., + abort on non-zero exit code. + + - `"no_cache"` is a boolean. If `true`, the action should never be + cached, not even on success. The default is `false`. + +The graph format +---------------- + +The action graph is given by a JSON object. + + - The value for the key `"blobs"` is a list of strings. Those strings + should be considered known; they might (additionally to what was + agreed ahead of time as known) referred to as `"KNOWN"` artifacts. + + - The value for the key `"trees"` is a JSON object, mapping the names + of trees to their definition. The definition of a tree is JSON + object mapping paths to artifacts (serialized in the way described + earlier). The paths are always interpreted as relative paths, + relative to the root of the tree. It is not a requirement that a new + tree is defined for every subdirectory; if a path contains the + hierarchy separator, which is slash, then implicitly a subdirectory + is present, and all path going through that subdirectory contribute + to its content. It is, however, an error, if the a path is a prefix + of another one (with the comparison done in the canonical form of + that path). + + - The value for the key `"actions"` is a JSON object, mapping names of + actions to their respective definition (serialized as JSON). + +Additional keys +--------------- + +Any JSON object described here might have additional keys on top of the +ones described. Implementations reading the graph have to accept and +ignore those. Implementations writing action-graph files should be aware +that a future version of this file format might give a specific meaning +to those extra keys. + +Graphs written by **just(1)** have the additional key `"origins"` in +each action. The value is a list of all places where this action was +requested (so often, but not always, the list has length 1). Each such +place is described by a JSON object with the following keys. + + - `"target"` The target in which the action was requested. It is given + as a list, either a full qualified named target given as `"@"` + followed by global repository name, module, and target name, or an + anonymous target, given by `"#"` followed by a hash of the rule + binding and the node name. + - `"subtask"` The running number, starting from `0`, of the action, as + given by the (deterministic) evaluation order of he defining + expression for the rule that defined the target. + - `"config"` The effective configuration for that target, a JSON + object. + +See also +======== + +**just(1)** diff --git a/share/man/just-graph-file.5.org b/share/man/just-graph-file.5.org deleted file mode 100644 index 5fed6466..00000000 --- a/share/man/just-graph-file.5.org +++ /dev/null @@ -1,147 +0,0 @@ -#+TITLE: JUST GRAPH FILE -#+MAN_CLASS_OPTIONS: :section-id "5" - -* NAME - -just graph file -- The format of the action graph used by *just(1)* - -* DESCRIPTION - -The file is read as JSON. Any other serialization describing the -same JSON object is equivalent. We assume, that in JSON objects, -each key occurs at most once; it is implementation defined how -repetitions of the same key are treated. - -** Artifacts and their serialization - -There are four different kind of artifacts. The serialization of -the artifact is always a JSON object with two keys: ~"type"~ and -~"data"~. The value for ~"type"~ is always on of the strings ~"LOCAL"~, -~"KNOWN"~, ~"ACTION"~, or ~"TREE"~. The value for ~"data"~ is a -JSON object with keys depending on which type the artifact is of. - -- ~"LOCAL"~ artifacts refer to source files in a logical repository. - The describing data are - - the ~"repository"~, given as its global name, and - - the ~"path"~, given as path relative to the root of that - repository. - -- ~"KNOWN"~ artifacts are described by the hash of their content. - The describing data are - - the ~"file_type"~, which is a one-letter string, - - ~"f"~ for regular, non-executable files, - - ~"x"~ for executable files, or - - ~"t"~ for trees. - - the ~"id"~ specifying the (applicable) hash of the file given - as its hexadecimal encoding, a string, and - - the ~"size"~ of the artifact, a number, in bytes. - -- ~"ACTION"~ artifacts are the outputs of actions. The defining data are - - the ~"id"~, a string with the name of the action, and - - the ~"path"~, specifying the path of this output artifact, - relative to the root of the action directory - -- ~"TREE"~ artifacts refer to trees defined in the action graph. - The defining data are - - the ~"id"~, a string with the name of the tree. - -** Actions and their serialization - -Actions are given by the data described in the following sections. -For each item a key is associated and the serialization of the action -is a JSON object mapping those keys to the respective serialization -of the values. For some data items default values are given; if the -value for the respective item equals the default, the respective -key-value pair may be omitted in the serialization. - -- ~"command"~ specifies the command to be executed. It is a non-empty - list of strings that forms the argument vector; the first entry - is taken as program. This key is mandatory. - -- ~"env"~ specifies the environment variables the command should - be executed with. It is given as map from strings to strings. - The default is the empty map. - -- ~"input"~ describes the files available to the action. The action - must not modify them in any way. They are specified as map from - paths to artifacts (the latter serialized as described). Paths - have to be relative paths and are taken relative to the working - directory of the action. The default is the empty map. - -- ~"output"~ describes the files the action is supposed to generate, - if any. It is given as a list of strings, each specifying a file - name by a path relative to the working directory of the action. - The default is the empty list. However, every action has to produce - some form of output, so if ~"output"~ is empty, ~"output_dirs"~ - cannot be empty. - -- ~"output_dirs"~ describes the directory output of the action, - if any. It is given as a list of strings, each specifying the - a directory name by a path relative to the working directory of - the action. The ~"output_dirs"~ may also specify directories from - which individual files are specified as ~"output"~. The default - value for ~"output_dirs"~ is the empty list. However, every action - to produce some form of output, so if ~"output_dirs"~ is empty, - ~"output"~ cannot be empty. - -- ~"may_fail"~ can either be ~null~ or a string. If it is a string, - the build should be continued, even if that action returns a - non-zero exit state. If the action returns a non-zero exit code, - that string should be shown to the user in a suitable way (e.g., - printing on the console). Otherwise (i.e., if no ~"may_fail"~ - string is given), the build should be aborted if the action - returns a non-zero exit code. The default for ~"may_fail"~ is - ~null~, i.e., abort on non-zero exit code. - -- ~"no_cache"~ is a boolean. If ~true~, the action should never be - cached, not even on success. The default is ~false~. - -** The graph format - -The action graph is given by a JSON object. - -- The value for the key ~"blobs"~ is a list of strings. Those strings - should be considered known; they might (additionally to what was - agreed ahead of time as known) referred to as ~"KNOWN"~ artifacts. - -- The value for the key ~"trees"~ is a JSON object, mapping the - names of trees to their definition. The definition of a tree is - JSON object mapping paths to artifacts (serialized in the way - described earlier). The paths are always interpreted as relative - paths, relative to the root of the tree. It is not a requirement - that a new tree is defined for every subdirectory; if a path - contains the hierarchy separator, which is slash, then implicitly - a subdirectory is present, and all path going through that - subdirectory contribute to its content. It is, however, an error, - if the a path is a prefix of another one (with the comparison - done in the canonical form of that path). - -- The value for the key ~"actions"~ is a JSON object, mapping names - of actions to their respective definition (serialized as JSON). - -** Additional keys - -Any JSON object described here might have additional keys on top -of the ones described. Implementations reading the graph have to -accept and ignore those. Implementations writing action-graph files -should be aware that a future version of this file format might -give a specific meaning to those extra keys. - -Graphs written by *just(1)* have the additional key ~"origins"~ -in each action. The value is a list of all places where this action -was requested (so often, but not always, the list has length 1). Each -such place is described by a JSON object with the following keys. -- ~"target"~ The target in which the action was requested. It is - given as a list, either a full qualified named target given as - ~"@"~ followed by global repository name, module, and target - name, or an anonymous target, given by ~"#"~ followed by a hash - of the rule binding and the node name. -- ~"subtask"~ The running number, starting from ~0~, of the action, - as given by the (deterministic) evaluation order of he defining - expression for the rule that defined the target. -- ~"config"~ The effective configuration for that target, a - JSON object. - -* See also - -*just(1)* diff --git a/share/man/just-import-git.1.md b/share/man/just-import-git.1.md new file mode 100644 index 00000000..4af210f3 --- /dev/null +++ b/share/man/just-import-git.1.md @@ -0,0 +1,80 @@ +% JUST-import-git(1) | General Commands Manual + +NAME +==== + +just-import-git - import one git repository to a multi-repository +configuration + +SYNOPSIS +======== + +just-import-deps \[OPTIONS\] URL \[foreign repository name\] + +DESCRIPTION +=========== + +Extend an existing **just-mr-repository-config(5)** by adding one git +repository. In doing so, the dependencies declared in the imported +repository are added as well and `"file"` repositories are transformed +to `"subdir"` parts of the imported repository. This solves the problem, +that a repository can refer to itself only as `"."` in a portable way. +The importing party, however, always knows the URL it is importing from. + +The imported repositories are renamed in a way that no conflicts with +already present repositories arise. The repositories pulled in as +dependencies are named in a way to remind for which repositories they +came as a dependency. This renaming is taken into account at all places +repositories are referred to, i.e., the `"bindings"` field, as well as +roots defined by reference to other repositories. + +Only the main parts of repositories are imported (`"repository"`, +`"bindings"`, names, and roots). The `"pragma"` part, as well as unknown +fields are dropped. + +The repository to import is specified by its URL + +The resulting configuration is printed on standard output. + +OPTIONS +======= + +**--as** NAME +Specify the name the imported repository should have in the final +configuration. If not specified, default to the name the repository has +in the configuration file of the repository imported. In any case, the +name is amended if it conflicts with an already existing name. + +**-b** BRANCH +The branch in the imported repository to use; this branch is also +recorded as the branch to follow. Defaults to `"master"`. + +**-C** CONFIGFILE +Use the specified file as the configuration to import into. The string +`-` is treated as a request to take the config from stdin; so a file +called `-` has to be described as `./-`, or similar. If not specified, +for a config file is searched in the same way, as `just-mr` does, when +invoved with `--norc`. + +**-h**, **--help** +Output a usage message and exit. + +**--map** THEIRS OURS +Map repositories from the imported configuration to already existing +ones. Those repositories are not imported (and the search for their +transitive dependency is omitted) and instead the specified already +existing repository is used. This is useful, if a sufficiently +compatible repository already exists in the configuration. + +**-R** RELPATH +Use the file, specified by path relative to the repository root, as +multi-repository specification in the imported repository. If not +specifed, for a config file is searched in the same way as `just-mr` +does, when invoked with `--no-rc`, however leaving out searches relative +to global roots (`"home"` and `"system"`). In other words, `repos.json` +and `etc/repos.json` are tried if this option is not given. + +See also +======== + +**just-mr-repository-config(5)**, **just-mr(1)** diff --git a/share/man/just-import-git.1.org b/share/man/just-import-git.1.org deleted file mode 100644 index c2d5c6f9..00000000 --- a/share/man/just-import-git.1.org +++ /dev/null @@ -1,81 +0,0 @@ -#+TITLE: JUST-import-git -#+MAN_CLASS_OPTIONS: :section-id "1" - -* NAME - -just-import-git - import one git repository to a multi-repository configuration - -* SYNOPSIS - -just-import-deps [OPTIONS] URL [foreign repository name] - -* DESCRIPTION - -Extend an existing *just-mr-repository-config(5)* by adding one -git repository. In doing so, the dependencies declared in the -imported repository are added as well and ~"file"~ repositories -are transformed to ~"subdir"~ parts of the imported repository. -This solves the problem, that a repository can refer to itself only -as ~"."~ in a portable way. The importing party, however, always -knows the URL it is importing from. - -The imported repositories are renamed in a way that no conflicts -with already present repositories arise. The repositories pulled in -as dependencies are named in a way to remind for which repositories -they came as a dependency. This renaming is taken into account at -all places repositories are referred to, i.e., the ~"bindings"~ -field, as well as roots defined by reference to other repositories. - -Only the main parts of repositories are imported (~"repository"~, -~"bindings"~, names, and roots). The ~"pragma"~ part, as well as -unknown fields are dropped. - -The repository to import is specified by its URL - -The resulting configuration is printed on standard output. - - -* OPTIONS - - *--as* NAME\\ - Specify the name the imported repository should have in the - final configuration. If not specified, default to the name - the repository has in the configuration file of the repository - imported. In any case, the name is amended if it conflicts - with an already existing name. - - *-b* BRANCH\\ - The branch in the imported repository to use; this branch is - also recorded as the branch to follow. Defaults to ~"master"~. - - *-C* CONFIGFILE\\ - Use the specified file as the configuration to import into. - The string ~-~ is treated as a request to take the config from - stdin; so a file called ~-~ has to be described as ~./-~, or similar. - If not specified, for a config file is searched in the same - way, as ~just-mr~ does, when invoved with ~--norc~. - - *-h*, *--help* \\ - Output a usage message and exit. - - *--map* THEIRS OURS\\ - Map repositories from the imported configuration to already - existing ones. Those repositories are not imported (and the - search for their transitive dependency is omitted) and instead - the specified already existing repository is used. This is - useful, if a sufficiently compatible repository already exists - in the configuration. - - *-R* RELPATH\\ - Use the file, specified by path relative to the repository - root, as multi-repository specification in the imported - repository. If not specifed, for a config file is searched - in the same way as ~just-mr~ does, when invoked with ~--no-rc~, - however leaving out searches relative to global roots (~"home"~ - and ~"system"~). In other words, ~repos.json~ and ~etc/repos.json~ - are tried if this option is not given. - - -* See also - -*just-mr-repository-config(5)*, *just-mr(1)* diff --git a/share/man/just-mr-repository-config.5.md b/share/man/just-mr-repository-config.5.md new file mode 100644 index 00000000..25b4bb6c --- /dev/null +++ b/share/man/just-mr-repository-config.5.md @@ -0,0 +1,196 @@ +% JUST-MR REPOSITORY CONFIG(5) | File Formats Manual + +NAME +==== + +just-mr repository config -- The format of the repository config used by +**just-mr(1)** + +DESCRIPTION +=========== + +In order for the **just-mr(1)** tool to generate a repository +configuration file usable by the **just(1)** multi-repository build +system, it requires a configuration file describing repositories and +their dependencies. + +The file is read as JSON. Any other serialization describing the same +JSON object is equivalent. It is assumed that in JSON objects keys occur +at most once; it is implementation defined how repetitions of the same +key are treated. + +Workspace root description +-------------------------- + +A repository's *workspace root description* provides information about +the location of source files. It can be an explicit description, given +as a JSON object, or an implicit one, given as the global name of +another repository, from which the workspace root can be inferred. + +Explicit workspace roots can be of several types, distinguishable by the +value of the key `"type"` in the JSON object. Depending on this value, +other fields in the object are also supported. + +### `"file"` + +It defines as workspace root a directory on the file system. + +The following fields are supported: + + - `"path"` provides the root directory containing the source files. + This entry is mandatory. + +### `"archive"` / `"zip"` + +They define as workspace root a remote archive. The only difference +between the two types is the nature of the archive: a compressed tarball +in the case of `"archive"`, or a compressed zip file in the case of +`"zip"`. + +The following fields are supported: + + - `"content"` provides the git blob hash of the archive file. This has + to be specified in hex encoding. This entry is mandatory. + + - `"fetch"` specifies the URL to the remote archive. This entry is + mandatory. + + - `"distfile"` provides an alternative name for the archive file. This + entry is optional. If missing, the basename of the fetch URL is + used. + + - `"sha256"`, + + - `"sha512"` provide optional checksum hashes in order to verify the + integrity of the remote site archive. These have to be provided in + hex encoding. These checks are only performed if the archive file is + actually downloaded from the (potentially untrusted) network and not + already available locally. + + - `"subdir"` specifies the subdirectory withing the unpacked archive. + This entry is optional. If missing, the root directory of the + archive is used. + +### `"git"` + +It defines as workspace root a part of a Git repository. + +The following fields are supported: + + - `"repository"` provides the URL of the Git repository. This entry is + mandatory. + + - `"commit"` contains the commit hash. This has to be specified in hex + encoding. This entry is mandatory. + + - `"branch"` provides the branch name, with the promise that it + contains the aforementioned commit. This entry is mandatory. + + - `"subdir"` specifies the subdirectory containing the distribution + files. This entry is optional. If missing, the root directory of the + Git repository is used. + +### `"git tree"` + +It defines as workspace root a known Git tree obtainable by a generic +command. + +The following fields are supported: + + - `"id"` provides the Git tree identifier. This entry is mandatory. + + - `"cmd"` provides a list of strings forming a command which promises + that, when executed in an empty directory (anywhere in the file + system), creates in that directory a directory structure containing + the promised Git tree (either top-level or in some subdirectory). + This entry is mandatory. + + - `"env"` provides a map of envariables to be set for executing the + command. + +### `"distdir"` + +It defines as workspace root a directory with the distribution archives +of the specified repositories. Usually this root is realized as a Git +tree in the Git repository in `just`'s local build root. + +The following fields are supported: + + - `"repositories"` provides a list of global names of repositories. + This entry is mandatory. + +### Additional keys + +The key `"pragma"` is reserved for type-specific repository directives +which alter the workspace root. It is given as a JSON object. The +different workspace roots might support different keys for this object; +unsupported keys are always ignored. + +For a `"file"` workspace root, the pragma key `"to_git"` is supported. +If its value is `"true"`, it indicates that the workspace root should be +returned as a Git tree. If the root directory is already part of a Git +repository, its Git tree identifier is used; otherwise, the workspace +root will be realized as a Git tree in the Git repository in `just`'s +local build root. + +Repository description +---------------------- + +A *repository description* is defined as a JSON object, containing a +*workspace root description*, directory roots and names for targets, +rules, and expressions files, and bindings to other repositories. + +Specifically, the following fields are supported: + + - `"repository"` contains a *workspace root description*. This entry + is mandatory. + + - `"target_root"`, + + - `"rule_root"`, + + - `"expression_root"` define the root directories for the targets, + rules, and expressions, respectively. If provided, they are passed + on expanded to the workspace root of the repository named by their + value. + + - `"target_file_name"`, + + - `"rule_file_name"`, + + - `"expression_file_name"` refer to the name of the files containing + the targets, rules, and expressions, respectively, located relative + to the corresponding root directories. These entries are optional. + If provided, they are passed on as-is. + + - `"bindings"` provides a JSON object defining dependencies on other + repositories. The object's keys are strings defining local + repository names, while the values are the corresponding global + names of those repositories. If provided, this entry is passed on + as-is. + +Repository configuration format +------------------------------- + +The repository configuration format is structured as a JSON object. The +following fields are supported: + + - `"main"` contains a JSON string that determines which of the + provided repositories is considered the main repository. + + - `"repositories"` contains a JSON object, where each key is the + global name of a repository and its corresponding value is the + *repository description*. + +Additional keys +--------------- + +Any JSON object described in this format might have additional keys +besides the ones mentioned. The current strategy of **just-mr(1)** is to +accept and ignore them. Users should be aware that future versions of +this format might give specific meanings to these extra keys. + +See also +======== + +**just(1)**, **just-mr(1)**, **just-repository-config(5)** diff --git a/share/man/just-mr-repository-config.5.org b/share/man/just-mr-repository-config.5.org deleted file mode 100644 index 8fd9a032..00000000 --- a/share/man/just-mr-repository-config.5.org +++ /dev/null @@ -1,182 +0,0 @@ -#+TITLE: JUST-MR REPOSITORY CONFIG -#+MAN_CLASS_OPTIONS: :section-id "5" - -* NAME - -just-mr repository config --- The format of the repository config used by *just-mr(1)* - -* DESCRIPTION - -In order for the *just-mr(1)* tool to generate a repository -configuration file usable by the *just(1)* multi-repository build system, -it requires a configuration file describing repositories -and their dependencies. - -The file is read as JSON. Any other serialization describing -the same JSON object is equivalent. It is assumed that in JSON -objects keys occur at most once; it is implementation defined -how repetitions of the same key are treated. - -** Workspace root description - -A repository's /workspace root description/ provides information about -the location of source files. It can be an explicit description, -given as a JSON object, or an implicit one, given as the global name -of another repository, from which the workspace root can be inferred. - -Explicit workspace roots can be of several types, distinguishable -by the value of the key ~"type"~ in the JSON object. -Depending on this value, other fields in the object are also supported. - -*** ~"file"~ - -It defines as workspace root a directory on the file system. - -The following fields are supported: - -- ~"path"~ provides the root directory containing the source files. - This entry is mandatory. - -*** ~"archive"~ / ~"zip"~ - -They define as workspace root a remote archive. -The only difference between the two types is the nature of the archive: -a compressed tarball in the case of ~"archive"~, -or a compressed zip file in the case of ~"zip"~. - -The following fields are supported: - -- ~"content"~ provides the git blob hash of the archive file. - This has to be specified in hex encoding. This entry is mandatory. - -- ~"fetch"~ specifies the URL to the remote archive. - This entry is mandatory. - -- ~"distfile"~ provides an alternative name for the archive file. - This entry is optional. If missing, the basename of the fetch URL is used. - -- ~"sha256"~, -- ~"sha512"~ provide optional checksum hashes in order to verify - the integrity of the remote site archive. - These have to be provided in hex encoding. - These checks are only performed if the archive file is actually downloaded - from the (potentially untrusted) network and not already available locally. - -- ~"subdir"~ specifies the subdirectory withing the unpacked archive. - This entry is optional. If missing, the root directory of the archive is used. - -*** ~"git"~ - -It defines as workspace root a part of a Git repository. - -The following fields are supported: - -- ~"repository"~ provides the URL of the Git repository. - This entry is mandatory. - -- ~"commit"~ contains the commit hash. - This has to be specified in hex encoding. This entry is mandatory. - -- ~"branch"~ provides the branch name, with the promise that it - contains the aforementioned commit. This entry is mandatory. - -- ~"subdir"~ specifies the subdirectory containing the distribution files. - This entry is optional. If missing, the root directory of the Git repository - is used. - -*** ~"git tree"~ - -It defines as workspace root a known Git tree obtainable by a generic command. - -The following fields are supported: - -- ~"id"~ provides the Git tree identifier. - This entry is mandatory. - -- ~"cmd"~ provides a list of strings forming a command which promises that, when - executed in an empty directory (anywhere in the file system), creates in that - directory a directory structure containing the promised Git tree (either - top-level or in some subdirectory). - This entry is mandatory. - -- ~"env"~ provides a map of envariables to be set for executing the command. - -*** ~"distdir"~ - -It defines as workspace root a directory with the distribution archives -of the specified repositories. Usually this root is realized as a Git tree -in the Git repository in ~just~'s local build root. - -The following fields are supported: - -- ~"repositories"~ provides a list of global names of repositories. - This entry is mandatory. - -*** Additional keys - -The key ~"pragma"~ is reserved for type-specific repository -directives which alter the workspace root. It is given as a JSON object. -The different workspace roots might support different keys for this object; -unsupported keys are always ignored. - -For a ~"file"~ workspace root, the pragma key ~"to_git"~ is supported. -If its value is ~"true"~, it indicates that the workspace root should be -returned as a Git tree. If the root directory is already part of a Git repository, -its Git tree identifier is used; otherwise, the workspace root will be realized -as a Git tree in the Git repository in ~just~'s local build root. - -** Repository description - -A /repository description/ is defined as a JSON object, -containing a /workspace root description/, directory roots and names -for targets, rules, and expressions files, -and bindings to other repositories. - -Specifically, the following fields are supported: - -- ~"repository"~ contains a /workspace root description/. - This entry is mandatory. - -- ~"target_root"~, -- ~"rule_root"~, -- ~"expression_root"~ define the root directories for the targets, - rules, and expressions, respectively. - If provided, they are passed on expanded to the workspace root - of the repository named by their value. - -- ~"target_file_name"~, -- ~"rule_file_name"~, -- ~"expression_file_name"~ refer to the name of the files containing - the targets, rules, and expressions, respectively, - located relative to the corresponding root directories. - These entries are optional. If provided, they are passed on as-is. - -- ~"bindings"~ provides a JSON object defining dependencies on other - repositories. The object's keys are strings defining local repository names, - while the values are the corresponding global names of those repositories. - If provided, this entry is passed on as-is. - -** Repository configuration format - -The repository configuration format is structured as a JSON -object. The following fields are supported: - -- ~"main"~ contains a JSON string that determines which of the provided - repositories is considered the main repository. - -- ~"repositories"~ contains a JSON object, where each key is the - global name of a repository and its corresponding value is the - /repository description/. - -** Additional keys - -Any JSON object described in this format might have additional keys -besides the ones mentioned. -The current strategy of *just-mr(1)* is to accept and ignore them. -Users should be aware that future versions of this format might give -specific meanings to these extra keys. - -* See also - -*just(1)*, *just-mr(1)*, *just-repository-config(5)* diff --git a/share/man/just-mr.1.md b/share/man/just-mr.1.md new file mode 100644 index 00000000..90d6c3f8 --- /dev/null +++ b/share/man/just-mr.1.md @@ -0,0 +1,259 @@ +% JUST-MR(1) | General Commands Manual + +NAME +==== + +just-mr - multi-repository configuration tool and launcher for +**just(1)**. + +SYNOPSIS +======== + +just-mr \[OPTIONS\] mrversion +just-mr \[OPTIONS\] {setup|setup-env} \[--all\] \[main-repo\] +just-mr \[OPTIONS\] fetch \[--all\] \[-o fetch-dir\] \[main-repo\] +just-mr \[OPTIONS\] update \[repo...\] +just-mr \[OPTIONS\] do \[JUST ARGS\] +just-mr \[OPTIONS\] +{version|analyse|build|install|install-cas|describe|rebuild} +\[JUST ARGS\] + +DESCRIPTION +=========== + +Just-MR is a configuration tool for the multi-repository Just build +system. It can be used both standalone and as a launcher for `just`. + +The tool performs specific operations, based on the invoked subcommand, +on repositories described in a configuration file. All subcommands +operate at the level of *workspace roots* deduced from the given +repository descriptions. See **just-mr-repository-config(5)** for more +details on the input format. + +OPTIONS +======= + +General options +--------------- + +**-h**, **--help** Output a usage message and exit. + +**-C**, **--repository-config** PATH +Path to the multi-repository configuration file. See +**just-mr-repository-config(5)** for more details. If no configuration +file is \*specified, `just-mr` will look for one in the following +order: + + - `$WORKSPACE_ROOT/repos.json` (workspace of the `just-mr` invocation) + - `$WORKSPACE_ROOT/etc/repos.json` (workspace of the `just-mr` + invocation) + - `$HOME/.just-repos.json` + - `/etc/just-repos.json` + +The default configuration lookup order can be adjusted in the just-mrrc +file. See **just-mrrc(5)** for more details. + +**-D**, **--defines** JSON +Defines, via an in-line JSON object, an overlay configuration for +**just(1)**; if used as a launcher for a subcommand known to support +**--defines**, this defines value is forwarded, otherwise it is ignored. +If **-D** is given several times, the **-D** options overlay (in the +sense of `map_union`) in the order they are given on the command line. + +**--local-build-root** PATH +Root for local CAS, cache, and build directories. The path will be +created if it does not exist already. This option overwrites any values +set in the **just-mrrc(5)** file. +Default: path `".cache/just"` in user's home directory. + +**--checkout-locations** PATH +Specification file for checkout locations. This file contains a JSON +object, for which under the key `"<version control>"` of key +`"checkouts"` we get pairs of repository URLs as keys and absolute paths +as values. Currently supported version control is Git, therefore the +respective key is `"git"`. The paths contained for each repository URL +point to existing locations on the filesystem containing the checkout of +the respective repository. This options overwrites any values set in the +**just-mrrc(5)** file. +Default: file path `".just-local.json"` in user's home directory. + +**-L**, **--local-launcher** JSON_ARRAY +JSON array with the list of strings representing the launcher to prepend +actions' commands before being executed locally. +Default: `["env", "--"]`. + +**--distdir** PATH +Directory to look for distfiles before fetching. If given, this will be +the first place distfiles are looked for. This option can be given +multiple times to specify a list of distribution directories that are +used for lookup in the order they appear on the command line. +Directories specified via this option will be appended to the ones set +in the **just-mrrc(5)** file. +Default: the single file path `".distfiles"` in user's home directory. + +**--main** NAME +The repository to take the target from. +**-f,--log-file** PATH +Path to local log file. `just-mr` will store the information printed on +stderr in the log file along with the thread id and timestamp when the +output has been generated. + +**--log-limit** NUM +Log limit (higher is more verbose) in interval \[0,6\] (Default: 3). + +**--plain-log** +Do not use ANSI escape sequences to highlight messages. + +**--log-append** +Append messages to log file instead of overwriting existing. + +**--no-fetch-ssl-verify** +Disable the default peer SSL certificate verification step when fetching +archives (for which we verify the hash anyway) from remote. + +**--fetch-cacert** PATH +Path to the CA certificate bundle containing one or more certificates to +be used to peer verify archive fetches from remote. + +**--just** PATH +Name of the just binary in `PATH` or path to the just binary. +Default: `"just"`. + +**--rc** PATH +Path to the just-mrrc file to use. See **just-mrrc(5)** for more +details. +Default: file path `".just-mrrc"` in the user's home directory. + +**--git** PATH +Path to the git binary in `PATH` or path to the git binary. Used in the +rare instances when shelling out to git is needed. +Default: `"git"`. + +**--norc** +Option to prevent reading any **just-mrrc(5)** file. + +SUBCOMMANDS +=========== + +mrversion +--------- + +Print on stdout a JSON object providing version information for this +tool itself; the `version` subcommand calls the `version` subcommand of +just. The version information for just-mr is in the same format that +also `just` uses. + +setup|setup-env +---------------- + +These subcommands fetch all required repositories and generate an +appropriate multi-repository `just` configuration file. The resulting +file is stored in CAS and its path is printed to stdout. See +**just-repository-config(5)** for more details on the resulting +configuration file format. + +If a main repository is provided in the input configuration or on +command line, only it and its dependencies are considered in the +generation of the resulting multi-repository configuration file. If no +main repository is provided, the lexicographical first repository from +the configuration is used. To perform the setup for all repositories +from the input configuration file, use the `--all` flag. + +The behavior of the two subcommands differs only with respect to the +main repository. In the case of `setup-env`, the workspace root of the +main repository is left out, such that it can be deduced from the +working directory when `just` is invoked. In this way, working on a +checkout of that repository is possible, while having all of its +dependencies properly set up. In the case of `setup`, the workspace root +of the main repository is taken as-is into the output configuration +file. + +fetch +----- + +This subcommand prepares all archive-type workspace roots for an offline +build by fetching all their required source files from the specified +locations given in the input configuration file. Any subsequent +`just-mr` or `just` invocations containing fetched archive workspace +roots will thus need no further network connections. + +If a main repository is provided in the input configuration or on +command line, only it and its dependencies are considered for fetching. +If no main repository is provided, the lexicographical first repository +from the configuration is used. To perform the fetch for all +repositories from the input configuration file, use the `--all` flag. + +By default the first existing distribution directory is used as the +output directory for writing the fetched archives on disk. If no +existing distribution directory can be found an error is produced. To +define an output directory that is independent of the given distribution +directories, use the `-o` option. + +update +------ + +This subcommand updates the specified repositories (possibly none) and +prints the resulting updated configuration file to stdout. + +Currently, `just-mr` can only update Git repositories and it will fail +if a different repository type is given. The tool also fails if any of +the given repository names are not found in the configuration file. + +For Git repositories, the subcommand will replace the value for the +`"commit"` field with the commit hash (as a string) found in the remote +repository in the specified branch. The output configuration file will +otherwise remain the same at the JSON level with the input configuration +file. + +do +-- + +This subcommand is used as the canonical way of specifying just +arguments and calling `just` via **execvp(2)**. Any subsequent argument +is unconditionally forwarded to `just`. For *known* subcommands +(version, describe, analyse, build, install, install-cas, rebuild), the +`just-mr setup` step is performed first for those commands accepting a +configuration and the produced configuration is prefixed to the provided +arguments. The main repository for the `setup` step can be provided in +the configuration or on the command line. If no main repository is +provided, the lexicographical first repository from the configuration is +used. + +All logging arguments given to `just-mr` are passed to `just` as early +arguments. If log files are provided, an unconditional `--log-append` +argument is passed as well, which ensures no log messages will get +overwritten. + +The `--local-launcher` argument is passed to `just` as early argument +for those *known* subcommands that accept it (build, install, rebuild). + +version|describe|analyse|build|install|install-cas|rebuild|gc +-------------------------------------------------------------------- + +This subcommand is the explicit way of specifying *known* just +subcommands and calling `just` via **execvp(2)**. The same description +as for the `do` subcommand applies. + +EXIT STATUS +=========== + +The exit status of `just-mr` is one of the following values: + + - 0: the command completed successfully + - 64: setup succeeded, but exec failed + - 65: any unspecified error occurred in just-mr + - 66: unknown subcommand + - 67: error parsing the command-line arguments + - 68: error parsing the configuration + - 69: error during fetch + - 70: error during update + - 71: error during setup + +Any other exit code that does not have bit 64 set is a status value from +`just`, if `just-mr` is used as a launcher. See **just(1)** for more +details. + +See also +======== + +**just(1)** diff --git a/share/man/just-mr.1.org b/share/man/just-mr.1.org deleted file mode 100644 index 70de96e2..00000000 --- a/share/man/just-mr.1.org +++ /dev/null @@ -1,230 +0,0 @@ -#+TITLE: JUST-MR -#+MAN_CLASS_OPTIONS: :section-id "1" - -* NAME - -just-mr - multi-repository configuration tool and launcher for *just(1)*. - -* SYNOPSIS - -just-mr [OPTIONS] mrversion\\ -just-mr [OPTIONS] {setup|setup-env} [--all] [main-repo]\\ -just-mr [OPTIONS] fetch [--all] [-o fetch-dir] [main-repo]\\ -just-mr [OPTIONS] update [repo...]\\ -just-mr [OPTIONS] do [JUST ARGS]\\ -just-mr [OPTIONS] {version|analyse|build|install|install-cas|describe|rebuild} [JUST ARGS]\\ - -* DESCRIPTION - -Just-MR is a configuration tool for the multi-repository Just build system. It -can be used both standalone and as a launcher for ~just~. - -The tool performs specific operations, based on the invoked subcommand, on -repositories described in a configuration file. All subcommands operate at the -level of /workspace roots/ deduced from the given repository descriptions. -See *just-mr-repository-config(5)* for more details on the input format. - -* OPTIONS - -** General options - - *-h*, *--help* - Output a usage message and exit.\\ - - *-C*, *--repository-config* PATH\\ - Path to the multi-repository configuration file. See - *just-mr-repository-config(5)* for more details. If no configuration file is - *specified, ~just-mr~ will look for one in the following order:\\ - - ~$WORKSPACE_ROOT/repos.json~ (workspace of the ~just-mr~ invocation) - - ~$WORKSPACE_ROOT/etc/repos.json~ (workspace of the ~just-mr~ invocation) - - ~$HOME/.just-repos.json~ - - ~/etc/just-repos.json~ - The default configuration lookup order can be adjusted in the just-mrrc file. - See *just-mrrc(5)* for more details. - - *-D*, *--defines* JSON\\ - Defines, via an in-line JSON object, an overlay configuration - for *just(1)*; if used as a launcher for a subcommand known - to support *--defines*, this defines value is forwarded, - otherwise it is ignored. If *-D* is given several times, - the *-D* options overlay (in the sense of ~map_union~) in - the order they are given on the command line. - - *--local-build-root* PATH\\ - Root for local CAS, cache, and build directories. The path will be - created if it does not exist already. This option overwrites any values set - in the *just-mrrc(5)* file.\\ - Default: path ~".cache/just"~ in user's home directory. - - *--checkout-locations* PATH\\ - Specification file for checkout locations. This file contains a JSON object, - for which under the key ~"<version control>"~ of key ~"checkouts"~ we get - pairs of repository URLs as keys and absolute paths as values. Currently - supported version control is Git, therefore the respective key is ~"git"~. - The paths contained for each repository URL point to existing locations on - the filesystem containing the checkout of the respective repository. This - options overwrites any values set in the *just-mrrc(5)* file.\\ - Default: file path ~".just-local.json"~ in user's home directory. - - *-L*, *--local-launcher* <JSON_ARRAY>\\ - JSON array with the list of strings representing the launcher to - prepend actions' commands before being executed locally.\\ - Default: ~["env", "--"]~. - - *--distdir* PATH\\ - Directory to look for distfiles before fetching. If given, this will be the - first place distfiles are looked for. This option can be given multiple times - to specify a list of distribution directories that are used for lookup in the - order they appear on the command line. Directories specified via this option - will be appended to the ones set in the *just-mrrc(5)* file.\\ - Default: the single file path ~".distfiles"~ in user's home directory. - - *--main* NAME\\ - The repository to take the target from.\\ - - *-f,--log-file* PATH\\ - Path to local log file. ~just-mr~ will store the information printed - on stderr in the log file along with the thread id and timestamp - when the output has been generated. - - *--log-limit* NUM\\ - Log limit (higher is more verbose) in interval [0,6] (Default: 3). - - *--plain-log*\\ - Do not use ANSI escape sequences to highlight messages. - - *--log-append*\\ - Append messages to log file instead of overwriting existing. - - *--no-fetch-ssl-verify*\\ - Disable the default peer SSL certificate verification step when fetching - archives (for which we verify the hash anyway) from remote. - - *--fetch-cacert* PATH\\ - Path to the CA certificate bundle containing one or more certificates to be - used to peer verify archive fetches from remote. - - *--just* PATH\\ - Name of the just binary in ~PATH~ or path to the just binary.\\ - Default: ~"just"~.\\ - - *--rc* PATH\\ - Path to the just-mrrc file to use. See *just-mrrc(5)* for more details.\\ - Default: file path ~".just-mrrc"~ in the user's home directory. - - *--git* PATH\\ - Path to the git binary in ~PATH~ or path to the git binary. Used in the rare - instances when shelling out to git is needed.\\ - Default: ~"git"~.\\ - - *--norc*\\ - Option to prevent reading any *just-mrrc(5)* file. - -* SUBCOMMANDS - -** mrversion - -Print on stdout a JSON object providing version information for -this tool itself; the ~version~ subcommand calls the ~version~ -subcommand of just. The version information for just-mr is in the -same format that also ~just~ uses. - -** setup|setup-env - -These subcommands fetch all required repositories and generate an appropriate -multi-repository ~just~ configuration file. The resulting file is stored in CAS -and its path is printed to stdout. See *just-repository-config(5)* for more -details on the resulting configuration file format. - -If a main repository is provided in the input configuration or on command line, -only it and its dependencies are considered in the generation of the resulting -multi-repository configuration file. If no main repository is provided, the -lexicographical first repository from the configuration is used. To perform the -setup for all repositories from the input configuration file, use the ~--all~ -flag. - -The behavior of the two subcommands differs only with respect to the main -repository. In the case of ~setup-env~, the workspace root of the main -repository is left out, such that it can be deduced from the working directory -when ~just~ is invoked. In this way, working on a checkout of that repository is -possible, while having all of its dependencies properly set up. In the case of -~setup~, the workspace root of the main repository is taken as-is into the -output configuration file. - -** fetch - -This subcommand prepares all archive-type workspace roots for an offline build -by fetching all their required source files from the specified locations -given in the input configuration file. Any subsequent ~just-mr~ or ~just~ -invocations containing fetched archive workspace roots will thus need no further -network connections. - -If a main repository is provided in the input configuration or on command line, -only it and its dependencies are considered for fetching. If no main repository -is provided, the lexicographical first repository from the configuration is -used. To perform the fetch for all repositories from the input configuration -file, use the ~--all~ flag. - -By default the first existing distribution directory is used as the output -directory for writing the fetched archives on disk. If no existing distribution -directory can be found an error is produced. To define an output directory that -is independent of the given distribution directories, use the ~-o~ option. - -** update - -This subcommand updates the specified repositories (possibly none) and prints -the resulting updated configuration file to stdout. - -Currently, ~just-mr~ can only update Git repositories and it will fail if a -different repository type is given. The tool also fails if any of the given -repository names are not found in the configuration file. - -For Git repositories, the subcommand will replace the value for the ~"commit"~ -field with the commit hash (as a string) found in the remote repository in the -specified branch. The output configuration file will otherwise remain the same -at the JSON level with the input configuration file. - -** do - -This subcommand is used as the canonical way of specifying just arguments and -calling ~just~ via *execvp(2)*. Any subsequent argument is unconditionally -forwarded to ~just~. For /known/ subcommands (version, describe, analyse, build, -install, install-cas, rebuild), the ~just-mr setup~ step is performed first for -those commands accepting a configuration and the produced configuration is -prefixed to the provided arguments. The main repository for the ~setup~ step can -be provided in the configuration or on the command line. If no main repository -is provided, the lexicographical first repository from the configuration is -used. - -All logging arguments given to ~just-mr~ are passed to ~just~ as early arguments. -If log files are provided, an unconditional ~--log-append~ argument is passed as -well, which ensures no log messages will get overwritten. - -The ~--local-launcher~ argument is passed to ~just~ as early argument for those -/known/ subcommands that accept it (build, install, rebuild). - -** version|describe|analyse|build|install|install-cas|rebuild|gc - -This subcommand is the explicit way of specifying /known/ just subcommands and -calling ~just~ via *execvp(2)*. The same description as for the ~do~ subcommand -applies. - -* EXIT STATUS - -The exit status of ~just-mr~ is one of the following values: - - 0: the command completed successfully - - 64: setup succeeded, but exec failed - - 65: any unspecified error occurred in just-mr - - 66: unknown subcommand - - 67: error parsing the command-line arguments - - 68: error parsing the configuration - - 69: error during fetch - - 70: error during update - - 71: error during setup - -Any other exit code that does not have bit 64 set is a status value from ~just~, -if ~just-mr~ is used as a launcher. See *just(1)* for more details. - -* See also - -*just(1)* diff --git a/share/man/just-mrrc.5.md b/share/man/just-mrrc.5.md new file mode 100644 index 00000000..c94f9a69 --- /dev/null +++ b/share/man/just-mrrc.5.md @@ -0,0 +1,127 @@ +% JUST-MRRC(5) | File Formats Manual + +NAME +==== + +just-mr configuration -- The format of the configuration used by +**just-mr(1)** + +DESCRIPTION +=========== + +The file is read as JSON. Any other serialization describing the same +JSON object is equivalent. We assume, that in JSON objects, each key +occurs at most once; it is implementation defined how repetitions of the +same key are treated. + +Location objects +---------------- + +A *location* is a JSON object with the keys `"root"`, `"path"`, and +`"base"`. + +The value for key `"root"` is either `"workspace"`, `"home"`, or +`"system"`, which have the following meanings: + + - `"workspace"` refers to the root of the workspace in which the + `just-mr` invocation was issued (not the workspace of the requested + main repository). This location root is ignored if `just-mr` was not + invoked from inside a workspace. + + - `"home"` refers to the user's home directory. + + - `"system"` refers to the system root `/`. + +The value for key `"path"` is the relative path of the item to locate +within the location root. + +The value for key `"base"` is a relative path within the location root. +This path is only relevant for locations of config files. If such a +config file contains relative paths, those will be resolved relative to +the specified base. If omitted, the default value `.` is used. + +The just-mrrc format +-------------------- + +The just-mrrc is given by a JSON object. + + - The value for the key `"config lookup order"` is a JSON list of + location objects, specifying where to look for multi-repository + configurations (see **just-mr-repository-config(5)** for more + detail). The lookup is performed in the same order the location + objects appear in the list. + + - The value for the key `"local build root"` is a single location + object, specifying the path to use as the local build root. For more + details, see **just-mr(1)**. + + - The value for the key `"checkout locations"` is a single location + object, specifying the path to the file for checkout locations. For + more details, see **just-mr(1)**. + + - The value for the key `"distdirs"` is a JSON list of location + objects, specifying where to look for distribution files (usually + collected via the subcommand `fetch`). The lookup is performed in + the same order the location objects appear in the list. For more + details, see **just-mr(1)**. + + - The value for the key `"just"` is a single location object, + specifying the path to the `just` binary to use for execution, if + `just-mr` is used as a launcher. + + - The value for the key `"git"` is a single location object, + specifying the path to the git binary to use in the instances when + `just-mr` needs to shell out. + + - The value for the key `"local launcher"`, if given, is list of + strings setting the default for local launcher for `just-mr`; + command-line arguments take precedence over the value in the + configuration file. If the key `"local launcher"` is absent, the + default `["env", "--"]` is assumed. + + - The value for the key `"log limit"`, if given, sets the default + value for the log limit, that can be overridden by the command-line + options. + + - The value `"log files"`, if given, has to be a list of location + objects, specifying additional log files, on top of those specified + on the command line. + + - The value for the key `"just args"` is a JSON object. Its keys are + `just` subcommands and its value is a JSON list of strings. For the + corresponding subcommand, these strings are prefixed to the `just` + argument vector, if `just-mr` is used as a launcher. + +EXAMPLE +======= + +An example just-mrrc file could look like the following: + +``` jsonc +{ "config lookup order": + [ {"root": "workspace", "path": "repos.json"} + , {"root": "workspace", "path": "etc/repos.json"} + , {"root": "home", "path": ".just-repos.json"} + , {"root": "system", "path": "etc/just-repos.json"} + ] +, "local build root": {"root": "home", "path": ".cache/just"} +, "checkout locations": {"root": "home", "path": ".just-local.json"} +, "local launcher": ["env", "--"] +, "log limit": 4 +, "log files": [{"root": "home", "path": ".log/just/latest-invocation"}] +, "distdirs": [{"root": "home", "path": ".distfiles"}] +, "just": {"root": "system", "path": "usr/bin/just"} +, "git": {"root": "system", "path": "usr/bin/git"} +, "just args": + { "build": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] + , "install": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] + , "rebuild": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] + , "install-cas": ["-r", "10.0.0.1:8980"] + } +} +``` + +See also +======== + +**just-mr(1)**, **just-mr-repository-config(5)** diff --git a/share/man/just-mrrc.5.org b/share/man/just-mrrc.5.org deleted file mode 100644 index ab93d939..00000000 --- a/share/man/just-mrrc.5.org +++ /dev/null @@ -1,118 +0,0 @@ -#+TITLE: JUST-MRRC -#+MAN_CLASS_OPTIONS: :section-id "5" - -* NAME - -just-mr configuration -- The format of the configuration used by *just-mr(1)* - -* DESCRIPTION - -The file is read as JSON. Any other serialization describing the -same JSON object is equivalent. We assume, that in JSON objects, -each key occurs at most once; it is implementation defined how -repetitions of the same key are treated. - -** Location objects - -A /location/ is a JSON object with the keys ~"root"~, ~"path"~, and ~"base"~. - -The value for key ~"root"~ is either ~"workspace"~, ~"home"~, or ~"system"~, -which have the following meanings: - -- ~"workspace"~ refers to the root of the workspace in which the ~just-mr~ - invocation was issued (not the workspace of the requested main repository). - This location root is ignored if ~just-mr~ was not invoked from inside a - workspace. - -- ~"home"~ refers to the user's home directory. - -- ~"system"~ refers to the system root ~/~. - -The value for key ~"path"~ is the relative path of the item to locate within -the location root. - -The value for key ~"base"~ is a relative path within the location root. This -path is only relevant for locations of config files. If such a config file -contains relative paths, those will be resolved relative to the specified base. -If omitted, the default value ~.~ is used. - -** The just-mrrc format - -The just-mrrc is given by a JSON object. - -- The value for the key ~"config lookup order"~ is a JSON list of location - objects, specifying where to look for multi-repository configurations (see - *just-mr-repository-config(5)* for more detail). The lookup is performed in - the same order the location objects appear in the list. - -- The value for the key ~"local build root"~ is a single location object, - specifying the path to use as the local build root. For more details, see - *just-mr(1)*. - -- The value for the key ~"checkout locations"~ is a single location object, - specifying the path to the file for checkout locations. For more details, see - *just-mr(1)*. - -- The value for the key ~"distdirs"~ is a JSON list of location objects, - specifying where to look for distribution files (usually collected via the - subcommand ~fetch~). The lookup is performed in the same order the location - objects appear in the list. For more details, see *just-mr(1)*. - -- The value for the key ~"just"~ is a single location object, specifying the - path to the ~just~ binary to use for execution, if ~just-mr~ is used as a - launcher. - -- The value for the key ~"git"~ is a single location object, specifying the - path to the git binary to use in the instances when ~just-mr~ needs to shell - out. - -- The value for the key ~"local launcher"~, if given, is list of - strings setting the default for local launcher for ~just-mr~; - command-line arguments take precedence over the value in the - configuration file. If the key ~"local launcher"~ is absent, the - default ~["env", "--"]~ is assumed. - -- The value for the key ~"log limit"~, if given, sets the default - value for the log limit, that can be overridden by the command-line - options. - -- The value ~"log files"~, if given, has to be a list of location - objects, specifying additional log files, on top of those specified - on the command line. - -- The value for the key ~"just args"~ is a JSON object. Its keys are ~just~ - subcommands and its value is a JSON list of strings. For the corresponding - subcommand, these strings are prefixed to the ~just~ argument vector, if - ~just-mr~ is used as a launcher. - -* EXAMPLE - -An example just-mrrc file could look like the following: - -#+BEGIN_SRC js -{ "config lookup order": - [ {"root": "workspace", "path": "repos.json"} - , {"root": "workspace", "path": "etc/repos.json"} - , {"root": "home", "path": ".just-repos.json"} - , {"root": "system", "path": "etc/just-repos.json"} - ] -, "local build root": {"root": "home", "path": ".cache/just"} -, "checkout locations": {"root": "home", "path": ".just-local.json"} -, "local launcher": ["env", "--"] -, "log limit": 4 -, "log files": [{"root": "home", "path": ".log/just/latest-invocation"}] -, "distdirs": [{"root": "home", "path": ".distfiles"}] -, "just": {"root": "system", "path": "usr/bin/just"} -, "git": {"root": "system", "path": "usr/bin/git"} -, "just args": - { "build": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] - , "install": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] - , "rebuild": ["-r", "10.0.0.1:8980", "--remote-execution-property", "OS:Linux"] - , "install-cas": ["-r", "10.0.0.1:8980"] - } -} -#+END_SRC - -* See also - -*just-mr(1)*, *just-mr-repository-config(5)* diff --git a/share/man/just-repository-config.5.md b/share/man/just-repository-config.5.md new file mode 100644 index 00000000..e57394e9 --- /dev/null +++ b/share/man/just-repository-config.5.md @@ -0,0 +1,106 @@ +% JUST REPOSITORY CONFIG(5) | File Formats Manual + +NAME +==== + +just repository config -- The format of the repository config used by +**just(1)** + +DESCRIPTION +=========== + +`just`'s repository configuration is read as JSON. Any other +serialization describing the same JSON object is equivalent. We assume, +that in JSON objects, each key occurs at most once; it is implementation +defined how repetitions of the same key are treated. + +File root description +--------------------- + +Each repository can have multiple *file roots*. Each file root is +defined as a non-empty JSON list with its first element being a string, +which determines the type and semantic of the subsequent elements: + + - `"file"` refers to a file root that is located in the file system. + The list has to be of length 2 and the second argument contains the + path to the file root. + + - `"git tree"` refers to a file root that is available as part of a + Git repository. The list has to be of length 3 with the remaining + two elements being: + + 1. The *git tree hash*, which is sufficient to describe the content + of an entire tree including its sub-trees and blobs. The tree + hash has to be specified in hex encoding. + 2. The path to a Git repository on the file system with the promise + that it contains the aforementioned *git tree hash*. + +Repository description +---------------------- + +A single *repository description* is defined as a JSON object, which +contains *file roots*, file names, and bindings to other repositories. +Specifically the following fields are supported: + + - `"workspace_root"` contains the *file root* where source files are + located. If this entry is missing for the main repository, `just` + will perform the normal workspace root resolution starting from the + current working directory. + + - `"target_root"` contains the *file root* where the target files are + located. If this entry is missing, the workspace root is taken. + + - `"target_file_name"` contains the file name of target files to use. + If this entry is missing, the default target file name `TARGETS` is + used. + + - `"rule_root"` contains the *file root* where the rule files are + located. If this entry is missing, the target root is taken. + + - `"rule_file_name"` contains the file name of rule files to use. If + this entry is missing, the default rule file name `RULES` is used. + + - `"expression_root"` contains the *file root* where the expression + files are located. If this entry is missing, the rule root is taken. + + - `"expression_file_name"` contains the file name of expression files + to use. If this entry is missing, the default expression file name + `EXPRESSIONS` is used. + + - `"bindings"` contains a JSON object that defines bindings to other + repositories by mapping local repository names to global ones. The + object's key is local name, while the value is a string + representing the global name. + +Note that any other unsupported field is accepted but ignored. There are +no guarantees that any yet unsupported field may not become meaningful +in future versions. + +Repository configuration format +------------------------------- + +The repository configuration format is a JSON object with the following +keys: + + - `"main"` contains a string, which defines the repository name to + consider by default if not explicitly specified on the command line + (i.e., via `--main`). This entry is optional and if omitted the + empty string is used. + + - `"repositories"` contains a JSON object that defines all + repositories by mapping global repository names to *repository + descriptions* documented above. This entry is optional and if + omitted an empty JSON object is used. + +NOTES +===== + +Although the repository configuration is human-readable and can be +written by hand, in many cases it will be generated by an independent +tool. **just-mr(1)** is one such tool that can be used for configuration +generation, but not necessarily the only one. + +See also +======== + +**just(1)**, **just-mr(1)**, **just-mr-repository-config(5)** diff --git a/share/man/just-repository-config.5.org b/share/man/just-repository-config.5.org deleted file mode 100644 index 941d9a92..00000000 --- a/share/man/just-repository-config.5.org +++ /dev/null @@ -1,91 +0,0 @@ -#+TITLE: JUST REPOSITORY CONFIG -#+MAN_CLASS_OPTIONS: :section-id "5" - -* NAME - -just repository config -- The format of the repository config used by *just(1)* - -* DESCRIPTION - -~just~'s repository configuration is read as JSON. Any other serialization -describing the same JSON object is equivalent. We assume, that in JSON objects, -each key occurs at most once; it is implementation defined how repetitions of -the same key are treated. - -** File root description - -Each repository can have multiple /file roots/. Each file root is defined as a -non-empty JSON list with its first element being a string, which determines the -type and semantic of the subsequent elements: - -- ~"file"~ refers to a file root that is located in the file system. The list - has to be of length 2 and the second argument contains the path to the - file root. - -- ~"git tree"~ refers to a file root that is available as part of a Git - repository. The list has to be of length 3 with the remaining two elements - being: - 1. The /git tree hash/, which is sufficient to describe the content of an - entire tree including its sub-trees and blobs. The tree hash has to be - specified in hex encoding. - 2. The path to a Git repository on the file system with the promise that it - contains the aforementioned /git tree hash/. - -** Repository description - -A single /repository description/ is defined as a JSON object, which contains -/file roots/, file names, and bindings to other repositories. Specifically the -following fields are supported: - -- ~"workspace_root"~ contains the /file root/ where source files are located. If - this entry is missing for the main repository, ~just~ will perform the normal - workspace root resolution starting from the current working directory. - -- ~"target_root"~ contains the /file root/ where the target files are located. - If this entry is missing, the workspace root is taken. - -- ~"target_file_name"~ contains the file name of target files to use. If this - entry is missing, the default target file name ~TARGETS~ is used. - -- ~"rule_root"~ contains the /file root/ where the rule files are located. If - this entry is missing, the target root is taken. - -- ~"rule_file_name"~ contains the file name of rule files to use. If this entry - is missing, the default rule file name ~RULES~ is used. - -- ~"expression_root"~ contains the /file root/ where the expression files are - located. If this entry is missing, the rule root is taken. - -- ~"expression_file_name"~ contains the file name of expression files to use. If - this entry is missing, the default expression file name ~EXPRESSIONS~ is used. - -- ~"bindings"~ contains a JSON object that defines bindings to other - repositories by mapping local repository names to global ones. The object's - key is local name, while the value is a string representing the global name. - -Note that any other unsupported field is accepted but ignored. There are no -guarantees that any yet unsupported field may not become meaningful in future -versions. - -** Repository configuration format - -The repository configuration format is a JSON object with the following keys: - -- ~"main"~ contains a string, which defines the repository name to consider by - default if not explicitly specified on the command line (i.e., via ~--main~). - This entry is optional and if omitted the empty string is used. - -- ~"repositories"~ contains a JSON object that defines all repositories by - mapping global repository names to /repository descriptions/ documented above. - This entry is optional and if omitted an empty JSON object is used. - -* NOTES - -Although the repository configuration is human-readable and can be written by -hand, in many cases it will be generated by an independent tool. *just-mr(1)* is -one such tool that can be used for configuration generation, but not necessarily -the only one. - -* See also - -*just(1)*, *just-mr(1)*, *just-mr-repository-config(5)* diff --git a/share/man/just.1.md b/share/man/just.1.md new file mode 100644 index 00000000..d7968282 --- /dev/null +++ b/share/man/just.1.md @@ -0,0 +1,670 @@ +% JUST(1) | General Commands Manual + +NAME +==== + +just - a generic build tool. + +SYNOPSIS +======== + +just version +just {analyse|build} \[OPTIONS\] \[\[module\] target\] +just install -o OUTPUT_DIR \[OPTIONS\] \[\[module\] target\] +just install-cas \[OPTIONS\] OBJECT_ID +just describe \[OPTIONS\] \[\[module\] target\] +just rebuild \[OPTIONS\] \[\[module\] target\] +just traverse -g GRAPH_FILE -o OUT_DIR \[OPTIONS\] +just gc \[OPTIONS\] +just execute \[OPTIONS\] + +DESCRIPTION +=========== + +Just is a generic multi-repository build system; language-specific +knowledge is described in separate rule files. For every build action, +the relative location of the inputs is independent of their physical +location. This staging allows taking sources from different locations +(logical repositories), including bare git repositories. Targets are +defined using JSON format, in proper files (by default, named +`TARGETS`). Targets are uniquely identified by their name, the +repository, and the module they belong to. A module is the relative path +from the repository target root directory to a subdirectory containing a +target file. + +The module's name of the targets defined at the target root level is +the empty string. Specifying the correct repository, target root, +module, and target name allows to process that target independently of +the current working directory. + +If the module is not specified on the command line, `just` sets the +module corresponding to the current working directory. + +If a target is not specified, the lexicographically-first target, +according to native byte order, is used. So, a target named with an +empty string will always be the default target for that module. + +If a target depends on other targets defined in other modules or +repositories, `just` will recursively visit all and only the required +modules. + +The main repository is the repository containing the target specified on +the command line. The main repository can either be read from the +multi-repository configuration file if it contains the key `main` or +through the option `--main`. The command-line option `--main` overrides +what is eventually read from the multi-repository configuration file. If +neither the multi-repository configuration file contains the `main` key +nor the `--main` option is provided, the lexicographical first +repository from the multi-repository configuration file is used as main. + +The `workspace_root` of the main repository is then defined as follows. +If the option `--workspace-root` is provided, then `workspace_root` is +set accordingly. If the option is not provided, `just` checks if it is +specified within the multi-repository configuration file. If it is, then +it is set accordingly. If not, just starts looking for a marker in the +current directory first, then in all the parent directories until it +finds one. The supported markers are + + - ROOT file (can be empty, content is ignored) + - WORKSPACE (can be empty, content is ignored) + - .git (can be either a file - empty or not, content is ignored - or + the famous directory) + +If it fails, `just` errors out. + +For non-main repositories, the `workspace_root` entry must be declared +in the multi-repository configuration file. + +Afterwards, `target_root`, `rule_root`, and `expression_root` +directories for the main repository are set using the following +strategy. If the corresponding command-line option is specified, then it +is honored. Otherwise, it is read from the multi-repo configuration +file. If it is not specified there, the default value is used. The +default value of `target_root` is `workspace_root`, of `rule_root` is +`target_root`, and of `expression_root` is `rule_root`. + +Finally, the file names where `targets`, `rules`, and `expressions` are +defined for the main repository. If the corresponding key is present in +the multi-repository configuration file, it is set accordingly. If the +user gives the corresponding command-line option, it overwrites what is +eventually read from the configuration file. If they are not explicitly +stated neither within the multi-repository configuration file nor on the +command line, the default values are used, which are `TARGETS`, `RULES`, +and `EXPRESSIONS`, respectively. + +For non-main repositories (i.e., repositories defining targets required +by the target given on the command line), `target_root`, `rule_root`, +`expression_root`, and file names of targets, rules and expressions, if +different from the default values, must be declared in the +multi-repository configuration file. + +SUBCOMMANDS +=========== + +version +------- + +Print on stdout a JSON object providing version information about the +version of the tool used. This JSON object will contain at least the +following keys. + + - `"version"` The version, as a list of numbers of length at least 3, + following the usual convention that version numbers are compared + lexicographically. + - `"suffix"` The version suffix as a string. Generally, suffixes + starting with a `+` symbol are positive offsets to the version, + while suffixes starting with a `~` symbol are negative offsets. + - `"SOURCE_DATE_EPOCH"` Either a number or `null`. If it is a number, + it is the time, in seconds since the epoch, of the last commit that + went into this binary. It is `null` if that time is not known (e.g., + in development builds). + +analyse|build|install +----------------------- + +The subcommands `analyse`, `build`, and `install` are strictly related. +In fact, from left to right, one is a subset of the other. `build` +performs work on top of `analyse`, and `install` on top of `build`. When +a user issues `build`, the `analyse` is called underneath. In +particular, there is no need to run these three subcommands +sequentially. + +### analyse + +`analyse` reads the target graph from TARGETS files for the given +target, computes the action graph (required by e.g., `build`, `install`, +`traverse`), and reports the artifacts, provides, and runfiles of the +analysed target. + +In short, the `analyse` subcommand identifies all the steps required to +build a given target without actually performing those steps. + +This subcommand, issued with proper flags, can dump in JSON format +artifacts, action graph, nodes, actions, (transitive) targets (both +named and anonymous), and trees. + +### build + +This subcommand performs the actions contained in the action graph +computed through the `analyse` phase. + +If building locally, the building process is performed in temporary +separate directories to allow for staging according to the logical path +described in the TARGETS file. Since artifacts are only stored in the +CAS, the user has to use either the `install` or `install-cas` +subcommand to get them. + +`just` allows for both local (i.e., on the same machine where `just` is +used) and remote compilation (i.e., by sending requests over a TCP +connection, e.g., to a different machine, cluster or cloud +infrastructure). In case of a remote compilation, artifacts are compiled +remotely and stored in the remote CAS. `install` and `install-cas` +subcommands can be used to locally fetch and stage the desired +artifacts. + +### install + +The `install` subcommand determines which (if any) actions need to be +(re)done and issues the command to (re)run them. Then, it installs the +artifacts (stored in the local or remote CAS) of the processed target +under the given output-dir (set by option `-o`) honoring the logical +path (aka, staging). If the output path does not exist, it will create +all the necessary folders and subfolders. If files are already present, +they will be overwritten. + +rebuild +------- + +This subcommand inspects if builds are fully reproducible or not (e.g., +time stamps are used). It simply rebuilds and compares artifacts to the +cached build reporting actions with different output. To do so in a +meaningful way, it requires that previous build is already in the cache +(local or remote). + +describe +-------- + +The `describe` subcommand allows for describing the rule generating a +target. The rule is resolved in precisely the same way as during the +analysis. The doc-strings (if any) from the rule definition (if +user-defined) are reported, together with a summary of the declared +fields and their types. The multi-repository configuration is honored in +the same way as during `analyse` and `build`; in particular, the rule +definition can also reside in a git-tree root. + +install-cas +----------- + +`install-cas` fetches artifacts from CAS (Content Addressable Storage) +by means of their object identifier. The canonical format of an object +identifier is `[<hash>:<size>:<type>]`; however, when parsing an object +identifier, `install-cas` uses the following default rules, to make +usage simpler. + + - The square brackets are optional. + - If the size is missing (e.g., because the argument contains no + colon), or cannot be parsed as a number, this is not an error, and + the value `0` is assumed. While this is almost never the correct + size, many CAS implementations, including the local CAS of just + itself, ignore the size for lookups. + - From the type, only the first letter (`f` for non-executable file, + `x` for executable file, and `t` for tree) is significant; the rest + is ignored. If the type is missing (e.g., because the argument + contains less than two colons), or its first letter is not one of + the valid ones, `f` is assumed. + +Depending on whether the output path is set or not, the behavior is +different. + +### Output path is omitted + +If the output path is omitted, it prints the artifact content to stdout +and if the artifact is a tree, it will print a human readable +description. + +### Output path is set + +1. Output path does not exist + + The artifact will be staged to that path. If artifact is a file, the + installed one will have the name of the output path. If the artifact + is a tree, it will create a directory named like the output path, + and will stage all the entries (subtrees included) under that + directory. + +2. Output path exists and it is a directory + + If the artifact is a tree, a directory named with the hash of tree + itself is created under the output path, and all the entries and + subtrees are installed inside the hash-named directory. + + If the artifact is a file, it is installed under the output path and + named according to the hash of the artifact itself. + +3. Output path exists and it is a file + + If the artifact is a file, it will replace the existing file. If the + artifact is a tree, it will cause an error. + +traverse +-------- + +It allows for the building and staging of requested artifacts from a +well-defined graph file. See **just-graph-file(5)** for more details. + +gc +-- + +The **gc** subcommand triggers garbage collection of the local cache. +More precisely, it rotates the cache and CAS generations. During a +build, upon cache hit, everything related to that cache hit is uplinked +to the youngest generation; therefore, upon a call to `gc` everything +not referenced since the last call to `gc` is purged and the +corresponding disk space reclaimed. + +execute +------- + +This subcommand starts a single node remote execution service, honoring +the just native remote protocol. + +If the flag --compatible is provided, the execution service will honor +the original remote build execution protocol. + +OPTIONS +======= + +Generic program information +--------------------------- + +**-h**, **--help** Output a usage message and exit. +Supported by: all subcommands. + +Compatibility options +--------------------- + +**--compatible** +At increased computational effort, be compatible with the original +remote build execution protocol. As the change affects identifiers, the +flag must be used consistently for all related invocations. +Supported by: +analyse|build|install-cas|install|rebuild|traverse|execute. + +Build configuration options +--------------------------- + +**--action-timeout** NUM +Action timeout in seconds. (Default: 300). The timeout is honored only +for the remote build. +Supported by: build|install|rebuild|traverse. + +**-c**, **--config** PATH +Path to configuration file. +Supported by: analyse|build|describe|install|rebuild. + +**-C**, **--repository-config** PATH +Path to configuration file for multi-repository builds. See +**just-repository-config(5)** for more details. +Supported by: analyse|build|describe|install|rebuild|traverse. + +**-D**, **--defines** JSON +Defines, via an in-line JSON object a configuration to overlay (in the +sense of `map_union`) to the configuration obtained by the **--config** +option. If **-D** is given several times, the **-D** options overlay in +the order they are given on the command line. +Supported by: analyse|build|describe|install|rebuild. + +**--request-action-input** ACTION +Modify the request to be, instead of the analysis result of the +requested target, the input stage of the specified action as artifacts, +with empty runfiles and a provides map providing the remaining +information about the action, in particular as `"cmd"` the arguments +vector and `"env"` the environment. + +An action can be specified in the following ways + + - an action identifier prefixed by the `%` character + - a number prefixed by the `#` character (note that it requires + quoting on most shells). This specifies the action with that index + of the actions associated directly with that target; the indices + start from `0` onwards, and negative indices count from the end of + the array of actions. + - an action identifier or number without prefix, provided the action + identifier does not start with either `%` or `#` and the number does + not happen to be a valid action identifier. + +Supported by: analyse|build|describe|install|rebuild. + +**--expression-file-name** TEXT +Name of the expressions file. +Supported by: analyse|build|describe|install|rebuild. + +**--expression-root** PATH +Path of the expression files' root directory. Default: Same as +--rule-root. +Supported by: analyse|build|describe|install|rebuild. + +**-L**, **--local-launcher** JSON_ARRAY +JSON array with the list of strings representing the launcher to prepend +actions' commands before being executed locally. Default value: +`["env", "--"]` +Supported by: build|install|rebuild|traverse|execute. + +**--local-build-root** PATH +Root for local CAS, cache, and build directories. The path will be +created if it does not exist already. +Supported by: +build|install-cas|install|rebuild|traverse|gc|execute. + +**--main** NAME +The repository to take the target from. +Supported by: analyse|build|describe|install|rebuild|traverse. + +**--rule-file-name** TEXT +Name of the rules file. +Supported by: analyse|build|describe|install|rebuild. + +**--rule-root** PATH +Path of the rule files' root directory. Default: Same as --target-root +Supported by: analyse|build|describe|install|rebuild. + +**--target-file-name** TEXT +Name of the targets file. +Supported by: analyse|build|describe|install|rebuild. + +**--target-root** PATH +Path of the target files' root directory. Default: Same as +--workspace-root +Supported by: analyse|build|describe|install|rebuild. + +**-w**, **--workspace-root** PATH +Path of the workspace's root directory. +Supported by: analyse|build|describe|install|rebuild|traverse. + +General output options +---------------------- + +**--dump-artifacts-to-build** PATH +File path for writing the artifacts to build to. Output format is JSON +map with staging path as key, and intentional artifact description as +value. +Supported by: analyse|build|install|rebuild. + +**--dump-artifacts** PATH +Dump artifacts generated by the given target. Using `-` as PATH, it is +interpreted as stdout. Note that, passing `./-` will instead create a +file named `-` in the current directory. Output format is JSON map with +staging path as key, and object id description (hash, type, size) as +value. Each artifact is guaranteed to be KNOWN in CAS. Therefore, this +option cannot be used with `analyse`. +Supported by: build|install|rebuild|traverse. + +**--dump-graph** PATH +File path for writing the action graph description to. See +**just-graph-file(5)** for more details. +Supported by: analyse|build|install|rebuild. + +**-f,--log-file** PATH +Path to local log file. `just` will store the information printed on +stderr in the log file along with the thread id and timestamp when the +output has been generated. +Supported by: +analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. + +**--log-limit** NUM +Log limit (higher is more verbose) in interval \[0,6\] (Default: 3). +Supported by: +analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. + +**--plain-log** +Do not use ANSI escape sequences to highlight messages. +Supported by: +analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. + +**--log-append** +Append messages to log file instead of overwriting existing. +Supported by: +analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. + +**--expression-log-limit** NUM +In error messages, truncate the entries in the enumeration of the active +environment, as well as the expression to be evaluated, to the specified +number of characters (default: 320). +Supported by: analyse|build|install + +**-P**, **--print-to-stdout** LOGICAL_PATH +After building, print the specified artifact to stdout. + +**-s**, **--show-runfiles** +Do not omit runfiles in build report. +Supported by: build|install|rebuild|traverse. + +Output dir and path +------------------- + +**-o**, **--output-dir** PATH +Path of the directory where outputs will be copied. If the output path +does not exist, it will create all the necessary folders and subfolders. +If the artifacts have been already staged, they will be overwritten. +Required by: install|traverse. + +**-o**, **--output-path** PATH +Install path for the artifact. Refer to **install-cas** section for more +details. +Supported by: install-cas + +**--raw-tree** +When installing a tree to stdout, i.e., when no option **-o** is given, +dump the raw tree rather than a pretty-printed version. Supported by: +install-cas + +**--remember** +Ensure that all installed artifacts are available in local CAS as well, +even when using remote execution. Supported by: +install|traverse|install-cas + +Parallelism options +------------------- + +**-J**, **--build-jobs** NUM +Number of jobs to run during build phase. Default: same as --jobs. +Supported by: build|install|rebuild|traverse. + +**-j**, **--jobs** NUM +Number of jobs to run. Default: Number of cores. +Supported by: analyse|build|describe|install|rebuild|traverse. + +Remote execution options +------------------------ + +As remote execution properties shard the target-level cache, they are +also available for analysis. In this way, the same action identifiers +can be achieved despite the extensional projection inherent to target +level caching, e.g., in conjunction with **--request-action-input**. + +**--remote-execution-property** KEY:VAL +Property for remote execution as key-value pair. Specifying this option +multiple times will accumulate pairs. If multiple pairs with the same +key are given, the latest wins. +Supported by: analyse|build|install|rebuild|traverse. + +**-r**, **--remote-execution-address** NAME:PORT +Address of the remote execution service. +Supported by: analyse|build|install-cas|install|rebuild|traverse. + +Authentication options +---------------------- + +Only TLS and mutual TLS (mTLS) are supported. + +**--tls-ca-cert** PATH +Path to a TLS CA certificate that is trusted to sign the server +certificate. Supported by: +build|install-cas|install|rebuild|traverse|execute. + +**--tls-client-cert** PATH +Path to a TLS client certificate to enable mTLS. It must be passed in +conjunction with **--tls-client-key** and **--tls-ca-cert**. Supported +by: build|install-cas|install|rebuild|traverse. + +**--tls-client-key** PATH +Path to a TLS client key to enable mTLS. It must be passed in +conjunction with **--tls-client-cert** and **--tls-ca-cert**. Supported +by: build|install-cas|install|rebuild|traverse. + +**analyse** specific options +---------------------------- + +**--dump-actions** PATH +Dump actions to file. `-` is treated as stdout. Output is a list of +action descriptions, in JSON format, for the given target. + +**--dump-anonymous** PATH +Dump anonymous targets to file. `-` is treated as stdout. Output is a +JSON map, for all transitive targets, with two entries: `nodes` and +`rule_maps`. The former contains maps between node id and the node +description. `rule_maps` states the maps between the `mode_type` and the +rule to use in order to make a target out of the node. + +**--dump-blobs** PATH +Dump blobs to file. `-` is treated as stdout. The term `blob` identifies +a collection of strings that the execution back end should be aware of +before traversing the action graph. A blob, will be referred to as a +KNOWN artifact in the action graph. + +**--dump-nodes** PATH +Dump nodes of only the given target to file. `-` is treated as stdout. +Output is a JSON map between node id and its description. + +**--dump-vars** PATH +Dump configuration variables to file. `-` is treated as stdout. The +output is a JSON list of those variable names (in lexicographic order) +at which the configuration influenced the analysis of this target. This +might contain variables unset in the configuration if the fact that they +were unset (and hence treated as the default `null`) was relevant for +the analysis of that target. + +**--dump-targets** PATH +Dump all transitive targets to file for the given target. `-` is treated +as stdout. Output is a JSON map of all targets encoded as tree by their +entity name: + +``` jsonc +{ "#": // anonymous targets + { "<rule_map_id>": + { "<node_id>": ["<serialized config1>", ...] } // all configs this target is configured with + } +, "@": // "normal" targets + { "<repo>": + { "<module>": + { "<target>": ["<serialized config1>", ...] } // all configs this target is configured with + } + } +} +``` + +**--dump-export-targets** PATH +Dump all transitive targets to file for the given target that are export +targets. `-` is treated as stdout. The output format is the same as for +**--dump-targets**. + +**--dump-targets-graph** PATH +Dump the graph of configured targets to a file (even if it is called +`-`). In this graph, only non-source targets are reported. The graph is +represented as a JSON object. The keys are the nodes of the graph, and +for each node, the value is a JSON object containing the different kind +of dependencies (each represented as a list of nodes). + + - "declared" are the dependencies coming from the target fields in + the definition of the target + - "implicit" are the dependencies implicit from the rule definition + - "anonymous" are the dependencies on anonymous targets implicitly + referenced during the evaluation of that rule + +While the node names are strings (so that they can be keys in a JSON +object), they can themselves be decoded as JSON and in this way +precisely name the configured target. More precisely, the JSON decoding +of a node name is a list of length two, with the first entry being the +target name (as `["@", repo, + module, target]` or `["#", rule_map_id, node_id]`) and the second +entry the effective configuration. + +**--dump-trees** PATH +Dump trees and all subtrees of the given target to file. `-` is treated +as stdout. Output is a JSON map between tree ids and the corresponding +artifact map, which maps the path to the artifact description. + +**rebuild** specific options +---------------------------- + +**--vs** NAME:PORT|"local" +Cache endpoint to compare against (use "local" for local cache). + +**--dump-flaky** PATH +Dump flaky actions to file. + +**traverse** specific options +----------------------------- + +**-a**, **--artifacts** TEXT +JSON maps between relative path where to copy the artifact and its +description (as JSON object as well). + +**-g**, **--graph-file** TEXT `[[REQUIRED]]` +Path of the file containing the description of the actions. See +**just-graph-file(5)** for more details. + +**--git-cas** TEXT +Path to a Git repository, containing blobs of potentially missing KNOWN +artifacts. + +**describe** specific options +----------------------------- + +**--json** +Omit pretty-printing and describe rule in JSON format. + +**--rule** +Module and target arguments refer to a rule instead of a target. + +**execute** specific options +---------------------------- + +**-p,--port** INT +Execution service will listen to this port. If unset, the service will +listen to the first available one. + +**--info-file** TEXT +Write the used port, interface, and pid to this file in JSON format. If +the file exists, it will be overwritten. + +**-i,--interface** TEXT +Interface to use. If unset, the loopback device is used. + +**--pid-file** TEXT +Write pid to this file in plain txt. If the file exists, it will be +overwritten. + +**--tls-server-cert** TEXT +Path to the TLS server certificate. + +**--tls-server-key** TEXT +Path to the TLS server key. + +**----log-operations-threshold** INT +Once the number of operations stored exceeds twice 2^n, where n is +given by the option --log-operations-threshold, at most 2^n operations +will be removed, in a FIFO scheme. If unset, defaults to 14. Must be in +the range \[0,255\]. + +EXIT STATUS +=========== + +The exit status of `just` is one of the following values: + + - 0: the command completed successfully + - 1: the command could not complete due to some errors (e.g., + compilation errors, missing arguments, syntax errors, etc.) + - 2: the command successfully parsed all the needed files (e.g., + TARGETS), successfully compiled the eventually required objects, but + the generation of some artifacts failed (e.g., a test failed). diff --git a/share/man/just.1.org b/share/man/just.1.org deleted file mode 100644 index d1c8b7f7..00000000 --- a/share/man/just.1.org +++ /dev/null @@ -1,631 +0,0 @@ -#+TITLE: JUST -#+MAN_CLASS_OPTIONS: :section-id "1" - -* NAME - -just - a generic build tool. - -* SYNOPSIS - -just version\\ -just {analyse|build} [OPTIONS] [[module] target]\\ -just install -o <OUTPUT_DIR> [OPTIONS] [[module] target]\\ -just install-cas [OPTIONS] <OBJECT_ID>\\ -just describe [OPTIONS] [[module] target]\\ -just rebuild [OPTIONS] [[module] target]\\ -just traverse -g <GRAPH_FILE> -o <OUT_DIR> [OPTIONS]\\ -just gc [OPTIONS]\\ -just execute [OPTIONS] - -* DESCRIPTION - -Just is a generic multi-repository build system; language-specific -knowledge is described in separate rule files. For every build action, -the relative location of the inputs is independent of their physical -location. This staging allows taking sources from different locations -(logical repositories), including bare git repositories. Targets are -defined using JSON format, in proper files (by default, named -~TARGETS~). Targets are uniquely identified by their name, the -repository, and the module they belong to. A module is the relative -path from the repository target root directory to a subdirectory -containing a target file. - -The module's name of the targets defined at the target root level is -the empty string. Specifying the correct repository, target root, -module, and target name allows to process that target independently of -the current working directory. - -If the module is not specified on the command line, ~just~ sets the -module corresponding to the current working directory. - -If a target is not specified, the lexicographically-first target, -according to native byte order, is used. So, a target named with an -empty string will always be the default target for that module. - -If a target depends on other targets defined in other modules or -repositories, ~just~ will recursively visit all and only the required -modules. - -The main repository is the repository containing the target specified -on the command line. The main repository can either be read from the -multi-repository configuration file if it contains the key ~main~ or -through the option ~--main~. The command-line option ~--main~ -overrides what is eventually read from the multi-repository -configuration file. If neither the multi-repository configuration file -contains the ~main~ key nor the ~--main~ option is provided, the lexicographical -first repository from the multi-repository configuration file is used as main. - -The ~workspace_root~ of the main repository is then defined as -follows. If the option ~--workspace-root~ is provided, then -~workspace_root~ is set accordingly. If the option is not provided, -~just~ checks if it is specified within the multi-repository -configuration file. If it is, then it is set accordingly. If not, just -starts looking for a marker in the current directory first, then in -all the parent directories until it finds one. The supported markers -are - - ROOT file (can be empty, content is ignored) - - WORKSPACE (can be empty, content is ignored) - - .git (can be either a file - empty or not, content is ignored - - or the famous directory) -If it fails, ~just~ errors out. - -For non-main repositories, the ~workspace_root~ entry must be declared -in the multi-repository configuration file. - -Afterwards, ~target_root~, ~rule_root~, and ~expression_root~ -directories for the main repository are set using the following -strategy. If the corresponding command-line option is specified, then -it is honored. Otherwise, it is read from the multi-repo configuration -file. If it is not specified there, the default value is used. The -default value of ~target_root~ is ~workspace_root~, of ~rule_root~ is -~target_root~, and of ~expression_root~ is ~rule_root~. - -Finally, the file names where ~targets~, ~rules~, and ~expressions~ -are defined for the main repository. If the corresponding key is -present in the multi-repository configuration file, it is set -accordingly. If the user gives the corresponding command-line option, -it overwrites what is eventually read from the configuration file. If -they are not explicitly stated neither within the multi-repository -configuration file nor on the command line, the default values are -used, which are ~TARGETS~, ~RULES~, and ~EXPRESSIONS~, respectively. - -For non-main repositories (i.e., repositories defining targets -required by the target given on the command line), ~target_root~, -~rule_root~, ~expression_root~, and file names of targets, rules and -expressions, if different from the default values, must be declared in -the multi-repository configuration file. - -* SUBCOMMANDS - -** version - -Print on stdout a JSON object providing version information about -the version of the tool used. This JSON object will contain at -least the following keys. -- ~"version"~ The version, as a list of numbers of length at least - 3, following the usual convention that version numbers are compared - lexicographically. -- ~"suffix"~ The version suffix as a string. Generally, suffixes - starting with a ~+~ symbol are positive offsets to the version, - while suffixes starting with a ~~~ symbol are negative offsets. -- ~"SOURCE_DATE_EPOCH"~ Either a number or ~null~. If it is a - number, it is the time, in seconds since the epoch, of the last - commit that went into this binary. It is ~null~ if that time is - not known (e.g., in development builds). - -** analyse|build|install - -The subcommands ~analyse~, ~build~, and ~install~ are strictly -related. In fact, from left to right, one is a subset of the -other. ~build~ performs work on top of ~analyse~, and ~install~ on top -of ~build~. When a user issues ~build~, the ~analyse~ is called -underneath. In particular, there is no need to run these three -subcommands sequentially. - -*** analyse - -~analyse~ reads the target graph from TARGETS files for the given -target, computes the action graph (required by e.g., ~build~, -~install~, ~traverse~), and reports the artifacts, provides, and -runfiles of the analysed target. - -In short, the ~analyse~ subcommand identifies all the steps required to -build a given target without actually performing those steps. - -This subcommand, issued with proper flags, can dump in JSON format -artifacts, action graph, nodes, actions, (transitive) targets (both -named and anonymous), and trees. - -*** build - -This subcommand performs the actions contained in the action graph -computed through the ~analyse~ phase. - -If building locally, the building process is performed in temporary -separate directories to allow for staging according to the logical -path described in the TARGETS file. Since artifacts are only stored in -the CAS, the user has to use either the ~install~ or ~install-cas~ -subcommand to get them. - -~just~ allows for both local (i.e., on the same machine where ~just~ -is used) and remote compilation (i.e., by sending requests over a TCP -connection, e.g., to a different machine, cluster or cloud -infrastructure). In case of a remote compilation, artifacts are -compiled remotely and stored in the remote CAS. ~install~ and -~install-cas~ subcommands can be used to locally fetch and stage the -desired artifacts. - -*** install - -The ~install~ subcommand determines which (if any) actions need to be -(re)done and issues the command to (re)run them. Then, it installs the -artifacts (stored in the local or remote CAS) of the processed target -under the given output-dir (set by option ~-o~) honoring the logical -path (aka, staging). If the output path does not exist, it will create -all the necessary folders and subfolders. If files are already present, -they will be overwritten. - -** rebuild - -This subcommand inspects if builds are fully reproducible or not -(e.g., time stamps are used). It simply rebuilds and compares -artifacts to the cached build reporting actions with different -output. To do so in a meaningful way, it requires that previous build -is already in the cache (local or remote). - -** describe - -The ~describe~ subcommand allows for describing the rule generating a -target. The rule is resolved in precisely the same way as during the -analysis. The doc-strings (if any) from the rule definition (if -user-defined) are reported, together with a summary of the declared -fields and their types. The multi-repository configuration is honored -in the same way as during ~analyse~ and ~build~; in particular, the -rule definition can also reside in a git-tree root. - -** install-cas - -~install-cas~ fetches artifacts from CAS (Content Addressable -Storage) by means of their object identifier. The canonical format -of an object identifier is ~[<hash>:<size>:<type>]~; however, when -parsing an object identifier, ~install-cas~ uses the following -default rules, to make usage simpler. -- The square brackets are optional. -- If the size is missing (e.g., because the argument contains no - colon), or cannot be parsed as a number, this is not an error, - and the value ~0~ is assumed. While this is almost never the - correct size, many CAS implementations, including the local CAS - of just itself, ignore the size for lookups. -- From the type, only the first letter (~f~ for non-executable - file, ~x~ for executable file, and ~t~ for tree) is significant; - the rest is ignored. If the type is missing (e.g., because the - argument contains less than two colons), or its first letter is - not one of the valid ones, ~f~ is assumed. - -Depending on whether the output path is set -or not, the behavior is different. - -*** Output path is omitted - -If the output path is omitted, it prints the artifact content to -stdout and if the artifact is a tree, it will print a human readable -description. - -*** Output path is set - -**** Output path does not exist - -The artifact will be staged to that path. If artifact is a file, the -installed one will have the name of the output path. If the artifact -is a tree, it will create a directory named like the output path, and -will stage all the entries (subtrees included) under that directory. - -**** Output path exists and it is a directory - -If the artifact is a tree, a directory named with the hash of tree -itself is created under the output path, and all the entries and -subtrees are installed inside the hash-named directory. - -If the artifact is a file, it is installed under the output path and -named according to the hash of the artifact itself. - -**** Output path exists and it is a file - -If the artifact is a file, it will replace the existing file. If -the artifact is a tree, it will cause an error. - -** traverse - -It allows for the building and staging of requested artifacts from a -well-defined graph file. See *just-graph-file(5)* for more details. - -** gc - -The *gc* subcommand triggers garbage collection of the local cache. -More precisely, it rotates the cache and CAS generations. During -a build, upon cache hit, everything related to that cache hit is -uplinked to the youngest generation; therefore, upon a call to ~gc~ -everything not referenced since the last call to ~gc~ is purged -and the corresponding disk space reclaimed. - -** execute - -This subcommand starts a single node remote execution service, -honoring the just native remote protocol. - -If the flag --compatible is provided, the execution service will honor -the original remote build execution protocol. - -* OPTIONS - -** Generic program information - - *-h*, *--help* - Output a usage message and exit.\\ - Supported by: all subcommands. - -** Compatibility options - - *--compatible* \\ - At increased computational effort, be compatible with the original - remote build execution protocol. As the change affects identifiers, - the flag must be used consistently for all related invocations.\\ - Supported by: analyse|build|install-cas|install|rebuild|traverse|execute. - -** Build configuration options - - *--action-timeout* NUM\\ - Action timeout in seconds. (Default: 300). The timeout is honored - only for the remote build.\\ - Supported by: build|install|rebuild|traverse. - - *-c*, *--config* PATH\\ - Path to configuration file.\\ - Supported by: analyse|build|describe|install|rebuild. - - *-C*, *--repository-config* PATH\\ - Path to configuration file for multi-repository builds. See - *just-repository-config(5)* for more details.\\ - Supported by: analyse|build|describe|install|rebuild|traverse. - - *-D*, *--defines* JSON\\ - Defines, via an in-line JSON object a configuration to overlay - (in the sense of ~map_union~) to the configuration - obtained by the *--config* option. If *-D* is given several times, - the *-D* options overlay in the order they are given on the command - line.\\ - Supported by: analyse|build|describe|install|rebuild. - - *--request-action-input* ACTION\\ - Modify the request to be, instead of the analysis result of the requested - target, the input stage of the specified action as artifacts, with empty - runfiles and a provides map providing the remaining information about the - action, in particular as ~"cmd"~ the arguments vector and ~"env"~ the - environment. - - An action can be specified in the following ways - - an action identifier prefixed by the ~%~ character - - a number prefixed by the ~#~ character (note that it requires quoting - on most shells). This specifies the action with that index of the actions - associated directly with that target; the indices start from ~0~ onwards, - and negative indices count from the end of the array of actions. - - an action identifier or number without prefix, provided the action - identifier does not start with either ~%~ or ~#~ and the number does not - happen to be a valid action identifier. - Supported by: analyse|build|describe|install|rebuild. - - *--expression-file-name* TEXT\\ - Name of the expressions file.\\ - Supported by: analyse|build|describe|install|rebuild. - - *--expression-root* PATH\\ - Path of the expression files' root directory. Default: Same as --rule-root.\\ - Supported by: analyse|build|describe|install|rebuild. - - *-L*, *--local-launcher* <JSON_ARRAY>\\ - JSON array with the list of strings representing the launcher to - prepend actions' commands before being executed locally. Default - value: ~["env", "--"]~ \\ - Supported by: build|install|rebuild|traverse|execute. - - *--local-build-root* PATH\\ - Root for local CAS, cache, and build directories. The path will be - created if it does not exist already.\\ - Supported by: build|install-cas|install|rebuild|traverse|gc|execute. - - *--main* NAME\\ - The repository to take the target from.\\ - Supported by: analyse|build|describe|install|rebuild|traverse. - - *--rule-file-name* TEXT\\ - Name of the rules file.\\ - Supported by: analyse|build|describe|install|rebuild. - - *--rule-root* PATH\\ - Path of the rule files' root directory. Default: Same as --target-root\\ - Supported by: analyse|build|describe|install|rebuild. - - *--target-file-name* TEXT\\ - Name of the targets file.\\ - Supported by: analyse|build|describe|install|rebuild. - - *--target-root* PATH\\ - Path of the target files' root directory. Default: Same as --workspace-root\\ - Supported by: analyse|build|describe|install|rebuild. - - *-w*, *--workspace-root* PATH\\ - Path of the workspace's root directory.\\ - Supported by: analyse|build|describe|install|rebuild|traverse. - -** General output options - - *--dump-artifacts-to-build* PATH\\ - File path for writing the artifacts to build to. Output format is - JSON map with staging path as key, and intentional artifact - description as value.\\ - Supported by: analyse|build|install|rebuild. - - *--dump-artifacts* PATH\\ - Dump artifacts generated by the given target. Using ~-~ as PATH, it - is interpreted as stdout. Note that, passing ~./-~ will instead - create a file named ~-~ in the current directory. Output format is - JSON map with staging path as key, and object id description (hash, - type, size) as value. Each artifact is guaranteed to be KNOWN in - CAS. Therefore, this option cannot be used with ~analyse~.\\ - Supported by: build|install|rebuild|traverse. - - *--dump-graph* PATH\\ - File path for writing the action graph description to. See - *just-graph-file(5)* for more details.\\ - Supported by: analyse|build|install|rebuild. - - *-f,--log-file* PATH\\ - Path to local log file. ~just~ will store the information printed - on stderr in the log file along with the thread id and timestamp - when the output has been generated.\\ - Supported by: analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. - - *--log-limit* NUM\\ - Log limit (higher is more verbose) in interval [0,6] (Default: 3).\\ - Supported by: analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. - - *--plain-log*\\ - Do not use ANSI escape sequences to highlight messages.\\ - Supported by: analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. - - *--log-append*\\ - Append messages to log file instead of overwriting existing.\\ - Supported by: analyse|build|describe|install|install-cas|rebuild|traverse|gc|execute. - - *--expression-log-limit* NUM\\ - In error messages, truncate the entries in the enumeration of the active - environment, as well as the expression to be evaluated, to the specified - number of characters (default: 320).\\ - Supported by: analyse|build|install - - *-P*, *--print-to-stdout* LOGICAL_PATH\\ - After building, print the specified artifact to stdout.\\ - - *-s*, *--show-runfiles* \\ - Do not omit runfiles in build report.\\ - Supported by: build|install|rebuild|traverse. - -** Output dir and path - - *-o*, *--output-dir* PATH\\ - Path of the directory where outputs will be copied. If the output - path does not exist, it will create all the necessary folders and - subfolders. If the artifacts have been already staged, they will be - overwritten.\\ - Required by: install|traverse. - - *-o*, *--output-path* PATH\\ - Install path for the artifact. Refer to *install-cas* section for - more details.\\ - Supported by: install-cas - - *--raw-tree*\\ - When installing a tree to stdout, i.e., when no option *-o* is given, - dump the raw tree rather than a pretty-printed version. - Supported by: install-cas - - *--remember*\\ - Ensure that all installed artifacts are available in local CAS as well, - even when using remote execution. - Supported by: install|traverse|install-cas - -** Parallelism options - - *-J*, *--build-jobs* NUM\\ - Number of jobs to run during build phase. Default: same as --jobs.\\ - Supported by: build|install|rebuild|traverse. - - *-j*, *--jobs* NUM\\ - Number of jobs to run. Default: Number of cores.\\ - Supported by: analyse|build|describe|install|rebuild|traverse. - -** Remote execution options - - As remote execution properties shard the target-level cache, they are also - available for analysis. In this way, the same action identifiers can be - achieved despite the extensional projection inherent to target level caching, - e.g., in conjunction with *--request-action-input*. - - *--remote-execution-property* KEY:VAL\\ - Property for remote execution as key-value pair. Specifying this - option multiple times will accumulate pairs. If multiple pairs with - the same key are given, the latest wins.\\ - Supported by: analyse|build|install|rebuild|traverse. - - *-r*, *--remote-execution-address* NAME:PORT\\ - Address of the remote execution service.\\ - Supported by: analyse|build|install-cas|install|rebuild|traverse. - -** Authentication options - - Only TLS and mutual TLS (mTLS) are supported. - - *--tls-ca-cert* PATH\\ - Path to a TLS CA certificate that is trusted to sign the server - certificate. - Supported by: build|install-cas|install|rebuild|traverse|execute. - - *--tls-client-cert* PATH\\ - Path to a TLS client certificate to enable mTLS. It must be passed - in conjunction with *--tls-client-key* and *--tls-ca-cert*. - Supported by: build|install-cas|install|rebuild|traverse. - - *--tls-client-key* PATH\\ - Path to a TLS client key to enable mTLS. It must be passed in - conjunction with *--tls-client-cert* and *--tls-ca-cert*. - Supported by: build|install-cas|install|rebuild|traverse. - -** *analyse* specific options - - *--dump-actions* PATH\\ - Dump actions to file. ~-~ is treated as stdout. Output is a list of - action descriptions, in JSON format, for the given target. - - *--dump-anonymous* PATH\\ - Dump anonymous targets to file. ~-~ is treated as stdout. Output is - a JSON map, for all transitive targets, with two entries: ~nodes~ - and ~rule_maps~. The former contains maps between node id and the - node description. ~rule_maps~ states the maps between the - ~mode_type~ and the rule to use in order to make a target out of - the node. - - *--dump-blobs* PATH\\ - Dump blobs to file. ~-~ is treated as stdout. The term ~blob~ - identifies a collection of strings that the execution back end - should be aware of before traversing the action graph. A blob, will - be referred to as a KNOWN artifact in the action graph. - - *--dump-nodes* PATH\\ - Dump nodes of only the given target to file. ~-~ is treated as - stdout. Output is a JSON map between node id and its description. - - *--dump-vars* PATH\\ - Dump configuration variables to file. ~-~ is treated as - stdout. The output is a JSON list of those variable names (in - lexicographic order) at which the configuration influenced the - analysis of this target. This might contain variables unset - in the configuration if the fact that they were unset (and - hence treated as the default ~null~) was relevant for the - analysis of that target. - - *--dump-targets* PATH\\ - Dump all transitive targets to file for the given target. ~-~ is - treated as stdout. Output is a JSON map of all targets encoded as - tree by their entity name: - - #+BEGIN_SRC shell - { "#": // anonymous targets - { "<rule_map_id>": - { "<node_id>": ["<serialized config1>", ...] } // all configs this target is configured with - } - , "@": // "normal" targets - { "<repo>": - { "<module>": - { "<target>": ["<serialized config1>", ...] } // all configs this target is configured with - } - } - } - #+END_SRC - - *--dump-export-targets* PATH\\ - Dump all transitive targets to file for the given target that are - export targets. ~-~ is treated as stdout. The output format is - the same as for *--dump-targets*. - - *--dump-targets-graph* PATH\\ - Dump the graph of configured targets to a file (even if it - is called ~-~). In this graph, only non-source targets are - reported. The graph is represented as a JSON object. The keys - are the nodes of the graph, and for each node, the value is a - JSON object containing the different kind of dependencies (each - represented as a list of nodes). - - "declared" are the dependencies coming from the target fields - in the definition of the target - - "implicit" are the dependencies implicit from the rule definition - - "anonymous" are the dependencies on anonymous targets implicitly - referenced during the evaluation of that rule - While the node names are strings (so that they can be keys in - a JSON object), they can themselves be decoded as JSON and in - this way precisely name the configured target. More precisely, - the JSON decoding of a node name is a list of length two, - with the first entry being the target name (as ~["@", repo, - module, target]~ or ~["#", rule_map_id, node_id]~) and the - second entry the effective configuration. - - *--dump-trees* PATH\\ - Dump trees and all subtrees of the given target to file. ~-~ is - treated as stdout. Output is a JSON map between tree ids and the - corresponding artifact map, which maps the path to the artifact - description. - -** *rebuild* specific options - - *--vs* NAME:PORT|"local"\\ - Cache endpoint to compare against (use "local" for local cache). - - *--dump-flaky* PATH\\ - Dump flaky actions to file. - -** *traverse* specific options - - *-a*, *--artifacts* TEXT\\ - JSON maps between relative path where to copy the artifact and its - description (as JSON object as well). - - *-g*, *--graph-file* TEXT ~[[REQUIRED]]~ \\ - Path of the file containing the description of the actions. See - *just-graph-file(5)* for more details. - - *--git-cas* TEXT\\ - Path to a Git repository, containing blobs of potentially missing - KNOWN artifacts. - -** *describe* specific options - - *--json*\\ - Omit pretty-printing and describe rule in JSON format. - - *--rule*\\ - Module and target arguments refer to a rule instead of a target. - -** *execute* specific options - - *-p,--port* INT\\ - Execution service will listen to this port. If unset, the service will listen to the first available one. - - *--info-file* TEXT\\ - Write the used port, interface, and pid to this file in JSON format. If the file exists, it will be overwritten. - - *-i,--interface* TEXT\\ - Interface to use. If unset, the loopback device is used. - - *--pid-file* TEXT\\ - Write pid to this file in plain txt. If the file exists, it will be overwritten. - - *--tls-server-cert* TEXT\\ - Path to the TLS server certificate. - - *--tls-server-key* TEXT\\ - Path to the TLS server key. - - *----log-operations-threshold* INT\\ - Once the number of operations stored exceeds twice 2^n, where n is given by - the option --log-operations-threshold, at most 2^n operations will be removed, - in a FIFO scheme. If unset, defaults to 14. Must be in the range [0,255]. - - -* EXIT STATUS - -The exit status of ~just~ is one of the following values: - - 0: the command completed successfully - - 1: the command could not complete due to some errors (e.g., - compilation errors, missing arguments, syntax errors, etc.) - - 2: the command successfully parsed all the needed files (e.g., - TARGETS), successfully compiled the eventually required objects, - but the generation of some artifacts failed (e.g., a test - failed). |