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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
* Getting Started
In order to use /justbuild/, first make sure that ~just~, ~just-mr~, and
~just-import-git~ are available in your ~PATH~.
** Creating a new project
/justbuild/ needs to know the root of the project worked on. By default, it
searches upwards from the current directory till it finds a marker. Currently,
we support three different markers: the files ~ROOT~ and ~WORKSPACE~ or the
directory ~.git~. Lets create a new project by creating one of those markers:
#+BEGIN_SRC sh
$ touch ROOT
#+END_SRC
** Creating a generic target
By default, targets are described in ~TARGETS~ files. These files contain a
~JSON~ object with the target name as key and the target description as value. A
target description is an object with at least a single mandatory field:
~"type"~. This field specifies which rule (built-in or user-defined) to apply
for this target.
A simple target that only executes commands can be created using the built-in
~"generic"~ rule, which requires at least one command and one output file or
directory. To create such a target, create the file ~TARGETS~ with the following
content:
#+SRCNAME: TARGETS
#+BEGIN_SRC js
{ "greeter":
{ "type": "generic"
, "cmds": ["echo -n 'Hello ' > out.txt", "cat name.txt >> out.txt"]
, "outs": ["out.txt"]
, "deps": ["name.txt"]
}
}
#+END_SRC
In this example, the ~"greeter"~ target will run two commands to produce the
output file ~out.txt~. The second command depends on the input file ~name.txt~
that we need to create as well:
#+BEGIN_SRC sh
$ echo World > name.txt
#+END_SRC
** Building a generic target
To build a target, we need to run ~just~ with the subcommand ~build~:
#+BEGIN_SRC sh
$ just build greeter
INFO: Requested target is [["@","","","greeter"],{}]
INFO: Analysed target [["@","","","greeter"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 1 actions, 0 trees, 0 blobs
INFO: Building [["@","","","greeter"],{}].
INFO: Processed 1 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
$
#+END_SRC
The subcommand ~build~ just builds the artifact but does not stage it to any
user-defined location on the file system. Instead it reports a description
of the artifact consisting of ~git~ blob identifier, size, and type (in
this case ~f~ for non-executable file). To also stage the produced artifact to
the working directory, use the ~install~ subcommand and specify the output
directory:
#+BEGIN_SRC sh
$ just install greeter -o .
INFO: Requested target is [["@","","","greeter"],{}]
INFO: Analysed target [["@","","","greeter"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 1 actions, 0 trees, 0 blobs
INFO: Building [["@","","","greeter"],{}].
INFO: Processed 1 actions, 1 cache hits.
INFO: Artifacts can be found in:
/tmp/tutorial/out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
$ cat out.txt
Hello World
$
#+END_SRC
Note that the ~install~ subcommand initiates the build a second time, without
executing any actions as all actions are being served from cache. The produced
artifact is identical, which is indicated by the same hash/size/type.
If one is only interested in a single final artifact, one can
also request via the ~-P~ option that this artifact be written to
standard output after the build. As all messages are reported to
standard error, this can be used for both, interactively reading a
text file, as well as for piping the artifact to another program.
#+BEGIN_SRC sh
$ just build greeter -Pout.txt
INFO: Requested target is [["@","","","greeter"],{}]
INFO: Analysed target [["@","","","greeter"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 1 actions, 0 trees, 0 blobs
INFO: Building [["@","","","greeter"],{}].
INFO: Processed 1 actions, 1 cache hits.
INFO: Artifacts built, logical paths are:
out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
Hello World
$
#+END_SRC
Alternatively, we could also directly request the artifact ~out.txt~ from
/justbuild/'s CAS (content-addressable storage) and print it on the command line
via:
#+BEGIN_SRC sh
$ just install-cas [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
Hello World
$
#+END_SRC
The canonical way of requesting an object from the CAS is, as just shown, to
specify the full triple of hash, size, and type, separated by colons and
enclosed in square brackets. To simplify usage, the brackets can be omitted
and the size and type fields have the default values ~0~ and ~f~, respectively.
While the default value for the size is wrong for all but one string, the hash
still determines the content of the file and hence the local CAS is still
able to retrieve the file. So the typical invocation would simply specify the
hash.
#+BEGIN_SRC sh
$ just install-cas 557db03de997c86a4a028e1ebd3a1ceb225be238
Hello World
$
#+END_SRC
** Targets versus Files: The Stage
When invoking the ~build~ command, we had to specify the target ~greeter~,
not the output file ~out.txt~. While other build systems allow requests
specifying an output file, for /justbuild/ this would conflict with a
fundamental design principle: staging; each target has its own logical
output space, the "stage", where it can put its artifacts. We can, without
any problem, add a second target also generating a file ~out.txt~.
#+SRCNAME: TARGETS
#+BEGIN_SRC js
...
, "upper":
{ "type": "generic"
, "cmds": ["cat name.txt | tr a-z A-Z > out.txt"]
, "outs": ["out.txt"]
, "deps": ["name.txt"]
}
...
#+END_SRC
As we only request targets, no conflicts arise.
#+BEGIN_SRC sh
$ just build upper -P out.txt
INFO: Requested target is [["@","","","upper"],{}]
INFO: Analysed target [["@","","","upper"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 1 actions, 0 trees, 0 blobs
INFO: Building [["@","","","upper"],{}].
INFO: Processed 1 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
out.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f]
WORLD
$ just build greeter -P out.txt
INFO: Requested target is [["@","","","greeter"],{}]
INFO: Analysed target [["@","","","greeter"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 1 actions, 0 trees, 0 blobs
INFO: Building [["@","","","greeter"],{}].
INFO: Processed 1 actions, 1 cache hits.
INFO: Artifacts built, logical paths are:
out.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
Hello World
$
#+END_SRC
While one normally tries to design targets in such a way that they
don't have conflicting files if they should be used together, it is
up to the receiving target to decide what to do with those artifacts.
A built-in rule allowing to rearrange artifacts is ~"install"~; a
detailed description of this rule can be found in the documentation.
In the simple case of a target producing precisely one file, the
argument ~"files"~ can be used to map that file to a new location.
#+SRCNAME: TARGETS
#+BEGIN_SRC js
...
, "both":
{"type": "install", "files": {"hello.txt": "greeter", "upper.txt": "upper"}}
...
#+END_SRC
#+BEGIN_SRC sh
$ just build both
INFO: Requested target is [["@","","","both"],{}]
INFO: Analysed target [["@","","","both"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 2 actions, 0 trees, 0 blobs
INFO: Building [["@","","","both"],{}].
INFO: Processed 2 actions, 2 cache hits.
INFO: Artifacts built, logical paths are:
hello.txt [557db03de997c86a4a028e1ebd3a1ceb225be238:12:f]
upper.txt [83cf24cdfb4891a36bee93421930dd220766299a:6:f]
$
#+END_SRC
|
