BUILDING revision 1.53 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.44 lukem release Do a ``make distribution'', build kernels, distribution
483 1.44 lukem media, and install sets (this as per ``make sets''), and
484 1.44 lukem then package the system into a standard release layout as
485 1.44 lukem described by release(7). This requires that RELEASEDIR be
486 1.25 lukem set (see above).
487 1.1 tv
488 1.1 tv regression-tests
489 1.20 lukem Can only be run after building the regression tests in the
490 1.20 lukem directory ``regress''. Runs the compiled regression tests
491 1.20 lukem on the local host.
492 1.1 tv
493 1.1 tv The "build.sh" script
494 1.1 tv This script file is a Bourne shell script designed to build the entire
495 1.1 tv NetBSD system on any host with a Bourne shell in /bin/sh, including many
496 1.1 tv that are not POSIX compliant. Note that if a host system's /bin/sh is
497 1.1 tv unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
498 1.1 tv a usable alternative.
499 1.1 tv
500 1.1 tv All cross-compile builds, and most native builds, of the entire system
501 1.1 tv should make use of build.sh rather than just running ``make''. This way,
502 1.1 tv the make(1) program will be bootstrapped properly, in case the host sys-
503 1.1 tv tem has an older or incompatible ``make'' program.
504 1.1 tv
505 1.1 tv When compiling the entire system via build.sh, many make(1) variables are
506 1.1 tv set for you in order to help encapsulate the build process. In the list
507 1.1 tv of options below, variables that are automatically set by build.sh are
508 1.1 tv noted where applicable.
509 1.1 tv
510 1.22 lukem The following operations are supported by build.sh:
511 1.22 lukem
512 1.44 lukem build Build the system as per ``make build''. This option
513 1.44 lukem implies the obj and tools operations.
514 1.22 lukem
515 1.22 lukem distribution Build a full distribution as per ``make distribution''.
516 1.22 lukem This option implies the build operation.
517 1.22 lukem
518 1.22 lukem release Build a full release as per ``make release''. This option
519 1.22 lukem implies the distribution operation.
520 1.22 lukem
521 1.23 lukem makewrapper Create the nbmake-MACHINE wrapper. This operation is auto-
522 1.23 lukem matically performed for any of the other operations.
523 1.23 lukem
524 1.22 lukem obj Perform ``make obj''.
525 1.22 lukem
526 1.22 lukem tools Build and install the host tools from src/tools.
527 1.22 lukem
528 1.35 lukem install=idir Install the contents of DESTDIR to idir, using ``make
529 1.35 lukem installworld''.
530 1.35 lukem
531 1.22 lukem kernel=kconf Build a new kernel. The kconf argument is the name of a
532 1.22 lukem configuration file suitable for use by config(8). If kconf
533 1.22 lukem does not contain any `/' characters, the configuration file
534 1.22 lukem is expected to be found in the KERNCONFDIR directory, which
535 1.22 lukem is typically sys/arch/MACHINE/conf. The new kernel will be
536 1.22 lukem built in a subdirectory of KERNOBJDIR, which is typically
537 1.22 lukem sys/arch/MACHINE/compile or an associated object directory.
538 1.22 lukem In order to ensure that the kernel is built using up-to-
539 1.22 lukem date tools, it is strongly recommended that the tools be
540 1.22 lukem rebuilt (using the tools operation).
541 1.22 lukem
542 1.35 lukem releasekernel=kconf
543 1.35 lukem Install a gzip(1)ed copy of the kernel built by
544 1.35 lukem kernel=kconf into RELEASEDIR/MACHINE/binary/kernel, usually
545 1.44 lukem as netbsd-kconf.gz, although the ``netbsd'' prefix is
546 1.44 lukem determined from the ``config'' directives in kconf.
547 1.24 lukem
548 1.24 lukem sets Perform ``make sets''.
549 1.31 lukem
550 1.31 lukem sourcesets Perform ``make sourcesets''.
551 1.22 lukem
552 1.51 wiz The following command line options alter the behaviour of the build.sh
553 1.51 wiz operations described above:
554 1.1 tv
555 1.1 tv -a arch Set the value of MACHINE_ARCH to arch.
556 1.9 thorpej
557 1.9 thorpej -B buildid
558 1.9 thorpej Set the value of BUILDID to buildid. This will also append the
559 1.9 thorpej build idenfitier to the name of the ``make'' wrapper script so
560 1.37 lukem that the resulting name is of the form
561 1.37 lukem ``nbmake-MACHINE-BUILDID''.
562 1.1 tv
563 1.18 lukem -D dest Set the value of DESTDIR to dest.
564 1.18 lukem
565 1.23 lukem -E Set `expert' mode. This overrides various sanity checks, and
566 1.23 lukem allows: DESTDIR does not have to be set to a non-root path for
567 1.38 lukem builds, and MKUNPRIVED=yes does not have to be set when build-
568 1.38 lukem ing as a non-root user.
569 1.23 lukem
570 1.23 lukem Note: It is highly recommended that you know what you are doing
571 1.23 lukem when you use this option.
572 1.19 lukem
573 1.51 wiz -h Print a help message.
574 1.51 wiz
575 1.10 sommerfe -j njob Passed through to make(1). Makefiles should use .WAIT or have
576 1.10 sommerfe explicit dependancies as necessary to enforce build ordering.
577 1.10 sommerfe If you see build failures with -j, please save complete build
578 1.10 sommerfe logs so the failures can be analyzed.
579 1.1 tv
580 1.40 lukem -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR.
581 1.18 lukem
582 1.1 tv -m mach Set the value of MACHINE to mach. This will also override any
583 1.1 tv value of MACHINE_ARCH in the process environment with a value
584 1.33 lukem deduced from mach, unless -a is specified, or mach is a special
585 1.33 lukem case listed below. All cross builds require -m, but if unset
586 1.33 lukem on a NetBSD host, the host's value of MACHINE will be detected
587 1.33 lukem and used automatically.
588 1.33 lukem
589 1.33 lukem Some machines support multiple values for MACHINE_ARCH. For a
590 1.33 lukem given value of mach, the following MACHINE and MACHINE_ARCH
591 1.33 lukem values will result:
592 1.33 lukem
593 1.33 lukem mach MACHINE MACHINE_ARCH
594 1.33 lukem evbmips evbmips (not set)
595 1.33 lukem evbmips-eb evbmips mipseb
596 1.33 lukem evbmips-el evbmips mipsel
597 1.33 lukem evbsh3 evbsh3 (not set)
598 1.33 lukem evbsh3-eb evbsh3 sh3eb
599 1.33 lukem evbsh3-el evbsh3 sh3el
600 1.33 lukem sbmips sbmips (not set)
601 1.33 lukem sbmips-eb sbmips mipseb
602 1.33 lukem sbmips-el sbmips mipsel
603 1.1 tv
604 1.45 lukem -N noiselevel
605 1.46 lukem Set the ``noisyness'' level of the build, by setting
606 1.46 lukem MAKEVERBOSE to noiselevel.
607 1.45 lukem
608 1.1 tv -n Show the commands that would be executed by build.sh, but do
609 1.1 tv not make any changes. This is similar in concept to ``make
610 1.1 tv -n''.
611 1.1 tv
612 1.18 lukem -O obj Create an appropriate transform macro for MAKEOBJDIR that will
613 1.18 lukem place the built object files under obj. For instance, a set-
614 1.18 lukem ting of /usr/obj will place build-time files under
615 1.40 lukem /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth.
616 1.40 lukem Unsets MAKEOBJDIRPREFIX.
617 1.18 lukem
618 1.34 lukem -o Set the value of MKOBJDIRS to ``no''. Otherwise, it will be
619 1.34 lukem automatically set to ``yes'' (which is opposite to the default
620 1.34 lukem behaviour).
621 1.1 tv
622 1.22 lukem -R rel Set the value of RELEASEDIR to rel.
623 1.18 lukem
624 1.1 tv -r Remove the contents of DESTDIR and TOOLDIR before building
625 1.1 tv (provides a clean starting point). This will skip deleting
626 1.1 tv DESTDIR if building on a native system to the root directory.
627 1.1 tv
628 1.18 lukem -T tools Set the value of TOOLDIR to tools. If set, the bootstrap
629 1.18 lukem ``make'' will only be rebuilt as needed (when the source files
630 1.18 lukem for make(1) change).
631 1.18 lukem
632 1.38 lukem -U Set MKUNPRIVED=yes.
633 1.18 lukem
634 1.38 lukem -u Set MKUPDATE=yes.
635 1.1 tv
636 1.21 lukem -V var=[value]
637 1.40 lukem Set the environment variable var to an optional value. This is
638 1.40 lukem propagated to the nbmake wrapper.
639 1.21 lukem
640 1.1 tv -w wrapper
641 1.1 tv Create the nbmake wrapper script (see below) in a custom loca-
642 1.1 tv tion, specified by wrapper. This allows, for instance, to
643 1.1 tv place the wrapper in PATH automatically. Note that wrapper is
644 1.1 tv the full name of the file, not just a directory name.
645 1.1 tv
646 1.49 lukem -X x11src
647 1.49 lukem Set the value of X11SRCDIR to x11src.
648 1.49 lukem
649 1.49 lukem -x Set MKX11=yes.
650 1.49 lukem
651 1.40 lukem -Z var Unset ("zap") the environment variable var. This is propagated
652 1.40 lukem to the nbmake wrapper.
653 1.40 lukem
654 1.1 tv The "nbmake-MACHINE" wrapper script
655 1.1 tv If using the build.sh script to build NetBSD, a nbmake-MACHINE script
656 1.1 tv will be created in TOOLDIR/bin upon the first build to assist in building
657 1.1 tv subtrees on a cross-compile host.
658 1.1 tv
659 1.1 tv nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
660 1.1 tv the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
661 1.1 tv eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
662 1.40 lukem build.sh will also set variables specified with -V, and unset variables
663 1.40 lukem specified with -Z.
664 1.40 lukem
665 1.1 tv This script can be symlinked into a directory listed in PATH, or called
666 1.1 tv with an absolute path.
667 1.1 tv
668 1.16 lukem EXAMPLES
669 1.44 lukem 1. % ./build.sh tools kernel=GENERIC
670 1.28 lukem
671 1.28 lukem Build a new toolchain, and use the new toolchain to configure and
672 1.28 lukem build a new GENERIC kernel.
673 1.28 lukem
674 1.44 lukem 2. % ./build.sh -U distribution
675 1.28 lukem
676 1.30 lukem Using unprivileged mode, build a complete distribution to a DESTDIR
677 1.30 lukem directory that build.sh selects (and will display).
678 1.28 lukem
679 1.43 martti 3. # ./build.sh -U install=/
680 1.28 lukem
681 1.29 lukem As root, install to / the distribution that was built by example 2.
682 1.29 lukem Even though this is run as root, -U is required so that the permis-
683 1.30 lukem sions stored in DESTDIR/METALOG are correctly applied to the files
684 1.30 lukem as they're copied to /.
685 1.28 lukem
686 1.44 lukem 4. % ./build.sh -U -u release
687 1.28 lukem
688 1.30 lukem Using unprivileged mode, build a complete release to DESTDIR and
689 1.30 lukem RELEASEDIR directories that build.sh selects (and will display).
690 1.38 lukem MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
691 1.38 lukem if this is run after example 2, it doesn't need to redo that portion
692 1.38 lukem of the release build.
693 1.16 lukem
694 1.10 sommerfe OBSOLETE VARIABLES
695 1.15 lukem NBUILDJOBS Use the make(1) option -j, instead.
696 1.15 lukem
697 1.15 lukem USE_NEW_TOOLCHAIN
698 1.15 lukem The new toolchain is now the default. To disable, use
699 1.15 lukem TOOLCHAIN_MISSING=yes.
700 1.10 sommerfe
701 1.1 tv SEE ALSO
702 1.1 tv make(1), hier(7), release(7)
703 1.1 tv
704 1.1 tv HISTORY
705 1.15 lukem The build.sh based build scheme was introduced for NetBSD 1.6 as
706 1.15 lukem USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
707 1.1 tv
708 1.1 tv BUGS
709 1.15 lukem A few platforms are not yet using this build system.
710 1.1 tv
711 1.49 lukem NetBSD February 6, 2003 NetBSD
712