Annotation of src/BUILDING, Revision 1.81
1.1 tv 1: BUILDING(8) NetBSD System Manager's Manual BUILDING(8)
2:
3: NAME
1.52 jmc 4: BUILDING -- Procedure for building NetBSD from source code.
1.1 tv 5:
6: REQUIREMENTS
7: NetBSD is designed to be buildable on most POSIX-compliant host systems.
8: The basic build procedure is the same whether compiling natively (on the
9: same NetBSD architecture) or cross compiling (on another architecture or
10: OS).
11:
12: This source tree contains a special subtree, ``tools'', which uses the
13: host system to create a build toolchain for the target architecture. The
14: host system must have at least C and C++ compilers in order to create the
15: toolchain (make is not required); all other tools are created as part of
1.53 reed 16: the NetBSD build process. (See the environment variables section below
17: if you need to override or manually select your compilers.)
1.1 tv 18:
19: FILES
20: Source tree layout
1.17 wiz 21: doc/BUILDING.mdoc
22: This document (in -mdoc troff format; the original copy).
1.1 tv 23:
1.2 wiz 24: BUILDING This document (in plaintext).
1.1 tv 25:
1.48 jmc 26: tools/compat/README
27: Special notes for cross-hosting a NetBSD build on non-
28: NetBSD platforms.
29:
1.44 lukem 30: Makefile The main Makefile for NetBSD; should only be run for
31: native builds with an appropriately up-to-date version of
1.1 tv 32: NetBSD make(1). (For building from out-of-date systems or
33: on a non-native host, see the build.sh shell script.)
34:
35: UPDATING Special notes for updating from an earlier revision of
36: NetBSD. It is important to read this file before every
37: build of an updated source tree.
38:
39: build.sh Bourne-compatible shell script used for building the host
40: build tools and the NetBSD system from scratch. Can be
41: used for both native and cross builds, and should be used
42: instead of make(1) for any source tree that is updated and
43: recompiled regularly.
44:
45: crypto/dist/, dist/, gnu/dist/
46: Sources imported verbatim from third parties, without man-
47: gling the existing build structure. Other source trees in
48: bin through usr.sbin use the NetBSD make(1) ``reachover''
1.44 lukem 49: Makefile semantics when building these programs for a
50: native host.
1.1 tv 51:
52: distrib/, etc/
53: Sources for items used when making a full release snap-
1.27 lukem 54: shot, such as files installed in DESTDIR/etc on the desti-
55: nation system, boot media, and release notes.
1.1 tv 56:
1.70 dholland 57: tests/, regress/
58: Regression test harness. Can be cross-compiled, but only
59: run natively. tests/ uses the atf(7) test framework;
60: regress/ contains older tests that have not yet been
61: migrated to atf(7).
1.1 tv 62:
63: sys/ NetBSD kernel sources.
64:
65: tools/ ``Reachover'' build structure for the host build tools.
66: This has a special method of determining out-of-date sta-
67: tus.
68:
69: bin/ ... usr.sbin/
70: Sources to the NetBSD userland (non-kernel) programs. If
71: any of these directories are missing, they will be skipped
72: during the build.
73:
1.49 lukem 74: x11/ ``Reachover'' build structure for X11R6; the source is in
75: X11SRCDIR.
76:
1.1 tv 77: Build tree layout
78: The NetBSD build tree is described in hier(7), and the release layout is
79: described in release(7).
80:
81: CONFIGURATION
1.8 lukem 82: Environment variables
83: Several environment variables control the behaviour of NetBSD builds.
84:
1.58 apb 85: HOST_SH Path name to a POSIX-compliant shell. If this is not
86: set explicitly, then the default is set using heuris-
87: tics dependent on the host platform, or from the shell
88: under which build.sh is executed (if that can be deter-
89: mined), or using the first copy of sh found in PATH.
90: If the host system's /bin/sh is not POSIX-compliant, we
91: suggest that you build using commands like
92:
93: HOST_SH=/path/to/working/shell
94: export HOST_SH
95: ${HOST_SH} build.sh [options]
96:
1.53 reed 97: HOST_CC Path name to C compiler used to create the toolchain.
98:
99: HOST_CXX Path name to C++ compiler used to create the toolchain.
100:
1.70 dholland 101: MACHINE Machine type, e.g., ``macppc''.
1.8 lukem 102:
1.70 dholland 103: MACHINE_ARCH Machine architecture, e.g., ``powerpc''.
1.8 lukem 104:
105: MAKE Path name to invoke make(1) as.
106:
107: MAKEFLAGS Flags to invoke make(1) with.
108:
109: MAKEOBJDIR Directory to use as the .OBJDIR for the current direc-
1.59 apb 110: tory. The value is subjected to variable expansion by
1.73 apb 111: make(1). Typical usage is to set this variable to a
112: value involving the use of `${.CURDIR:S...}' or
113: `${.CURDIR:C...}', to derive the value of .OBJDIR from
114: the value of .CURDIR. Used only if MAKEOBJDIRPREFIX is
115: not defined. MAKEOBJDIR can be provided only in the
116: environment or via the -O flag of build.sh; it cannot
117: usefully be set inside a Makefile.
1.8 lukem 118:
119: MAKEOBJDIRPREFIX Top level directory of the object directory tree. If
1.59 apb 120: specified, must be an absolute path. If this is
121: defined, ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the
122: .OBJDIR for the current directory. The current direc-
1.73 apb 123: tory may be read only. MAKEOBJDIRPREFIX can be pro-
124: vided only in the environment or via the -M flag of
125: build.sh; it cannot usefully be set inside a Makefile.
1.8 lukem 126:
1.1 tv 127: "make" variables
128: Several variables control the behavior of NetBSD builds. Unless other-
129: wise specified, these variables may be set in either the process environ-
130: ment or the make(1) configuration file specified by MAKECONF.
131:
1.9 thorpej 132: BUILDID Identifier for the build. The identifier will be appended to
133: object directory names, and can be consulted in the make(1)
134: configuration file in order to set additional build parame-
135: ters, such as compiler flags.
136:
1.72 perry 137: BUILDSEED GCC uses random numbers when compiling C++ code. This vari-
138: able seeds the gcc random number generator using the -fran-
139: dom-seed flag with this value. By default, it is set to
140: NetBSD-(majorversion). Using a fixed value causes C++ bina-
141: ries to be the same when built from the same sources. Addi-
142: tional information is available in the GCC documentation of
143: -frandom-seed.
144:
1.1 tv 145: DESTDIR Directory to contain the built NetBSD system. If set, spe-
146: cial options are passed to the compilation tools to prevent
147: their default use of the host system's /usr/include,
1.59 apb 148: /usr/lib, and so forth. This pathname must be an absolute
149: path, and should not end with a slash (/) character. (For
150: installation into the system's root directory, set DESTDIR to
151: an empty string, not to ``/''). The directory must reside on
152: a file system which supports long file names and hard links.
1.1 tv 153:
154: Default: Empty string if USETOOLS is ``yes''; unset other-
155: wise.
156:
1.30 lukem 157: Note: build.sh will provide a default of destdir.MACHINE (in
1.70 dholland 158: the top-level .OBJDIR) unless run in `expert' mode.
1.30 lukem 159:
1.1 tv 160: MAKECONF The name of the make(1) configuration file. Only settable in
161: the process environment.
162:
163: Default: ``/etc/mk.conf''
164:
1.45 lukem 165: MAKEVERBOSE
166: Level of verbosity of status messages. Supported values:
167:
1.80 apb 168: 0 No descriptive messages or commands executed by make(1)
169: are shown.
1.45 lukem 170:
1.80 apb 171: 1 Brief messages are shown describing what is being done,
172: but the actual commands executed by make(1) are not dis-
173: played.
174:
175: 2 Descriptive messages are shown as above (prefixed with a
176: `#'), and ordinary commands performed by make(1) are
177: displayed.
178:
179: 3 In addition to the above, all commands performed by
180: make(1) are displayed, even if they would ordinarily
181: have been hidden through use of the ``@'' prefix in the
182: relevant makefile.
1.45 lukem 183:
1.80 apb 184: 4 In addition to the above, commands executed by make(1)
185: are traced through use of the sh(1) ``-x'' flag.
1.45 lukem 186:
187: Default: 2
188:
1.1 tv 189: MKCATPAGES Can be set to ``yes'' or ``no''. Indicates whether prefor-
190: matted plaintext manual pages will be created during a build.
191:
192: Default: ``yes''
193:
194: MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether crypto-
195: graphic code will be included in a build; provided for the
196: benefit of countries that do not allow strong cryptography.
1.44 lukem 197: Will not affect use of the standard low-security password
198: encryption system, crypt(3).
1.1 tv 199:
200: Default: ``yes''
201:
202: MKDOC Can be set to ``yes'' or ``no''. Indicates whether system
1.44 lukem 203: documentation destined for DESTDIR/usr/share/doc will be
204: installed during a build.
1.1 tv 205:
206: Default: ``yes''
207:
1.77 lukem 208: MKHTML Can be set to ``yes'' or ``no''. Indicates whether prefor-
209: matted HTML manual pages will be built and installed
210:
211: Default: ``yes''
212:
1.4 tv 213: MKHOSTOBJ Can be set to ``yes'' or ``no''. If set to ``yes'', then for
214: programs intended to be run on the compile host, the name,
215: release, and architecture of the host operating system will
216: be suffixed to the name of the object directory created by
217: ``make obj''. (This allows multiple host systems to compile
218: NetBSD for a single target.) If set to ``no'', then programs
219: built to be run on the compile host will use the same object
220: directory names as programs built to be run on the target.
221:
222: Default: ``no''
223:
1.1 tv 224: MKINFO Can be set to ``yes'' or ``no''. Indicates whether GNU Info
225: files, used for the documentation for most of the compilation
226: tools, will be created and installed during a build.
227:
228: Default: ``yes''
229:
230: MKLINT Can be set to ``yes'' or ``no''. Indicates whether lint(1)
231: will be run against portions of the NetBSD source code during
232: the build, and whether lint libraries will be installed into
1.27 lukem 233: DESTDIR/usr/libdata/lint.
1.1 tv 234:
235: Default: ``yes''
236:
237: MKMAN Can be set to ``yes'' or ``no''. Indicates whether manual
238: pages will be installed during a build.
239:
240: Default: ``yes''
241:
242: MKNLS Can be set to ``yes'' or ``no''. Indicates whether Native
1.44 lukem 243: Language System locale zone files will be compiled and
244: installed during a build.
1.1 tv 245:
246: Default: ``yes''
247:
248: MKOBJ Can be set to ``yes'' or ``no''. Indicates whether object
249: directories will be created when running ``make obj''. If
250: set to ``no'', then all built files will be located inside
251: the regular source tree.
252:
253: Default: ``yes''
254:
1.70 dholland 255: Note that setting MKOBJ to ``no'' is not recommended and may
256: cause problems when updating the tree with cvs(1).
257:
1.1 tv 258: MKPIC Can be set to ``yes'' or ``no''. Indicates whether shared
259: objects and libraries will be created and installed during a
260: build. If set to ``no'', the entire built system will be
261: statically linked.
262:
263: Default: Platform dependent. As of this writing, all plat-
264: forms except sh3 default to ``yes''.
265:
266: MKPICINSTALL
267: Can be set to ``yes'' or ``no''. Indicates whether the ar(1)
1.44 lukem 268: format libraries (lib*_pic.a), used to generate shared
269: libraries, are installed during a build.
1.1 tv 270:
271: Default: ``yes''
272:
273: MKPROFILE Can be set to ``yes'' or ``no''. Indicates whether profiled
274: libraries (lib*_p.a) will be built and installed during a
275: build.
276:
277: Default: ``yes''; however, some platforms turn off MKPROFILE
278: by default at times due to toolchain problems with profiled
279: code.
280:
281: MKSHARE Can be set to ``yes'' or ``no''. Indicates whether files
1.44 lukem 282: destined to reside in DESTDIR/usr/share will be built and
283: installed during a build. If set to ``no'', then all of
1.27 lukem 284: MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to
285: ``no'' unconditionally.
1.1 tv 286:
287: Default: ``yes''
288:
1.78 apb 289: MKSTRIPIDENT
290: Can be set to ``yes'' or ``no''. Indicates whether program
291: binaries and shared libraries should be built to include RCS
292: IDs for use with ident(1).
293:
294: Default: ``no''
295:
1.50 wiz 296: MKTTINTERP Can be set to ``yes'' or ``no''. For X builds, decides if
297: the TrueType bytecode interpreter is turned on. See
298: http://www.freetype.org/patents.html for details.
299:
300: Default: ``no''
301:
1.44 lukem 302: MKUNPRIVED Can be set to ``yes'' or ``no''. Indicates whether an
303: unprivileged install will occur. The user, group, permis-
1.52 jmc 304: sions, and file flags, will not be set on the installed
305: items; instead the information will be appended to a file
306: called METALOG in DESTDIR. The contents of METALOG are used
307: during the generation of the distribution tar files to ensure
308: that the appropriate file ownership is stored.
1.38 lukem 309:
310: Default: ``no''
311:
1.44 lukem 312: MKUPDATE Can be set to ``yes'' or ``no''. Indicates whether all
313: install operations intended to write to DESTDIR will compare
1.38 lukem 314: file timestamps before installing, and skip the install phase
1.44 lukem 315: if the destination files are up-to-date. This also has
316: implications on full builds (see next subsection).
1.38 lukem 317:
318: Default: ``no''
319:
1.79 mrg 320: MKX11 Can be set to ``yes'' or ``no''. Indicates whether X11 is
1.49 lukem 321: built from X11SRCDIR.
322:
323: Default: ``no''
324:
1.59 apb 325: TOOLDIR Directory to hold the host tools, once built. If specified,
326: must be an absolute path. This directory should be unique to
327: a given host system and NetBSD source tree. (However, multi-
328: ple targets may share the same TOOLDIR; the target-dependent
329: files have unique names.) If unset, a default based on the
330: uname(1) information of the host platform will be created in
331: the .OBJDIR of src.
1.1 tv 332:
333: Default: Unset.
334:
335: USETOOLS Indicates whether the tools specified by TOOLDIR should be
336: used as part of a build in progress. Must be set to ``yes''
337: if cross-compiling.
338:
339: yes Use the tools from TOOLDIR.
340:
341: no Do not use the tools from TOOLDIR, but refuse to build
342: native compilation tool components that are version-
343: specific for that tool.
344:
345: never Do not use the tools from TOOLDIR, even when building
346: native tool components. This is similar to the tradi-
347: tional NetBSD build method, but does not verify that
348: the compilation tools in use are up-to-date enough in
349: order to build the tree successfully. This may cause
350: build or runtime problems when building the whole
351: NetBSD source tree.
352:
1.71 dholland 353: Default: ``yes'', unless TOOLCHAIN_MISSING is set to ``yes''.
354:
355: USETOOLS is also set to ``no'' when using <bsd.*.mk> outside
356: the NetBSD source tree.
1.1 tv 357:
1.59 apb 358: X11SRCDIR Directory containing the X11R6 source. If specified, must be
359: an absolute path. The main X11R6 source is found in
360: X11SRCDIR/xfree/xc.
1.49 lukem 361:
362: Default: ``/usr/xsrc''
363:
1.79 mrg 364: X11FLAVOUR The style of X11 cross-built, set to either ``Xorg'' or
365: ``XFree86''.
366:
1.81 ! mrg 367: Default: ``Xorg'' on amd64, i386, macppc, shark and sparc64
! 368: platforms, ``XFree86'' on everything else.
1.79 mrg 369:
1.1 tv 370: "make" variables for full builds
1.7 lukem 371: These variables only affect the top level ``Makefile'' and do not affect
372: manually building subtrees of the NetBSD source code.
1.1 tv 373:
1.20 lukem 374: INSTALLWORLDDIR Location for the ``make installworld'' target to install
1.59 apb 375: to. If specified, must be an absolute path.
1.1 tv 376:
1.20 lukem 377: Default: ``/''
1.1 tv 378:
1.44 lukem 379: MKOBJDIRS Can be set to ``yes'' or ``no''. Indicates whether
380: object directories will be created automatically (via a
1.20 lukem 381: ``make obj'' pass) at the start of a build.
1.1 tv 382:
1.34 lukem 383: Default: ``no''
1.1 tv 384:
1.70 dholland 385: If using build.sh, the default is ``yes''. This may be
386: set back to ``no'' by giving build.sh the -o option.
387:
1.38 lukem 388: MKUPDATE Can be set to ``yes'' or ``no''. If set, then in addi-
389: tion to the effects described for MKUPDATE=yes above,
390: this implies the effects of NOCLEANDIR (i.e., ``make
391: cleandir'' is avoided).
392:
393: Default: ``no''
394:
1.70 dholland 395: If using build.sh, this may be set by giving the -u
396: option.
397:
398: NBUILDJOBS Now obsolete. Use the make(1) option -j, instead. See
399: below.
1.1 tv 400:
1.20 lukem 401: Default: Unset.
1.1 tv 402:
1.20 lukem 403: NOCLEANDIR If set, avoids the ``make cleandir'' phase of a full
404: build. This has the effect of allowing only changed
405: files in a source tree to be recompiled. This can speed
406: up builds when updating only a few files in the tree.
1.1 tv 407:
1.20 lukem 408: Default: Unset.
1.1 tv 409:
1.70 dholland 410: See also MKUPDATE.
411:
1.20 lukem 412: NODISTRIBDIRS If set, avoids the ``make distrib-dirs'' phase of a full
413: build. This skips running mtree(8) on DESTDIR, useful
414: on systems where building as an unprivileged user, or
415: where it is known that the system-wide mtree files have
416: not changed.
1.1 tv 417:
1.20 lukem 418: Default: Unset.
1.1 tv 419:
1.20 lukem 420: NOINCLUDES If set, avoids the ``make includes'' phase of a full
421: build. This has the effect of preventing make(1) from
1.44 lukem 422: thinking that some programs are out-of-date simply
423: because the system include files have changed. However,
1.20 lukem 424: this option should not be used when updating the entire
425: NetBSD source tree arbitrarily; it is suggested to use
1.70 dholland 426: MKUPDATE=yes instead in that case.
1.1 tv 427:
1.20 lukem 428: Default: Unset.
1.1 tv 429:
1.20 lukem 430: RELEASEDIR If set, specifies the directory to which a release(7)
431: layout will be written at the end of a ``make release''.
1.59 apb 432: If specified, must be an absolute path.
1.20 lukem 433:
434: Default: Unset.
435:
1.30 lukem 436: Note: build.sh will provide a default of releasedir (in
1.70 dholland 437: the top-level .OBJDIR) unless run in `expert' mode.
1.30 lukem 438:
1.1 tv 439: BUILDING
440: "make" command line options
1.52 jmc 441: This is not a summary of all the options available to make(1); only the
442: options used most frequently with NetBSD builds are listed here.
1.1 tv 443:
1.10 sommerfe 444: -j njob Run up to njob make(1) subjobs in parallel. Makefiles should
1.52 jmc 445: use .WAIT or have explicit dependencies as necessary to
1.74 apb 446: enforce build ordering.
1.10 sommerfe 447:
1.1 tv 448: -m dir Specify the default directory for searching for system Make-
449: file segments, mainly the <bsd.*.mk> files. When building any
450: full NetBSD source tree, this should be set to the
1.70 dholland 451: ``share/mk'' directory in the source tree. This is set auto-
452: matically when building from the top level, or when using
453: build.sh.
1.1 tv 454:
455: -n Display the commands that would have been executed, but do not
456: actually execute them. This will still cause recursion to
457: take place.
458:
1.47 zuntum 459: -V var Print make(1)'s idea of the value of var. Does not build any
1.1 tv 460: targets.
461:
462: var=value Set the variable var to value, overriding any setting speci-
463: fied by the process environment, the MAKECONF configuration
464: file, or the system Makefile segments.
465:
466: "make" targets
467: These default targets may be built by running make(1) in any subtree of
468: the NetBSD source code. It is recommended that none of these be used
469: from the top level Makefile; as a specific exception, ``make obj'' and
470: ``make cleandir'' are useful in that context.
471:
472: all Build programs, libraries, and preformatted documentation.
473:
474: clean Remove program and library object code files.
475:
1.44 lukem 476: cleandir Same as clean, but also remove preformatted documentation,
477: dependency files generated by ``make depend'', and any other
1.49 lukem 478: files known to be created at build time.
1.1 tv 479:
1.44 lukem 480: depend Create dependency files (.depend) containing more detailed
481: information about the dependencies of source code on header
1.1 tv 482: files. Allows programs to be recompiled automatically when a
483: dependency changes.
484:
485: dependall Does a ``make depend'' immediately followed by a ``make all''.
1.10 sommerfe 486: This improves cache locality of the build since both passes
487: read the source files in their entirety.
1.1 tv 488:
1.49 lukem 489: distclean Synonym for cleandir.
490:
1.44 lukem 491: includes Build and install system header files. Typically needed
492: before any system libraries or programs can be built.
1.1 tv 493:
494: install Install programs, libraries, and documentation into DESTDIR.
1.27 lukem 495: Few files will be installed to DESTDIR/dev, DESTDIR/etc,
496: DESTDIR/root or DESTDIR/var in order to prevent user supplied
497: configuration data from being overwritten.
1.1 tv 498:
499: lint Run lint(1) against the C source code, where appropriate, and
500: generate system-installed lint libraries.
501:
502: obj Create object directories to be used for built files, instead
503: of building directly in the source tree.
504:
505: tags Create ctags(1) searchable function lists usable by the ex(1)
506: and vi(1) text editors.
507:
508: "make" targets for the top level
509: Additional make(1) targets are usable specifically from the top source
510: level to facilitate building the entire NetBSD source tree.
511:
1.68 reed 512: build Build the entire NetBSD system (except the kernel). This
513: orders portions of the source tree such that prerequisites
514: will be built in the proper order.
1.20 lukem 515:
516: distribution Do a ``make build'', and then install a full distribution
1.68 reed 517: (which does not include a kernel) into DESTDIR, including
518: files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
519: DESTDIR/var.
1.20 lukem 520:
521: buildworld As per ``make distribution'', except that it ensures that
522: DESTDIR is not the root directory.
523:
1.70 dholland 524: installworld Install the distribution from DESTDIR to INSTALLWORLDDIR,
525: which defaults to the root directory. Ensures that
1.52 jmc 526: INSTALLWORLDDIR is not the root directory if cross compil-
1.20 lukem 527: ing.
528:
1.61 apb 529: The INSTALLSETS environment variable may be set to a list
530: of distribution sets to be installed. By default, all sets
1.70 dholland 531: except ``etc'' and ``xetc'' are installed, so most files in
532: INSTALLWORLDDIR/etc will not be installed or modified.
1.61 apb 533:
534: Note: Before performing this operation with
535: INSTALLWORLDDIR=/, it is highly recommended that you
536: upgrade your kernel and reboot. After performing this
537: operation, it is recommended that you use etcupdate(8) to
538: update files in INSTALLWORLDDIR/etc and that you use
539: postinstall(8) to check for inconsistencies (and possibly
540: to fix them).
1.20 lukem 541:
1.25 lukem 542: sets Create distribution sets from DESTDIR into
1.69 lukem 543: RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run
1.70 dholland 544: after ``make distribution'', as ``make build'' alone does
545: not install all of the required files.
1.25 lukem 546:
1.31 lukem 547: sourcesets Create source sets of the source tree into
548: RELEASEDIR/source/sets.
549:
1.54 apb 550: syspkgs Create syspkgs from DESTDIR into
1.69 lukem 551: RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run
1.70 dholland 552: after ``make distribution'', as ``make build'' alone does
553: not install all of the required files.
1.54 apb 554:
1.44 lukem 555: release Do a ``make distribution'', build kernels, distribution
556: media, and install sets (this as per ``make sets''), and
557: then package the system into a standard release layout as
558: described by release(7). This requires that RELEASEDIR be
1.25 lukem 559: set (see above).
1.1 tv 560:
1.62 apb 561: iso-image Create a NetBSD installation CD-ROM image in the
562: RELEASEDIR/iso directory. The CD-ROM file system will have
563: a layout as described in release(7).
564:
565: For most machine types, the CD-ROM will be bootable, and
566: will automatically run the sysinst(8) menu-based installa-
567: tion program, which can be used to install or upgrade a
568: NetBSD system. Bootable CD-ROMs also contain tools that
569: may be useful in repairing a damaged NetBSD installation.
570:
571: Before ``make iso-image'' is attempted, RELEASEDIR must be
572: populated by ``make release'' or equivalent.
573:
574: Note that other, smaller, CD-ROM images may be created in
1.69 lukem 575: the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
576: tory by ``make release''. These smaller images usually
577: contain the same tools as the larger images in
578: RELEASEDIR/iso, but do not contain additional content such
579: as the distribution sets.
1.62 apb 580:
581: Note that the mac68k port still uses an older method of
582: creating CD-ROM images. This requires the mkisofs(1) util-
583: ity, which is not part of NetBSD, but which can be
584: installed from pkgsrc/sysutils/cdrtools.
1.56 apb 585:
1.64 jnemeth 586: iso-image-source
587: Create a NetBSD installation CD-ROM image in the
588: RELEASEDIR/iso directory. The CD-ROM file system will have
589: a layout as described in release(7). It will have top
590: level directories for the machine type and source.
591:
592: For most machine types, the CD-ROM will be bootable, and
593: will automatically run the sysinst(8) menu-based installa-
594: tion program, which can be used to install or upgrade a
595: NetBSD system. Bootable CD-ROMs also contain tools that
596: may be useful in repairing a damaged NetBSD installation.
597:
598: Before ``make iso-image-source'' is attempted, RELEASEDIR
599: must be populated by ``make sourcesets release'' or equiva-
600: lent.
601:
602: Note that other, smaller, CD-ROM images may be created in
1.69 lukem 603: the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom direc-
604: tory by ``make release''. These smaller images usually
605: contain the same tools as the larger images in
606: RELEASEDIR/iso, but do not contain additional content such
607: as the distribution sets.
1.64 jnemeth 608:
609: Note that the mac68k port still uses an older method of
610: creating CD-ROM images. This requires the mkisofs(1) util-
611: ity, which is not part of NetBSD, but which can be
612: installed from pkgsrc/sysutils/cdrtools.
613:
1.1 tv 614: regression-tests
1.20 lukem 615: Can only be run after building the regression tests in the
1.70 dholland 616: directory ``regress''. Runs those compiled regression
617: tests on the local host. Note that most tests are now man-
618: aged instead using atf(7); this target should probably run
619: those as well but currently does not.
1.1 tv 620:
621: The "build.sh" script
622: This script file is a Bourne shell script designed to build the entire
623: NetBSD system on any host with a Bourne shell in /bin/sh, including many
624: that are not POSIX compliant. Note that if a host system's /bin/sh is
625: unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
626: a usable alternative.
627:
628: All cross-compile builds, and most native builds, of the entire system
629: should make use of build.sh rather than just running ``make''. This way,
630: the make(1) program will be bootstrapped properly, in case the host sys-
631: tem has an older or incompatible ``make'' program.
632:
633: When compiling the entire system via build.sh, many make(1) variables are
634: set for you in order to help encapsulate the build process. In the list
635: of options below, variables that are automatically set by build.sh are
636: noted where applicable.
637:
1.22 lukem 638: The following operations are supported by build.sh:
639:
1.70 dholland 640: build Build the system as per ``make build''. Before the main
641: part of the build commences, this command runs the obj
642: operation (unless the -o option is given), ``make
643: cleandir'' (unless the -u option is given), and the tools
644: operation.
1.22 lukem 645:
646: distribution Build a full distribution as per ``make distribution''.
1.70 dholland 647: This command first runs the build operation.
1.22 lukem 648:
1.70 dholland 649: release Build a full release as per ``make release''. This command
650: first runs the distribution operation.
1.22 lukem 651:
1.23 lukem 652: makewrapper Create the nbmake-MACHINE wrapper. This operation is auto-
653: matically performed for any of the other operations.
654:
1.75 lukem 655: cleandir Perform ``make cleandir''.
656:
1.22 lukem 657: obj Perform ``make obj''.
658:
1.70 dholland 659: tools Build and install the host tools from src/tools. This com-
660: mand will first run ``make obj'' and ``make cleandir'' in
661: the tools subdirectory unless the -o or -u options (respec-
662: tively) are given.
1.22 lukem 663:
1.35 lukem 664: install=idir Install the contents of DESTDIR to idir, using ``make
1.61 apb 665: installworld''. Note that files that are part of the
666: ``etc'' or ``xetc'' sets will not be installed.
1.35 lukem 667:
1.22 lukem 668: kernel=kconf Build a new kernel. The kconf argument is the name of a
1.54 apb 669: configuration file suitable for use by config(1). If kconf
1.22 lukem 670: does not contain any `/' characters, the configuration file
671: is expected to be found in the KERNCONFDIR directory, which
672: is typically sys/arch/MACHINE/conf. The new kernel will be
673: built in a subdirectory of KERNOBJDIR, which is typically
674: sys/arch/MACHINE/compile or an associated object directory.
1.70 dholland 675:
676: This command does not imply the tools command; run the
677: tools command first unless it is certain that the tools
678: already exist and are up to date.
679:
680: This command will run ``make cleandir'' on the kernel in
681: question first unless the -u option is given.
1.22 lukem 682:
1.35 lukem 683: releasekernel=kconf
1.70 dholland 684: Install a gzip(1)ed copy of the kernel previously built by
1.69 lukem 685: kernel=kconf into
686: RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
687: netbsd-kconf.gz, although the ``netbsd'' prefix is deter-
688: mined from the ``config'' directives in kconf.
1.24 lukem 689:
690: sets Perform ``make sets''.
1.31 lukem 691:
692: sourcesets Perform ``make sourcesets''.
1.22 lukem 693:
1.54 apb 694: syspkgs Perform ``make syspkgs''.
695:
1.56 apb 696: iso-image Perform ``make iso-image''.
697:
1.65 jnemeth 698: iso-image-source
699: Perform ``make iso-image-source''.
700:
1.51 wiz 701: The following command line options alter the behaviour of the build.sh
702: operations described above:
1.1 tv 703:
704: -a arch Set the value of MACHINE_ARCH to arch.
1.9 thorpej 705:
706: -B buildid
707: Set the value of BUILDID to buildid. This will also append the
1.67 sborrill 708: build identifier to the name of the ``make'' wrapper script so
1.37 lukem 709: that the resulting name is of the form
710: ``nbmake-MACHINE-BUILDID''.
1.1 tv 711:
1.67 sborrill 712: -C cdextras
713: Set the value of CDEXTRA to cdextras which is a space-separated
714: list of files or directories which will be added in order to
715: the CD-ROM image when used in conjunction with ``iso-image'' or
716: ``iso-image-source''. Files will be added to the root of the
717: CD-ROM image, whereas directories will be copied recursively.
718: If relative paths are specified, they will be converted to
719: absolute paths before being used.
1.66 jnemeth 720:
1.59 apb 721: -D dest Set the value of DESTDIR to dest. If a relative path is speci-
722: fied, it will be converted to an absolute path before being
723: used.
1.18 lukem 724:
1.23 lukem 725: -E Set `expert' mode. This overrides various sanity checks, and
726: allows: DESTDIR does not have to be set to a non-root path for
1.38 lukem 727: builds, and MKUNPRIVED=yes does not have to be set when build-
728: ing as a non-root user.
1.23 lukem 729:
730: Note: It is highly recommended that you know what you are doing
731: when you use this option.
1.19 lukem 732:
1.51 wiz 733: -h Print a help message.
734:
1.70 dholland 735: -j njob Run up to njob make(1) subjobs in parallel; passed through to
1.74 apb 736: make(1). If you see failures for reasons other than running
737: out of memory while using build.sh with -j, please save com-
738: plete build logs so the failures can be analyzed.
739:
740: To achieve the fastest builds, -j values between (1 + the num-
741: ber of CPUs) and (2 * the number of CPUs) are recommended. Use
742: lower values on machines with limited memory or I/O bandwidth.
1.1 tv 743:
1.73 apb 744: -M obj Set MAKEOBJDIRPREFIX to obj. For instance, if the source
745: directory is /usr/src, a setting of ``-M /usr/obj'' will place
746: build-time files under /usr/obj/usr/src/bin,
747: /usr/obj/usr/src/lib, /usr/obj/usr/src/usr.bin, and so forth.
748: If a relative path is specified, it will be converted to an
749: absolute path before being used. Unsets MAKEOBJDIR. See ``-O
750: -obj'' for more information.
1.18 lukem 751:
1.60 apb 752: -m mach Set the value of MACHINE to mach, except in some special cases
753: listed below. This will also override any value of
754: MACHINE_ARCH in the process environment with a value deduced
755: from mach, unless -a is specified. All cross builds require
756: -m, but if unset on a NetBSD host, the host's value of MACHINE
757: will be detected and used automatically.
758:
759: Some machines support multiple values for MACHINE_ARCH. The
760: following special cases for the mach argument are defined to
761: set the listed values of MACHINE and MACHINE_ARCH:
1.33 lukem 762:
763: mach MACHINE MACHINE_ARCH
1.60 apb 764: evbarm evbarm (not set)
765: evbarm-eb evbarm armeb
766: evbarm-el evbarm arm
1.33 lukem 767: evbmips evbmips (not set)
768: evbmips-eb evbmips mipseb
769: evbmips-el evbmips mipsel
770: evbsh3 evbsh3 (not set)
771: evbsh3-eb evbsh3 sh3eb
772: evbsh3-el evbsh3 sh3el
773: sbmips sbmips (not set)
774: sbmips-eb sbmips mipseb
775: sbmips-el sbmips mipsel
1.1 tv 776:
1.45 lukem 777: -N noiselevel
1.46 lukem 778: Set the ``noisyness'' level of the build, by setting
779: MAKEVERBOSE to noiselevel.
1.45 lukem 780:
1.1 tv 781: -n Show the commands that would be executed by build.sh, but do
782: not make any changes. This is similar in concept to ``make
783: -n''.
784:
1.18 lukem 785: -O obj Create an appropriate transform macro for MAKEOBJDIR that will
1.73 apb 786: place the built object files under obj. For instance, a set-
787: ting of ``-O /usr/obj'' will place build-time files under
788: /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and so forth. If
789: a relative path is specified, it will be converted to an abso-
790: lute path before being used. Unsets MAKEOBJDIRPREFIX.
791:
792: In normal use, exactly one of the -M or -O options should be
1.78 apb 793: specified. If neither -M nor -O is specified, then a default
794: object directory will be chosen according to rules in
795: <bsd.obj.mk>. Relying on this default is not recommended
796: because it is determined by complex rules that are influenced
797: by the values of several variables and by the location of the
798: source directory.
1.18 lukem 799:
1.34 lukem 800: -o Set the value of MKOBJDIRS to ``no''. Otherwise, it will be
1.70 dholland 801: automatically set to ``yes''. This default is opposite to the
802: behaviour when not using build.sh.
1.1 tv 803:
1.59 apb 804: -R rel Set the value of RELEASEDIR to rel. If a relative path is
805: specified, it will be converted to an absolute path before
806: being used.
1.18 lukem 807:
1.1 tv 808: -r Remove the contents of DESTDIR and TOOLDIR before building
809: (provides a clean starting point). This will skip deleting
810: DESTDIR if building on a native system to the root directory.
811:
1.72 perry 812: -S seed Change the value of BUILDSEED to seed. This should rarely be
813: necessary.
814:
1.59 apb 815: -T tools Set the value of TOOLDIR to tools. If a relative path is spec-
816: ified, it will be converted to an absolute path before being
1.70 dholland 817: used. If set, the bootstrap ``make'' will only be rebuilt if
818: the source files for make(1) have changed.
1.18 lukem 819:
1.38 lukem 820: -U Set MKUNPRIVED=yes.
1.18 lukem 821:
1.38 lukem 822: -u Set MKUPDATE=yes.
1.1 tv 823:
1.21 lukem 824: -V var=[value]
1.40 lukem 825: Set the environment variable var to an optional value. This is
826: propagated to the nbmake wrapper.
1.21 lukem 827:
1.1 tv 828: -w wrapper
829: Create the nbmake wrapper script (see below) in a custom loca-
830: tion, specified by wrapper. This allows, for instance, to
831: place the wrapper in PATH automatically. Note that wrapper is
1.59 apb 832: the full name of the file, not just a directory name. If a
833: relative path is specified, it will be converted to an absolute
834: path before being used.
1.1 tv 835:
1.49 lukem 836: -X x11src
1.59 apb 837: Set the value of X11SRCDIR to x11src. If a relative path is
838: specified, it will be converted to an absolute path before
839: being used.
1.49 lukem 840:
841: -x Set MKX11=yes.
842:
1.40 lukem 843: -Z var Unset ("zap") the environment variable var. This is propagated
844: to the nbmake wrapper.
845:
1.1 tv 846: The "nbmake-MACHINE" wrapper script
847: If using the build.sh script to build NetBSD, a nbmake-MACHINE script
848: will be created in TOOLDIR/bin upon the first build to assist in building
849: subtrees on a cross-compile host.
850:
851: nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
852: the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
853: eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
1.70 dholland 854: nbmake-MACHINE will also set variables specified with -V, and unset vari-
855: ables specified with -Z.
1.40 lukem 856:
1.1 tv 857: This script can be symlinked into a directory listed in PATH, or called
858: with an absolute path.
859:
1.16 lukem 860: EXAMPLES
1.78 apb 861: 1. % ./build.sh [options] tools kernel=GENERIC
1.28 lukem 862:
863: Build a new toolchain, and use the new toolchain to configure and
864: build a new GENERIC kernel.
865:
1.78 apb 866: 2. % ./build.sh [options] -U distribution
1.28 lukem 867:
1.30 lukem 868: Using unprivileged mode, build a complete distribution to a DESTDIR
869: directory that build.sh selects (and will display).
1.28 lukem 870:
1.78 apb 871: 3. # ./build.sh [options] -U install=/
1.28 lukem 872:
1.29 lukem 873: As root, install to / the distribution that was built by example 2.
874: Even though this is run as root, -U is required so that the permis-
1.30 lukem 875: sions stored in DESTDIR/METALOG are correctly applied to the files
876: as they're copied to /.
1.28 lukem 877:
1.78 apb 878: 4. % ./build.sh [options] -U -u release
1.28 lukem 879:
1.30 lukem 880: Using unprivileged mode, build a complete release to DESTDIR and
881: RELEASEDIR directories that build.sh selects (and will display).
1.38 lukem 882: MKUPDATE=yes (-u) is set to prevent the ``make cleandir'', so that
883: if this is run after example 2, it doesn't need to redo that portion
884: of the release build.
1.16 lukem 885:
1.10 sommerfe 886: OBSOLETE VARIABLES
1.70 dholland 887: NBUILDJOBS Use the make(1) option -j instead.
1.15 lukem 888:
889: USE_NEW_TOOLCHAIN
890: The new toolchain is now the default. To disable, use
891: TOOLCHAIN_MISSING=yes.
1.10 sommerfe 892:
1.1 tv 893: SEE ALSO
1.62 apb 894: make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
1.61 apb 895: pkgsrc/sysutils/cdrtools
1.1 tv 896:
897: HISTORY
1.15 lukem 898: The build.sh based build scheme was introduced for NetBSD 1.6 as
899: USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
1.1 tv 900:
1.78 apb 901: NetBSD September 10, 2008 NetBSD
CVSweb <webmaster@jp.NetBSD.org>