summaryrefslogtreecommitdiff
path: root/share/man/just-graph-file.5.md
blob: 66c3f8aed29e9b2f60cbe8f197c43fd122752c65 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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)**