BUILDING revision 1.54 1 1.1 tv BUILDING(8) NetBSD System Manager's Manual BUILDING(8)
2 1.1 tv
3 1.1 tv NAME
4 1.52 jmc BUILDING -- Procedure for building NetBSD from source code.
5 1.1 tv
6 1.1 tv STATUS
7 1.1 tv This document is a work-in-progress. As such, the information described
8 1.1 tv here may not match the reality of the build system as of this writing.
9 1.1 tv Once this document is completely in sync with reality, this paragraph
10 1.1 tv will be removed.
11 1.1 tv
12 1.44 lukem Discrepancies between this documentation and the current reality of
13 1.44 lukem implementation are noted specially, as with the note below:
14 1.1 tv
15 1.1 tv Note: This document applies only to platforms which use the new toolchain
16 1.15 lukem as indicated by the default setting of TOOLCHAIN_MISSING in <bsd.own.mk>.
17 1.5 tv Platforms which have not yet been switched to the new toolchain should
18 1.5 tv continue building traditionally, using the notes specified in the file
19 1.5 tv UPDATING.
20 1.1 tv
21 1.1 tv REQUIREMENTS
22 1.1 tv NetBSD is designed to be buildable on most POSIX-compliant host systems.
23 1.1 tv The basic build procedure is the same whether compiling natively (on the
24 1.1 tv same NetBSD architecture) or cross compiling (on another architecture or
25 1.1 tv OS).
26 1.1 tv
27 1.1 tv This source tree contains a special subtree, ``tools'', which uses the
28 1.1 tv host system to create a build toolchain for the target architecture. The
29 1.1 tv host system must have at least C and C++ compilers in order to create the
30 1.1 tv toolchain (make is not required); all other tools are created as part of
31 1.53 reed the NetBSD build process. (See the environment variables section below
32 1.53 reed if you need to override or manually select your compilers.)
33 1.1 tv
34 1.1 tv FILES
35 1.1 tv Source tree layout
36 1.17 wiz doc/BUILDING.mdoc
37 1.17 wiz This document (in -mdoc troff format; the original copy).
38 1.1 tv
39 1.2 wiz BUILDING This document (in plaintext).
40 1.1 tv
41 1.48 jmc tools/compat/README
42 1.48 jmc Special notes for cross-hosting a NetBSD build on non-
43 1.48 jmc NetBSD platforms.
44 1.48 jmc
45 1.44 lukem Makefile The main Makefile for NetBSD; should only be run for
46 1.44 lukem native builds with an appropriately up-to-date version of
47 1.1 tv NetBSD make(1). (For building from out-of-date systems or
48 1.1 tv on a non-native host, see the build.sh shell script.)
49 1.1 tv
50 1.1 tv UPDATING Special notes for updating from an earlier revision of
51 1.1 tv NetBSD. It is important to read this file before every
52 1.1 tv build of an updated source tree.
53 1.1 tv
54 1.1 tv build.sh Bourne-compatible shell script used for building the host
55 1.1 tv build tools and the NetBSD system from scratch. Can be
56 1.1 tv used for both native and cross builds, and should be used
57 1.1 tv instead of make(1) for any source tree that is updated and
58 1.1 tv recompiled regularly.
59 1.1 tv
60 1.1 tv crypto/dist/, dist/, gnu/dist/
61 1.1 tv Sources imported verbatim from third parties, without man-
62 1.1 tv gling the existing build structure. Other source trees in
63 1.1 tv bin through usr.sbin use the NetBSD make(1) ``reachover''
64 1.44 lukem Makefile semantics when building these programs for a
65 1.44 lukem native host.
66 1.1 tv
67 1.1 tv distrib/, etc/
68 1.1 tv Sources for items used when making a full release snap-
69 1.27 lukem shot, such as files installed in DESTDIR/etc on the desti-
70 1.27 lukem nation system, boot media, and release notes.
71 1.1 tv
72 1.1 tv regress/ Regression test harness. Can be cross-compiled, but only
73 1.1 tv run natively.
74 1.1 tv
75 1.1 tv sys/ NetBSD kernel sources.
76 1.1 tv
77 1.1 tv tools/ ``Reachover'' build structure for the host build tools.
78 1.1 tv This has a special method of determining out-of-date sta-
79 1.1 tv tus.
80 1.1 tv
81 1.1 tv bin/ ... usr.sbin/
82 1.1 tv Sources to the NetBSD userland (non-kernel) programs. If
83 1.1 tv any of these directories are missing, they will be skipped
84 1.1 tv during the build.
85 1.1 tv
86 1.49 lukem x11/ ``Reachover'' build structure for X11R6; the source is in
87 1.49 lukem X11SRCDIR.
88 1.49 lukem
89 1.1 tv Build tree layout
90 1.1 tv The NetBSD build tree is described in hier(7), and the release layout is
91 1.1 tv described in release(7).
92 1.1 tv
93 1.1 tv CONFIGURATION
94 1.8 lukem Environment variables
95 1.8 lukem Several environment variables control the behaviour of NetBSD builds.
96 1.8 lukem
97 1.53 reed HOST_CC Path name to C compiler used to create the toolchain.
98 1.53 reed
99 1.53 reed HOST_CXX Path name to C++ compiler used to create the toolchain.
100 1.53 reed
101 1.8 lukem MACHINE Machine type.
102 1.8 lukem
103 1.8 lukem MACHINE_ARCH Machine architecture.
104 1.8 lukem
105 1.8 lukem MAKE Path name to invoke make(1) as.
106 1.8 lukem
107 1.8 lukem MAKEFLAGS Flags to invoke make(1) with.
108 1.8 lukem
109 1.8 lukem MAKEOBJDIR Directory to use as the .OBJDIR for the current direc-
110 1.8 lukem tory. Used only if MAKEOBJDIRPREFIX is not defined.
111 1.36 lukem MAKEOBJDIR can only be provided in the environment or
112 1.41 lukem via the -O flag of build.sh.
113 1.8 lukem
114 1.8 lukem MAKEOBJDIRPREFIX Top level directory of the object directory tree. If
115 1.8 lukem this is defined, ${MAKEOBJDIRPREFIX}/${.CURDIR} is used
116 1.8 lukem as the .OBJDIR for the current directory. The current
117 1.8 lukem directory may be read only. MAKEOBJDIRPREFIX can only
118 1.36 lukem be provided in the environment or via the -M flag of
119 1.36 lukem build.sh.
120 1.8 lukem
121 1.1 tv "make" variables
122 1.1 tv Several variables control the behavior of NetBSD builds. Unless other-
123 1.1 tv wise specified, these variables may be set in either the process environ-
124 1.1 tv ment or the make(1) configuration file specified by MAKECONF.
125 1.1 tv
126 1.9 thorpej BUILDID Identifier for the build. The identifier will be appended to
127 1.9 thorpej object directory names, and can be consulted in the make(1)
128 1.9 thorpej configuration file in order to set additional build parame-
129 1.9 thorpej ters, such as compiler flags.
130 1.9 thorpej
131 1.1 tv DESTDIR Directory to contain the built NetBSD system. If set, spe-
132 1.1 tv cial options are passed to the compilation tools to prevent
133 1.1 tv their default use of the host system's /usr/include,
134 1.1 tv /usr/lib, and so forth. This pathname should not end with a
135 1.1 tv slash (/) character (for installation into the system's root
136 1.7 lukem directory, set DESTDIR to an empty string). The directory
137 1.7 lukem must reside on a file system which supports long file names
138 1.7 lukem and hard links.
139 1.1 tv
140 1.1 tv Default: Empty string if USETOOLS is ``yes''; unset other-
141 1.1 tv wise.
142 1.1 tv
143 1.30 lukem Note: build.sh will provide a default of destdir.MACHINE (in
144 1.30 lukem the top-level .OBJDIR) unless run in `expert' mode
145 1.30 lukem
146 1.1 tv MAKECONF The name of the make(1) configuration file. Only settable in
147 1.1 tv the process environment.
148 1.1 tv
149 1.1 tv Default: ``/etc/mk.conf''
150 1.1 tv
151 1.45 lukem MAKEVERBOSE
152 1.45 lukem Level of verbosity of status messages. Supported values:
153 1.45 lukem
154 1.45 lukem 0 No descriptive messages are shown.
155 1.45 lukem
156 1.45 lukem 1 Descriptive messages are shown.
157 1.45 lukem
158 1.45 lukem 2 Descriptive messages (prefixed with a `#') and command
159 1.45 lukem output is not suppressed.
160 1.45 lukem
161 1.45 lukem Default: 2
162 1.45 lukem
163 1.1 tv MKCATPAGES Can be set to ``yes'' or ``no''. Indicates whether prefor-
164 1.1 tv matted plaintext manual pages will be created during a build.
165 1.1 tv
166 1.1 tv Default: ``yes''
167 1.1 tv
168 1.1 tv MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether crypto-
169 1.1 tv graphic code will be included in a build; provided for the
170 1.1 tv benefit of countries that do not allow strong cryptography.
171 1.44 lukem Will not affect use of the standard low-security password
172 1.44 lukem encryption system, crypt(3).
173 1.1 tv
174 1.1 tv Default: ``yes''
175 1.1 tv
176 1.1 tv MKDOC Can be set to ``yes'' or ``no''. Indicates whether system
177 1.44 lukem documentation destined for DESTDIR/usr/share/doc will be
178 1.44 lukem installed during a build.
179 1.1 tv
180 1.1 tv Default: ``yes''
181 1.1 tv
182 1.4 tv MKHOSTOBJ Can be set to ``yes'' or ``no''. If set to ``yes'', then for
183 1.4 tv programs intended to be run on the compile host, the name,
184 1.4 tv release, and architecture of the host operating system will
185 1.4 tv be suffixed to the name of the object directory created by
186 1.4 tv ``make obj''. (This allows multiple host systems to compile
187 1.4 tv NetBSD for a single target.) If set to ``no'', then programs
188 1.4 tv built to be run on the compile host will use the same object
189 1.4 tv directory names as programs built to be run on the target.
190 1.4 tv
191 1.4 tv Default: ``no''
192 1.4 tv
193 1.1 tv MKINFO Can be set to ``yes'' or ``no''. Indicates whether GNU Info
194 1.1 tv files, used for the documentation for most of the compilation
195 1.1 tv tools, will be created and installed during a build.
196 1.1 tv
197 1.1 tv Default: ``yes''
198 1.1 tv
199 1.1 tv MKLINT Can be set to ``yes'' or ``no''. Indicates whether lint(1)
200 1.1 tv will be run against portions of the NetBSD source code during
201 1.1 tv the build, and whether lint libraries will be installed into
202 1.27 lukem DESTDIR/usr/libdata/lint.
203 1.1 tv
204 1.1 tv Default: ``yes''
205 1.1 tv
206 1.1 tv MKMAN Can be set to ``yes'' or ``no''. Indicates whether manual
207 1.1 tv pages will be installed during a build.
208 1.1 tv
209 1.1 tv Default: ``yes''
210 1.1 tv
211 1.1 tv MKNLS Can be set to ``yes'' or ``no''. Indicates whether Native
212 1.44 lukem Language System locale zone files will be compiled and
213 1.44 lukem installed during a build.
214 1.1 tv
215 1.1 tv Default: ``yes''
216 1.1 tv
217 1.1 tv MKOBJ Can be set to ``yes'' or ``no''. Indicates whether object
218 1.1 tv directories will be created when running ``make obj''. If
219 1.1 tv set to ``no'', then all built files will be located inside
220 1.1 tv the regular source tree.
221 1.1 tv
222 1.1 tv Default: ``yes''
223 1.1 tv
224 1.1 tv MKPIC Can be set to ``yes'' or ``no''. Indicates whether shared
225 1.1 tv objects and libraries will be created and installed during a
226 1.1 tv build. If set to ``no'', the entire built system will be
227 1.1 tv statically linked.
228 1.1 tv
229 1.1 tv Default: Platform dependent. As of this writing, all plat-
230 1.1 tv forms except sh3 default to ``yes''.
231 1.1 tv
232 1.1 tv MKPICINSTALL
233 1.1 tv Can be set to ``yes'' or ``no''. Indicates whether the ar(1)
234 1.44 lukem format libraries (lib*_pic.a), used to generate shared
235 1.44 lukem libraries, are installed during a build.
236 1.1 tv
237 1.1 tv Default: ``yes''
238 1.1 tv
239 1.1 tv MKPROFILE Can be set to ``yes'' or ``no''. Indicates whether profiled
240 1.1 tv libraries (lib*_p.a) will be built and installed during a
241 1.1 tv build.
242 1.1 tv
243 1.1 tv Default: ``yes''; however, some platforms turn off MKPROFILE
244 1.1 tv by default at times due to toolchain problems with profiled
245 1.1 tv code.
246 1.1 tv
247 1.1 tv MKSHARE Can be set to ``yes'' or ``no''. Indicates whether files
248 1.44 lukem destined to reside in DESTDIR/usr/share will be built and
249 1.44 lukem installed during a build. If set to ``no'', then all of
250 1.27 lukem MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
251 1.27 lukem ``no'' unconditionally.
252 1.1 tv
253 1.1 tv Default: ``yes''
254 1.1 tv
255 1.50 wiz MKTTINTERP Can be set to ``yes'' or ``no''. For X builds, decides if
256 1.50 wiz the TrueType bytecode interpreter is turned on. See
257 1.50 wiz http://www.freetype.org/patents.html for details.
258 1.50 wiz
259 1.50 wiz Default: ``no''
260 1.50 wiz
261 1.44 lukem MKUNPRIVED Can be set to ``yes'' or ``no''. Indicates whether an
262 1.44 lukem unprivileged install will occur. The user, group, permis-
263 1.52 jmc sions, and file flags, will not be set on the installed
264 1.52 jmc items; instead the information will be appended to a file
265 1.52 jmc called METALOG in DESTDIR. The contents of METALOG are used
266 1.52 jmc during the generation of the distribution tar files to ensure
267 1.52 jmc that the appropriate file ownership is stored.
268 1.38 lukem
269 1.38 lukem Default: ``no''
270 1.38 lukem
271 1.44 lukem MKUPDATE Can be set to ``yes'' or ``no''. Indicates whether all
272 1.44 lukem install operations intended to write to DESTDIR will compare
273 1.38 lukem file timestamps before installing, and skip the install phase
274 1.44 lukem if the destination files are up-to-date. This also has
275 1.44 lukem implications on full builds (see next subsection).
276 1.38 lukem
277 1.38 lukem Default: ``no''
278 1.38 lukem
279 1.49 lukem MKX11 Can be set to ``yes'' or ``no''. Indicates whether X11R6 is
280 1.49 lukem built from X11SRCDIR.
281 1.49 lukem
282 1.49 lukem Default: ``no''
283 1.49 lukem
284 1.1 tv TOOLDIR Directory to hold the host tools, once built. This directory
285 1.1 tv should be unique to a given host system and NetBSD source
286 1.1 tv tree. (However, multiple targets may share the same TOOLDIR;
287 1.1 tv the target-dependent files have unique names.) If unset, a
288 1.1 tv default based on the uname(1) information of the host plat-
289 1.39 lukem form will be created in the .OBJDIR of src.
290 1.1 tv
291 1.1 tv Default: Unset.
292 1.1 tv
293 1.1 tv USETOOLS Indicates whether the tools specified by TOOLDIR should be
294 1.1 tv used as part of a build in progress. Must be set to ``yes''
295 1.1 tv if cross-compiling.
296 1.1 tv
297 1.1 tv yes Use the tools from TOOLDIR.
298 1.1 tv
299 1.1 tv no Do not use the tools from TOOLDIR, but refuse to build
300 1.1 tv native compilation tool components that are version-
301 1.1 tv specific for that tool.
302 1.1 tv
303 1.1 tv never Do not use the tools from TOOLDIR, even when building
304 1.1 tv native tool components. This is similar to the tradi-
305 1.1 tv tional NetBSD build method, but does not verify that
306 1.1 tv the compilation tools in use are up-to-date enough in
307 1.1 tv order to build the tree successfully. This may cause
308 1.1 tv build or runtime problems when building the whole
309 1.1 tv NetBSD source tree.
310 1.1 tv
311 1.1 tv Default: ``yes'' if building all or part of a whole NetBSD
312 1.1 tv source tree (detected automatically); ``no'' otherwise (to
313 1.44 lukem preserve traditional semantics of the <bsd.*.mk> make(1)
314 1.44 lukem include files).
315 1.1 tv
316 1.49 lukem X11SRCDIR Directory containing the X11R6 source. The main X11R6 source
317 1.49 lukem is found in X11SRCDIR/xfree/xc.
318 1.49 lukem
319 1.49 lukem Default: ``/usr/xsrc''
320 1.49 lukem
321 1.1 tv "make" variables for full builds
322 1.7 lukem These variables only affect the top level ``Makefile'' and do not affect
323 1.7 lukem manually building subtrees of the NetBSD source code.
324 1.1 tv
325 1.20 lukem INSTALLWORLDDIR Location for the ``make installworld'' target to install
326 1.20 lukem to.
327 1.1 tv
328 1.20 lukem Default: ``/''
329 1.1 tv
330 1.44 lukem MKOBJDIRS Can be set to ``yes'' or ``no''. Indicates whether
331 1.44 lukem object directories will be created automatically (via a
332 1.20 lukem ``make obj'' pass) at the start of a build.
333 1.1 tv
334 1.34 lukem Default: ``no''
335 1.1 tv
336 1.38 lukem MKUPDATE Can be set to ``yes'' or ``no''. If set, then in addi-
337 1.38 lukem tion to the effects described for MKUPDATE=yes above,
338 1.38 lukem this implies the effects of NOCLEANDIR (i.e., ``make
339 1.38 lukem cleandir'' is avoided).
340 1.38 lukem
341 1.38 lukem Default: ``no''
342 1.38 lukem
343 1.20 lukem NBUILDJOBS Now obsolete. Use the make(1) option -j, instead (see
344 1.20 lukem below)
345 1.1 tv
346 1.20 lukem Default: Unset.
347 1.1 tv
348 1.20 lukem NOCLEANDIR If set, avoids the ``make cleandir'' phase of a full
349 1.20 lukem build. This has the effect of allowing only changed
350 1.20 lukem files in a source tree to be recompiled. This can speed
351 1.20 lukem up builds when updating only a few files in the tree.
352 1.1 tv
353 1.20 lukem Default: Unset.
354 1.1 tv
355 1.20 lukem NODISTRIBDIRS If set, avoids the ``make distrib-dirs'' phase of a full
356 1.20 lukem build. This skips running mtree(8) on DESTDIR, useful
357 1.20 lukem on systems where building as an unprivileged user, or
358 1.20 lukem where it is known that the system-wide mtree files have
359 1.20 lukem not changed.
360 1.1 tv
361 1.20 lukem Default: Unset.
362 1.1 tv
363 1.20 lukem NOINCLUDES If set, avoids the ``make includes'' phase of a full
364 1.20 lukem build. This has the effect of preventing make(1) from
365 1.44 lukem thinking that some programs are out-of-date simply
366 1.44 lukem because the system include files have changed. However,
367 1.20 lukem this option should not be used when updating the entire
368 1.20 lukem NetBSD source tree arbitrarily; it is suggested to use
369 1.38 lukem MKUPDATE=yes in that case.
370 1.1 tv
371 1.20 lukem Default: Unset.
372 1.1 tv
373 1.20 lukem RELEASEDIR If set, specifies the directory to which a release(7)
374 1.20 lukem layout will be written at the end of a ``make release''.
375 1.20 lukem
376 1.20 lukem Default: Unset.
377 1.20 lukem
378 1.30 lukem Note: build.sh will provide a default of releasedir (in
379 1.30 lukem the top-level .OBJDIR) unless run in `expert' mode
380 1.30 lukem
381 1.1 tv BUILDING
382 1.1 tv "make" command line options
383 1.52 jmc This is not a summary of all the options available to make(1); only the
384 1.52 jmc options used most frequently with NetBSD builds are listed here.
385 1.1 tv
386 1.10 sommerfe -j njob Run up to njob make(1) subjobs in parallel. Makefiles should
387 1.52 jmc use .WAIT or have explicit dependencies as necessary to
388 1.44 lukem enforce build ordering. If you see build failures with -j,
389 1.10 sommerfe please save complete build logs so the failures can be ana-
390 1.10 sommerfe lyzed.
391 1.10 sommerfe
392 1.1 tv -m dir Specify the default directory for searching for system Make-
393 1.1 tv file segments, mainly the <bsd.*.mk> files. When building any
394 1.1 tv full NetBSD source tree, this should be set to the
395 1.1 tv ``share/mk'' directory in the source tree. (This is set auto-
396 1.1 tv matically when building from the top level.)
397 1.1 tv
398 1.1 tv -n Display the commands that would have been executed, but do not
399 1.1 tv actually execute them. This will still cause recursion to
400 1.1 tv take place.
401 1.1 tv
402 1.47 zuntum -V var Print make(1)'s idea of the value of var. Does not build any
403 1.1 tv targets.
404 1.1 tv
405 1.1 tv var=value Set the variable var to value, overriding any setting speci-
406 1.1 tv fied by the process environment, the MAKECONF configuration
407 1.1 tv file, or the system Makefile segments.
408 1.1 tv
409 1.1 tv "make" targets
410 1.1 tv These default targets may be built by running make(1) in any subtree of
411 1.1 tv the NetBSD source code. It is recommended that none of these be used
412 1.1 tv from the top level Makefile; as a specific exception, ``make obj'' and
413 1.1 tv ``make cleandir'' are useful in that context.
414 1.1 tv
415 1.1 tv all Build programs, libraries, and preformatted documentation.
416 1.1 tv
417 1.1 tv clean Remove program and library object code files.
418 1.1 tv
419 1.44 lukem cleandir Same as clean, but also remove preformatted documentation,
420 1.44 lukem dependency files generated by ``make depend'', and any other
421 1.49 lukem files known to be created at build time.
422 1.1 tv
423 1.44 lukem depend Create dependency files (.depend) containing more detailed
424 1.44 lukem information about the dependencies of source code on header
425 1.1 tv files. Allows programs to be recompiled automatically when a
426 1.1 tv dependency changes.
427 1.1 tv
428 1.1 tv dependall Does a ``make depend'' immediately followed by a ``make all''.
429 1.10 sommerfe This improves cache locality of the build since both passes
430 1.10 sommerfe read the source files in their entirety.
431 1.1 tv
432 1.49 lukem distclean Synonym for cleandir.
433 1.49 lukem
434 1.44 lukem includes Build and install system header files. Typically needed
435 1.44 lukem before any system libraries or programs can be built.
436 1.1 tv
437 1.1 tv install Install programs, libraries, and documentation into DESTDIR.
438 1.27 lukem Few files will be installed to DESTDIR/dev, DESTDIR/etc,
439 1.27 lukem DESTDIR/root or DESTDIR/var in order to prevent user supplied
440 1.27 lukem configuration data from being overwritten.
441 1.1 tv
442 1.1 tv lint Run lint(1) against the C source code, where appropriate, and
443 1.1 tv generate system-installed lint libraries.
444 1.1 tv
445 1.1 tv obj Create object directories to be used for built files, instead
446 1.1 tv of building directly in the source tree.
447 1.1 tv
448 1.1 tv tags Create ctags(1) searchable function lists usable by the ex(1)
449 1.1 tv and vi(1) text editors.
450 1.1 tv
451 1.1 tv "make" targets for the top level
452 1.1 tv Additional make(1) targets are usable specifically from the top source
453 1.1 tv level to facilitate building the entire NetBSD source tree.
454 1.1 tv
455 1.20 lukem build Build the entire NetBSD system. This orders portions of
456 1.20 lukem the source tree such that prerequisites will be built in
457 1.20 lukem the proper order.
458 1.20 lukem
459 1.20 lukem distribution Do a ``make build'', and then install a full distribution
460 1.27 lukem into DESTDIR, including files in DESTDIR/dev, DESTDIR/etc,
461 1.27 lukem DESTDIR/root and DESTDIR/var.
462 1.20 lukem
463 1.20 lukem buildworld As per ``make distribution'', except that it ensures that
464 1.20 lukem DESTDIR is not the root directory.
465 1.20 lukem
466 1.20 lukem installworld Install the distribution from DESTDIR to INSTALLWORLDDIR
467 1.20 lukem (which defaults to the root directory). Ensures that
468 1.52 jmc INSTALLWORLDDIR is not the root directory if cross compil-
469 1.20 lukem ing.
470 1.20 lukem
471 1.20 lukem Note: It is highly recommended that you upgrade your kernel
472 1.20 lukem and reboot before performing this operation.
473 1.20 lukem
474 1.25 lukem sets Create distribution sets from DESTDIR into
475 1.25 lukem RELEASEDIR/MACHINE/binary/sets. Should be run after ``make
476 1.25 lukem distribution'' (as ``make build'' does not install all of
477 1.25 lukem the required files).
478 1.25 lukem
479 1.31 lukem sourcesets Create source sets of the source tree into
480 1.31 lukem RELEASEDIR/source/sets.
481 1.31 lukem
482 1.54 apb syspkgs Create syspkgs from DESTDIR into
483 1.54 apb RELEASEDIR/MACHINE/binary/syspkgs. Should be run after
484 1.54 apb ``make distribution'' (as ``make build'' does not install
485 1.54 apb all of the required files).
486 1.54 apb
487 1.44 lukem release Do a ``make distribution'', build kernels, distribution
488 1.44 lukem media, and install sets (this as per ``make sets''), and
489 1.44 lukem then package the system into a standard release layout as
490 1.44 lukem described by release(7). This requires that RELEASEDIR be
491 1.25 lukem set (see above).
492 1.1 tv
493 1.1 tv regression-tests
494 1.20 lukem Can only be run after building the regression tests in the
495 1.20 lukem directory ``regress''. Runs the compiled regression tests
496 1.20 lukem on the local host.
497 1.1 tv
498 1.1 tv The "build.sh" script
499 1.1 tv This script file is a Bourne shell script designed to build the entire
500 1.1 tv NetBSD system on any host with a Bourne shell in /bin/sh, including many
501 1.1 tv that are not POSIX compliant. Note that if a host system's /bin/sh is
502 1.1 tv unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
503 1.1 tv a usable alternative.
504 1.1 tv
505 1.1 tv All cross-compile builds, and most native builds, of the entire system
506 1.1 tv should make use of build.sh rather than just running ``make''. This way,
507 1.1 tv the make(1) program will be bootstrapped properly, in case the host sys-
508 1.1 tv tem has an older or incompatible ``make'' program.
509 1.1 tv
510 1.1 tv When compiling the entire system via build.sh, many make(1) variables are
511 1.1 tv set for you in order to help encapsulate the build process. In the list
512 1.1 tv of options below, variables that are automatically set by build.sh are
513 1.1 tv noted where applicable.
514 1.1 tv
515 1.22 lukem The following operations are supported by build.sh:
516 1.22 lukem
517 1.44 lukem build Build the system as per ``make build''. This option
518 1.44 lukem implies the obj and tools operations.
519 1.22 lukem
520 1.22 lukem distribution Build a full distribution as per ``make distribution''.
521 1.22 lukem This option implies the build operation.
522 1.22 lukem
523 1.22 lukem release Build a full release as per ``make release''. This option
524 1.22 lukem implies the distribution operation.
525 1.22 lukem
526 1.23 lukem makewrapper Create the nbmake-MACHINE wrapper. This operation is auto-
527 1.23 lukem matically performed for any of the other operations.
528 1.23 lukem
529 1.22 lukem obj Perform ``make obj''.
530 1.22 lukem
531 1.22 lukem tools Build and install the host tools from src/tools.
532 1.22 lukem
533 1.35 lukem install=idir Install the contents of DESTDIR to idir, using ``make
534 1.35 lukem installworld''.
535 1.35 lukem
536 1.22 lukem kernel=kconf Build a new kernel. The kconf argument is the name of a
537 1.54 apb configuration file suitable for use by config(1). If kconf
538 1.22 lukem does not contain any `/' characters, the configuration file
539 1.22 lukem is expected to be found in the KERNCONFDIR directory, which
540 1.22 lukem is typically sys/arch/MACHINE/conf. The new kernel will be
541 1.22 lukem built in a subdirectory of KERNOBJDIR, which is typically
542 1.22 lukem sys/arch/MACHINE/compile or an associated object directory.
543 1.22 lukem In order to ensure that the kernel is built using up-to-
544 1.22 lukem date tools, it is strongly recommended that the tools be
545 1.22 lukem rebuilt (using the tools operation).
546 1.22 lukem
547 1.35 lukem releasekernel=kconf
548 1.35 lukem Install a gzip(1)ed copy of the kernel built by
549 1.35 lukem kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
550 1.44 lukem as netbsd-kconf.gz, although the ``netbsd'' prefix is
551 1.44 lukem determined from the ``config'' directives in kconf.
552 1.24 lukem
553 1.24 lukem sets Perform ``make sets''.
554 1.31 lukem
555 1.31 lukem sourcesets Perform ``make sourcesets''.
556 1.22 lukem
557 1.54 apb syspkgs Perform ``make syspkgs''.
558 1.54 apb
559 1.51 wiz The following command line options alter the behaviour of the build.sh
560 1.51 wiz operations described above:
561 1.1 tv
562 1.1 tv -a arch Set the value of MACHINE_ARCH to arch.
563 1.9 thorpej
564 1.9 thorpej -B buildid
565 1.9 thorpej Set the value of BUILDID to buildid. This will also append the
566 1.9 thorpej build idenfitier to the name of the ``make'' wrapper script so
567 1.37 lukem that the resulting name is of the form
568 1.37 lukem ``nbmake-MACHINE-BUILDID''.
569 1.1 tv
570 1.18 lukem -D dest Set the value of DESTDIR to dest.
571 1.18 lukem
572 1.23 lukem -E Set `expert' mode. This overrides various sanity checks, and
573 1.23 lukem allows: DESTDIR does not have to be set to a non-root path for
574 1.38 lukem builds, and MKUNPRIVED=yes does not have to be set when build-
575 1.38 lukem ing as a non-root user.
576 1.23 lukem
577 1.23 lukem Note: It is highly recommended that you know what you are doing
578 1.23 lukem when you use this option.
579 1.19 lukem
580 1.51 wiz -h Print a help message.
581 1.51 wiz
582 1.10 sommerfe -j njob Passed through to make(1). Makefiles should use .WAIT or have
583 1.10 sommerfe explicit dependancies as necessary to enforce build ordering.
584 1.10 sommerfe If you see build failures with -j, please save complete build
585 1.10 sommerfe logs so the failures can be analyzed.
586 1.1 tv
587 1.40 lukem -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR.
588 1.18 lukem
589 1.1 tv -m mach Set the value of MACHINE to mach. This will also override any
590 1.1 tv value of MACHINE_ARCH in the process environment with a value
591 1.33 lukem deduced from mach, unless -a is specified, or mach is a special
592 1.33 lukem case listed below. All cross builds require -m, but if unset
593 1.33 lukem on a NetBSD host, the host's value of MACHINE will be detected
594 1.33 lukem and used automatically.
595 1.33 lukem
596 1.33 lukem Some machines support multiple values for MACHINE_ARCH. For a
597 1.33 lukem given value of mach, the following MACHINE and MACHINE_ARCH
598 1.33 lukem values will result:
599 1.33 lukem
600 1.33 lukem mach MACHINE MACHINE_ARCH
601 1.33 lukem evbmips evbmips (not set)
602 1.33 lukem evbmips-eb evbmips mipseb
603 1.33 lukem evbmips-el evbmips mipsel
604 1.33 lukem evbsh3 evbsh3 (not set)
605 1.33 lukem evbsh3-eb evbsh3 sh3eb
606 1.33 lukem evbsh3-el evbsh3 sh3el
607 1.33 lukem sbmips sbmips (not set)
608 1.33 lukem sbmips-eb sbmips mipseb
609 1.33 lukem sbmips-el sbmips mipsel
610 1.1 tv
611 1.45 lukem -N noiselevel
612 1.46 lukem Set the ``noisyness'' level of the build, by setting
613 1.46 lukem MAKEVERBOSE to noiselevel.
614 1.45 lukem
615 1.1 tv -n Show the commands that would be executed by build.sh, but do
616 1.1 tv not make any changes. This is similar in concept to ``make
617 1.1 tv -n''.
618 1.1 tv
619 1.18 lukem -O obj Create an appropriate transform macro for MAKEOBJDIR that will
620 1.18 lukem place the built object files under obj. For instance, a set-
621 1.18 lukem ting of /usr/obj will place build-time files under
622 1.40 lukem /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth.
623 1.40 lukem Unsets MAKEOBJDIRPREFIX.
624 1.18 lukem
625 1.34 lukem -o Set the value of MKOBJDIRS to ``no''. Otherwise, it will be
626 1.34 lukem automatically set to ``yes'' (which is opposite to the default
627 1.34 lukem behaviour).
628 1.1 tv
629 1.22 lukem -R rel Set the value of RELEASEDIR to rel.
630 1.18 lukem
631 1.1 tv -r Remove the contents of DESTDIR and TOOLDIR before building
632 1.1 tv (provides a clean starting point). This will skip deleting
633 1.1 tv DESTDIR if building on a native system to the root directory.
634 1.1 tv
635 1.18 lukem -T tools Set the value of TOOLDIR to tools. If set, the bootstrap
636 1.18 lukem ``make'' will only be rebuilt as needed (when the source files
637 1.18 lukem for make(1) change).
638 1.18 lukem
639 1.38 lukem -U Set MKUNPRIVED=yes.
640 1.18 lukem
641 1.38 lukem -u Set MKUPDATE=yes.
642 1.1 tv
643 1.21 lukem -V var=[value]
644 1.40 lukem Set the environment variable var to an optional value. This is
645 1.40 lukem propagated to the nbmake wrapper.
646 1.21 lukem
647 1.1 tv -w wrapper
648 1.1 tv Create the nbmake wrapper script (see below) in a custom loca-
649 1.1 tv tion, specified by wrapper. This allows, for instance, to
650 1.1 tv place the wrapper in PATH automatically. Note that wrapper is
651 1.1 tv the full name of the file, not just a directory name.
652 1.1 tv
653 1.49 lukem -X x11src
654 1.49 lukem Set the value of X11SRCDIR to x11src.
655 1.49 lukem
656 1.49 lukem -x Set MKX11=yes.
657 1.49 lukem
658 1.40 lukem -Z var Unset ("zap") the environment variable var. This is propagated
659 1.40 lukem to the nbmake wrapper.
660 1.40 lukem
661 1.1 tv The "nbmake-MACHINE" wrapper script
662 1.1 tv If using the build.sh script to build NetBSD, a nbmake-MACHINE script
663 1.1 tv will be created in TOOLDIR/bin upon the first build to assist in building
664 1.1 tv subtrees on a cross-compile host.
665 1.1 tv
666 1.1 tv nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
667 1.1 tv the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
668 1.1 tv eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
669 1.40 lukem build.sh will also set variables specified with -V, and unset variables
670 1.40 lukem specified with -Z.
671 1.40 lukem
672 1.1 tv This script can be symlinked into a directory listed in PATH, or called
673 1.1 tv with an absolute path.
674 1.1 tv
675 1.16 lukem EXAMPLES
676 1.44 lukem 1. % ./build.sh tools kernel=GENERIC
677 1.28 lukem
678 1.28 lukem Build a new toolchain, and use the new toolchain to configure and
679 1.28 lukem build a new GENERIC kernel.
680 1.28 lukem
681 1.44 lukem 2. % ./build.sh -U distribution
682 1.28 lukem
683 1.30 lukem Using unprivileged mode, build a complete distribution to a DESTDIR
684 1.30 lukem directory that build.sh selects (and will display).
685 1.28 lukem
686 1.43 martti 3. # ./build.sh -U install=/
687 1.28 lukem
688 1.29 lukem As root, install to / the distribution that was built by example 2.
689 1.29 lukem Even though this is run as root, -U is required so that the permis-
690 1.30 lukem sions stored in DESTDIR/METALOG are correctly applied to the files
691 1.30 lukem as they're copied to /.
692 1.28 lukem
693 1.44 lukem 4. % ./build.sh -U -u release
694 1.28 lukem
695 1.30 lukem Using unprivileged mode, build a complete release to DESTDIR and
696 1.30 lukem RELEASEDIR directories that build.sh selects (and will display).
697 1.38 lukem MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
698 1.38 lukem if this is run after example 2, it doesn't need to redo that portion
699 1.38 lukem of the release build.
700 1.16 lukem
701 1.10 sommerfe OBSOLETE VARIABLES
702 1.15 lukem NBUILDJOBS Use the make(1) option -j, instead.
703 1.15 lukem
704 1.15 lukem USE_NEW_TOOLCHAIN
705 1.15 lukem The new toolchain is now the default. To disable, use
706 1.15 lukem TOOLCHAIN_MISSING=yes.
707 1.10 sommerfe
708 1.1 tv SEE ALSO
709 1.1 tv make(1), hier(7), release(7)
710 1.1 tv
711 1.1 tv HISTORY
712 1.15 lukem The build.sh based build scheme was introduced for NetBSD 1.6 as
713 1.15 lukem USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
714 1.1 tv
715 1.1 tv BUGS
716 1.15 lukem A few platforms are not yet using this build system.
717 1.1 tv
718 1.49 lukem NetBSD February 6, 2003 NetBSD
719