| blob | f165d820db6171ba4bd0cb5eb660b94cb5409d7c |
1 .\" $NetBSD: sysbuild.1,v 1.6 2012/10/13 18:40:33 jmmv Exp $
2 .\" Copyright 2012 Google Inc.
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions are
7 .\" met:
8 .\"
9 .\" * Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" * Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" * Neither the name of Google Inc. nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 .Dd March 8, 2013
30 .Dt SYSBUILD 1
31 .Os
32 .Sh NAME
33 .Nm sysbuild
34 .Nd performs fully automatic builds of NetBSD
35 .Sh SYNOPSIS
36 .Nm
37 .Op Fl c Ar config_name
38 .Op Fl o Ar variable=value
39 build
40 .Op Fl f
41 .Op Ar build_targets
42 .Nm
43 .Op Fl c Ar config_name
44 .Op Fl o Ar variable=value
45 config
46 .Nm
47 .Op Fl c Ar config_name
48 .Op Fl o Ar variable=value
49 env
50 .Op Ar machine
51 .Nm
52 .Op Fl c Ar config_name
53 .Op Fl o Ar variable=value
54 fetch
55 .Sh DESCRIPTION
56 .Nm
57 is a utility to build
58 .Nx
59 releases in a fully automated manner.
60 The process is made unattended by relying on a configuration file that
61 prespecifies the location of all build components and the desired goals of
62 the build.
63 If you want to plug
64 .Nm
65 into
66 .Xr cron 8 ,
67 please take a look to
68 .Xr sysbuild4cron 1
69 now.
70 .Pp
71 .Nm
72 can be seen as a simple wrapper over
73 .Xr cvs 1
74 and the
75 .Nm build.sh
76 script that ships with the
77 .Nx
78 source tree.
79 .Nm
80 provides the following additional features:
81 .Bl -bullet
82 .It
83 Automatically fetch or update the
84 .Nx
85 source trees (both src and xsrc)
86 before performing a build.
87 .It
88 Preconfigure the way
89 .Nm build.sh
90 is invoked by storing all relevant details in a configuration file.
91 .It
92 Perform builds for a variety of platforms with a single invocation.
93 .It
94 Trivially set up periodic
95 .Nx
96 rebuilds by adding a single line to your
97 .Xr crontab 5 .
98 .It
99 Hooks to plug other components into the build procedure.
100 For example: use
101 .Xr rsync 1
102 to push the results of a successful build to a file server.
103 .El
104 .Pp
105 As you can see in the
106 .Sx SYNOPSIS
107 section,
108 .Nm
109 provides a subcommand-interface: the tool has several modes of operation,
110 and the particular mode to use for a given run is selected by the first
111 non-option argument in the command line.
112 .Pp
113 The following options apply to all commands:
114 .Bl -tag -width XXXX
115 .It Fl c Ar config_name
116 Specifies the configuration file to use.
117 The format of the file is described in
118 .Xr sysbuild.conf 5 .
119 .Pp
120 If
121 .Ar config_name
122 includes any directory separator (aka, one or more slashes) or the
123 .Sq .conf
124 suffix, then this specifies the path of the configuration file to load.
125 .Pp
126 .If
127 .Ar config_name
128 is a plain name without any directory components nor extension, then this
129 specifies the name of the configuration.
130 .Nm
131 will first look for a configuration file in
132 .Pa ~/.sysbuild/<config_name>.conf
133 and, if not found, will use
134 .Pa @SYSBUILD_ETCDIR@/<config_name>.conf .
135 Any of the two files must exist, or else
136 .Nm
137 will exit with an error.
138 .It Fl o Ar variable=value
139 Applies an override to the loaded configuration.
140 .Pp
141 The
142 .Ar variable
143 part of the argument must be any of the recognized configuration variables
144 described in
145 .Xr sysbuild.conf 5 .
146 The
147 .Ar value ,
148 if not empty, specifies the value to set the configuration variable to.
149 If
150 .Ar value
151 is empty, then the configuration variable is unset.
152 .El
153 .Ss The build command
154 The build command provides the main functionality of
155 .Nm .
156 It performs the following steps:
157 .Bl -enum
158 .It
159 If
160 .Va UPDATE_SOURCES
161 is true, the fetch command is invoked first.
162 See
163 .Sx The fetch command
164 for more details.
165 .It
166 For every machine type listed in
167 .Va MACHINES ,
168 issues a
169 .Nm build.sh
170 call for that particular machine using the rest of the settings defined in
171 the configuration file.
172 The targets passed to the
173 .Nm build.sh
174 script are those defined in the
175 .Va BUILD_TARGETS
176 variable, or the arguments passed through the command line if any.
177 .El
178 .Pp
179 The following options apply only to the build command:
180 .Bl -tag -width XXXX
181 .It Fl f
182 Enables fast mode, which skips updating the source trees and performs
183 update builds.
184 This is a shorthand for these generic flags:
185 .Fl o Ar INCREMENTAL_BUILD=true
186 .Fl o Ar UPDATE_SOURCES=false .
187 .El
188 .Ss The config command
189 The config command dumps the loaded configuration to the standard output.
190 The format of the output is not a script, so it cannot be fed back into
191 .Nm .
192 The purpose of this command is to aid in debugging the configuration of the
193 tool before performing any builds, particularly when the configuration
194 files use shell logic to determine the value of any variables.
195 .Ss The env command
196 The env command prints a shell script snippet that defines environment variables
197 to simplify working with the directory layout of a
198 .Nx
199 build for a particular machine.
200 If the
201 .Va MACHINES
202 variable is not defined, or if it lists more than one machine, then the
203 .Ar machine
204 argument is required.
205 .Pp
206 The common mechanism to use these variables is by executing
207 .Nm
208 in the following way:
209 .Bd -literal -offset indent
210 $ eval $(sysbuild env)
211 .Ed
212 .Pp
213 The following variables are defined and/or modified:
214 .Bl -tag -width PATH
215 .It Va PATH
216 The path to the tools is prepended to the path.
217 Of particular interest is the
218 .Pa nbmake-<machine>
219 script made available in this way, which allows you to build arbitrary targets
220 within the source directory using the tools.
221 .It Va D
222 Path to the destdir.
223 .It Va O
224 Path to the objects directory for the source tree.
225 .It Va S
226 Path to the source tree.
227 .It Va T
228 Path to the tools.
229 Note that this points to the root of the tools, not their
230 .Pa bin
231 subdirectory.
232 .It Va XO
233 If
234 .Va XSRCDIR
235 is defined, path to the objects directory for the X source tree.
236 .It Va XS
237 If
238 .Va XSRCDIR
239 is defined, path to the X source tree.
240 .El
241 .Pp
242 And the following functions are defined:
243 .Bl -tag -width curobj
244 .It Fn curobj
245 When invoked from a subdirectory of either src or xsrc, prints the path to that
246 same subdirectory within the objects hierarchy.
247 You may use this to reference temporary build files easily when you are working
248 within the source tree as follows:
249 .Bd -literal -offset indent
250 $ cd /usr/src/bin/ls
251 /usr/src/bin/ls$ nbmake-amd64
252 /usr/src/bin/ls$ cd $(curobj)
253 /usr/obj/usr/src/bin/ls$
254 .Ed
255 .El
256 .Ss The fetch command
257 The fetch command downloads or updates the
258 .Nx
259 source trees, which include src and, optionally, xsrc.
260 .Pp
261 If the modules do not exist yet in the locations specified by
262 .Va SRCDIR
263 and
264 .Va XSRCDIR ,
265 this performs an initial CVS checkout of the trees.
266 If the modules exist, this performs a CVS update.
267 .Pp
268 The
269 .Va CVSROOT
270 and
271 .Va CVSTAG
272 variables are used to determine where to get the sources from and whether a
273 particular tag is desired.
274 .Pp
275 The major use of this subcommand is the following.
276 Consider that you wish to use the standard locations of
277 .Pa /usr/src
278 and
279 .Pa /usr/xsrc
280 for your source trees, and that you would like to keep these owned by root
281 while, at the same time, you run your
282 .Nx
283 builds as an unprivileged user.
284 In this situation, you can use the
285 .Sq fetch
286 command as root only, set
287 .Va UPDATE_SOURCES
288 to
289 .Sq false
290 in your user configuration files, and do your builds as another user.
291 .Sh FILES
292 .Bl -tag -width XXXX
293 .It Pa @SYSBUILD_ETCDIR@/
294 Directory containing all system-wide configuration files.
295 .It Pa @SYSBUILD_ETCDIR@/default.conf
296 Default configuration file to load if the user does not have a
297 corresponding
298 .Pa ~/.sysbuild/default.conf
299 file and the
300 .Fl c
301 flag is not provided.
302 .It Pa ~/.sysbuild/
303 Directory containing all user-specific configuration files.
304 .It Pa ~/.sysbuild/default.conf
305 Default configuration file to load when the
306 .Fl c
307 flag is not provided.
308 .El
309 .Sh SEE ALSO
310 .Xr cvs 1 ,
311 .Xr sysbuild4cron 1 ,
312 .Xr sysbuild.conf 5 ,
313 .Xr hier 7 ,
314 .Pa /usr/src/BUILDING
315 .Sh AUTHORS
316 The
317 .Nm
318 utility was developed by
319 .An Julio Merino
320 .Aq jmmv@NetBSD.org .