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
|
* Documentation of build rules, expressions, etc
Build rules can obtain a non-trivial complexity. This is especially
true if several rules have to exist for slightly different use
cases, or if the rule supports many different fields. Therefore,
documentation of the rules (and also expressions for the benefit
of rule authors) is desirable.
Experience shows that documentation that is not versioned together with
the code it refers to quickly gets out of date, or lost. Therefore,
we add documentation directly into the respective definitions.
** Multi-line strings in JSON
In JSON, the newline character is encoded specially and not taken
literally; also, there is not implicit joining of string literals.
So, in order to also have documentation readable in the JSON
representation itself, instead of single strings, we take arrays
of strings, with the understanding that they describe the strings
obtained by joining the entries with newline characters.
** Documentation is optional
While documentation is highly recommended, it still remains optional.
Therefore, when in the following we state that a key is for a list
or a map, it is always implied that it may be absent; in this case,
the empty array or the empty map is taken as default, respectively.
** Rules
Each rule is described as a JSON object with a fixed set of keys.
So having fixed keys for documentation does not cause conflicts.
More precisely, the keys ~doc~, ~field doc~, ~config_doc~,
~artifacts_doc~, ~runfiles_doc~, and ~provides_doc~
are reserved for documentation. Here, ~doc~ has to be a list of
strings describing the rule in general. ~field doc~ has to be a map
from (some of) the field names to an array of strings, containing
additional information on that particular field. ~config_doc~ has
to be a map from (some of) the config variables to an array of
strings describing the respective variable. ~artifacts_doc~ is
an array of strings describing the artifacts produced by the rule.
~runfiles_doc~ is an array of strings describing the runfiles produced
by this rule. Finally, ~provides_doc~ is a map describing (some
of) the providers by that rule; as opposed to fields or config
variables there is no authoritative list of providers given elsewhere
in the rule, so it is up to the rule author to give an accurate
documentation on the provided data.
*** Example
#+BEGIN_SRC
{ "library":
{ "doc":
[ "A C library"
, ""
, "Define a library that can be used to be statically linked to a"
, "binary. To do so, the target can simply be specified in the deps"
, "field of a binary; it can also be a dependency of another library"
, "and the information is then propagated to the corresponding binary."
]
, "string_fields": ["name"]
, "target_fields": ["srcs", "hdrs", "private-hdrs", "deps"]
, "field_doc":
{ "name":
["The base name of the library (i.e., the name without the leading lib)."]
, "srcs": ["The source files (i.e., *.c files) of the library."]
, "hdrs":
[ "The public header files of this library. Targets depending on"
, "this library will have access to those header files"
]
, "private-hdrs":
[ "Additional internal header files that are used when compiling"
, "the source files. Targets depending on this library have no access"
, "to those header files."
]
, "deps":
[ "Any other libraries that this library uses. The dependency is"
, "also propagated (via the link-deps provider) to any consumers of"
, "this target. So only direct dependencies should be declared."
]
}
, "config_vars": ["CC"]
, "config_doc":
{ "CC":
[ "single string. defaulting to \"cc\", specifying the compiler"
, "to be used. The compiler is also used to launch the preprocessor."
]
}
, "artifacts_doc":
["The actual library (libname.a) staged in the specified directory"]
, "runfiles_doc": ["The public headers of this library"]
, "provides_doc":
{ "compile-deps":
[ "Map of artifacts specifying any additional files that, besides the runfiles,"
, "have to be present in compile actions of targets depending on this library"
]
, "link-deps":
[ "Map of artifacts specifying any additional files that, besides the artifacts,"
, "have to be present in a link actions of targets depending on this library"
]
, "link-args":
[ "List of strings that have to be added to the command line for linking actions"
, "in targets depending on this library"
]
}
, "expression": { ... }
}
}
#+END_SRC
** Expressions
Expressions are also described by a JSON object with a fixed set of
keys. Here we use the keys ~doc~ and ~vars_doc~ for documentation,
where ~doc~ is an array of strings describing the expression as a
whole and ~vars_doc~ is a map from (some of) the ~vars~ to an array
of strings describing this variable.
** Export targets
As export targets play the role of interfaces between repositories,
it is important that they be documented as well. Again, export targets
are described as a JSON object with fixed set of keys amd we use
the keys ~doc~ and ~config_doc~ for documentation. Here ~doc~ is an
array of strings describing the targeted in general and ~config_doc~
is a map from (some of) the variables of the ~flexible_config~ to
an array of strings describing this parameter.
** Presentation of the documentation
As all documentation are just values (that need not be evaluated)
in JSON objects, it is easy to write tool rendering documentation
pages for rules, etc, and we expect those tools to be written
independently. Nevertheless, for the benefit of developers using
rules from a git-tree roots that might not be checked out, there is
a subcommand ~describe~ which takes a target specification like the
~analyze~ command, looks up the corresponding rule and describes
it fully, i.e., prints in human-readable form
- the documentation for the rule
- all the fields available for that rule together with
- their type (~string_field~, ~target_field~, etc), and
- their documentation,
- all the configuration variables of the rule with their
documentation (if given), and
- the documented providers.
|
