Annotation of src/BUILDING, Revision 1.139
1.104 wiz 1: BUILDING(8) System Manager's Manual BUILDING(8)
1.1 tv 2:
1.105 wiz 3: NAME
1.122 wiz 4: BUILDING - Procedure for building NetBSD from source code.
1.1 tv 5:
1.105 wiz 6: REQUIREMENTS
1.1 tv 7: NetBSD is designed to be buildable on most POSIX-compliant host systems.
1.105 wiz 8: The basic build procedure is the same whether compiling natively (on the
9: same NetBSD architecture) or cross compiling (on another architecture or
1.1 tv 10: OS).
11:
1.126 wiz 12: This source tree contains a special subtree, "tools", which uses the host
13: system to create a build toolchain for the target architecture. The host
14: system must have at least C and C++ compilers in order to create the
1.105 wiz 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:
1.105 wiz 19: FILES
20: Source tree layout
21: doc/BUILDING.mdoc
1.17 wiz 22: This document (in -mdoc troff format; the original copy).
1.1 tv 23:
1.105 wiz 24: BUILDING This document (in plaintext).
1.1 tv 25:
1.105 wiz 26: tools/compat/README
1.48 jmc 27: Special notes for cross-hosting a NetBSD build on non-
28: NetBSD platforms.
29:
1.105 wiz 30: Makefile The main Makefile for NetBSD; should only be run for
1.44 lukem 31: native builds with an appropriately up-to-date version of
1.129 sevan 32: NetBSD make(1). Intended for expert use with knowlege of
33: its shortcomings, it has been superseded by the build.sh
34: shell script as the recommended means for building NetBSD.
1.1 tv 35:
1.105 wiz 36: UPDATING Special notes for updating from an earlier revision of
1.1 tv 37: NetBSD. It is important to read this file before every
38: build of an updated source tree.
39:
1.105 wiz 40: build.sh Bourne-compatible shell script used for building the host
1.1 tv 41: build tools and the NetBSD system from scratch. Can be
42: used for both native and cross builds, and should be used
1.129 sevan 43: instead of make(1) as it performs additional checks to
44: prevent common issues going undetected, such as building
45: with an outdated version of make(1).
1.1 tv 46:
1.105 wiz 47: crypto/dist/, dist/, gnu/dist/
1.104 wiz 48: Sources imported verbatim from third parties, without
49: mangling the existing build structure. Other source trees
1.126 wiz 50: in bin through usr.sbin use the NetBSD make(1) "reachover"
51: Makefile semantics when building these programs for a
52: native host.
1.104 wiz 53:
1.106 wiz 54: external, sys/external
55: Sources and build infrastructure for components imported
56: (mostly) unchanged from upstream maintainers, sorted by
57: applicable license. This is (slowly) replacing the
58: crypto/dist, dist, and gnu/dist directories.
59:
1.105 wiz 60: distrib/, etc/
1.104 wiz 61: Sources for items used when making a full release
1.105 wiz 62: snapshot, such as files installed in DESTDIR/etc on the
1.104 wiz 63: destination system, boot media, and release notes.
1.1 tv 64:
1.105 wiz 65: tests/, regress/
1.70 dholland 66: Regression test harness. Can be cross-compiled, but only
1.105 wiz 67: run natively. tests/ uses the atf(7) test framework;
68: regress/ contains older tests that have not yet been
1.70 dholland 69: migrated to atf(7).
1.1 tv 70:
1.105 wiz 71: sys/ NetBSD kernel sources.
1.1 tv 72:
1.126 wiz 73: tools/ "Reachover" build structure for the host build tools.
1.104 wiz 74: This has a special method of determining out-of-date
75: status.
1.1 tv 76:
1.105 wiz 77: bin/ ... usr.sbin/
1.1 tv 78: Sources to the NetBSD userland (non-kernel) programs. If
79: any of these directories are missing, they will be skipped
80: during the build.
81:
1.121 mrg 82: external/mit/xorg/
1.126 wiz 83: "Reachover" build structure for modular Xorg; the source
1.121 mrg 84: is in X11SRCDIR.
1.49 lukem 85:
1.126 wiz 86: extsrc/ "Reachover" build structure for externally added programs
87: and libraries; the source is in EXTSRCSRCDIR.
1.115 apb 88:
1.105 wiz 89: Build tree layout
1.1 tv 90: The NetBSD build tree is described in hier(7), and the release layout is
91: described in release(7).
92:
1.105 wiz 93: CONFIGURATION
94: Environment variables
1.8 lukem 95: Several environment variables control the behaviour of NetBSD builds.
96:
1.105 wiz 97: HOST_SH Path name to a shell available on the host system and
1.96 apb 98: suitable for use during the build. The NetBSD build
99: system requires a modern Bourne-like shell with POSIX-
100: compliant features, and also requires support for the
1.126 wiz 101: "local" keyword to declare local variables in shell
1.104 wiz 102: functions (which is a widely-implemented but non-
103: standardised feature).
1.96 apb 104:
105: Depending on the host system, a suitable shell may be
1.105 wiz 106: /bin/sh, /usr/xpg4/bin/sh, /bin/ksh (provided it is a
1.126 wiz 107: variant of ksh that supports the "local" keyword, such
108: as ksh88, but not ksh93), or /usr/local/bin/bash.
1.96 apb 109:
1.105 wiz 110: Most parts of the build require HOST_SH to be an
111: absolute path; however, build.sh allows it to be a
1.104 wiz 112: simple command name, which will be converted to an
1.105 wiz 113: absolute path by searching the PATH.
1.58 apb 114:
1.105 wiz 115: HOST_CC Path name to C compiler used to create the toolchain.
1.53 reed 116:
1.137 uwe 117: HOST_CFLAGS Flags passed to the host C compiler.
118:
1.105 wiz 119: HOST_CXX Path name to C++ compiler used to create the toolchain.
1.53 reed 120:
1.137 uwe 121: HOST_CXXFLAGS Flags passed to the host C++ compiler.
122:
1.126 wiz 123: MACHINE Machine type, e.g., "macppc".
1.8 lukem 124:
1.126 wiz 125: MACHINE_ARCH Machine architecture, e.g., "powerpc".
1.8 lukem 126:
1.105 wiz 127: MAKE Path name to invoke make(1) as.
1.8 lukem 128:
1.105 wiz 129: MAKEFLAGS Flags to invoke make(1) with. Note that build.sh
130: ignores the value of MAKEFLAGS passed in the
131: environment, but allows MAKEFLAGS to be set via the -V
1.104 wiz 132: option.
1.8 lukem 133:
1.105 wiz 134: MAKEOBJDIR Directory to use as the .OBJDIR for the current
1.104 wiz 135: directory. The value is subjected to variable
136: expansion by make(1). Typical usage is to set this
137: variable to a value involving the use of
138: `${.CURDIR:S...}' or `${.CURDIR:C...}', to derive the
1.105 wiz 139: value of .OBJDIR from the value of .CURDIR. Used only
140: if MAKEOBJDIRPREFIX is not defined. MAKEOBJDIR can be
141: provided only in the environment or via the -O flag of
142: build.sh; it cannot usefully be set inside a Makefile,
143: including mk.conf or ${MAKECONF}.
1.8 lukem 144:
1.105 wiz 145: MAKEOBJDIRPREFIX Top level directory of the object directory tree. The
1.88 apb 146: value is subjected to variable expansion by make(1).
1.105 wiz 147: build.sh will create the ${MAKEOBJDIRPREFIX} directory
148: if necessary, but if make(1) is used without build.sh,
1.88 apb 149: then rules in <bsd.obj.mk> will abort the build if the
150: ${MAKEOBJDIRPREFIX} directory does not exist. If the
1.104 wiz 151: value is defined and valid, then
1.105 wiz 152: ${MAKEOBJDIRPREFIX}/${.CURDIR} is used as the .OBJDIR
1.104 wiz 153: for the current directory. The current directory may
1.105 wiz 154: be read only. MAKEOBJDIRPREFIX can be provided only in
155: the environment or via the -M flag of build.sh; it
1.104 wiz 156: cannot usefully be set inside a Makefile, including
1.105 wiz 157: mk.conf or ${MAKECONF}.
1.104 wiz 158:
1.105 wiz 159: "make" variables
1.104 wiz 160: Several variables control the behavior of NetBSD builds. Unless
161: otherwise specified, these variables may be set in either the process
1.105 wiz 162: environment or the make(1) configuration file specified by MAKECONF.
1.1 tv 163:
1.107 apb 164: BUILDID Identifier for the build. If set, this should be a short
165: string that is suitable for use as part of a file or
166: directory name. The identifier will be appended to object
167: directory names, and can be consulted in the make(1)
1.104 wiz 168: configuration file in order to set additional build
1.107 apb 169: parameters, such as compiler flags. It will also be used as
170: part of the kernel version string, which can be printed by
1.126 wiz 171: "uname -v".
1.107 apb 172:
173: Default: Unset.
1.9 thorpej 174:
1.108 apb 175: BUILDINFO This may be a multi-line string containing information about
176: the build. This will appear in DESTDIR/etc/release, and it
177: will be stored in the buildinfo variable in any kernels that
178: are built. When such kernels are booted, the sysctl(7)
179: kern.buildinfo variable will report this value. The string
1.126 wiz 180: may contain backslash escape sequences, such as "\\"
181: (representing a backslash character) and "\n" (representing a
182: newline).
1.108 apb 183:
184: Default: Unset.
185:
1.105 wiz 186: BUILDSEED GCC uses random numbers when compiling C++ code. This
1.104 wiz 187: variable seeds the gcc random number generator using the
188: -frandom-seed flag with this value. By default, it is set to
189: NetBSD-(majorversion). Using a fixed value causes C++
190: binaries to be the same when built from the same sources,
191: resulting in identical (reproducible) builds. Additional
192: information is available in the GCC documentation of
193: -frandom-seed.
194:
1.138 thorpej 195: CPUFLAGS Additional flags to the compiler/assembler to select CPU
196: instruction set options, CPU tuning options, etc.
197:
198: Default: Unset.
199:
1.105 wiz 200: DESTDIR Directory to contain the built NetBSD system. If set,
1.104 wiz 201: special options are passed to the compilation tools to
1.105 wiz 202: prevent their default use of the host system's /usr/include,
203: /usr/lib, and so forth. This pathname must be an absolute
204: path, and should not end with a slash (/) character. (For
205: installation into the system's root directory, set DESTDIR to
1.126 wiz 206: an empty string, not to "/"). The directory must reside on a
207: file system which supports long file names and hard links.
1.1 tv 208:
1.126 wiz 209: Default: Empty string if USETOOLS is "yes"; unset otherwise.
1.1 tv 210:
1.105 wiz 211: Note: build.sh will provide a default of destdir.MACHINE (in
212: the top-level .OBJDIR) unless run in `expert' mode.
1.30 lukem 213:
1.115 apb 214: EXTSRCSRCDIR
215: Directory containing sources of externally added programs and
216: libraries. If specified, must be an absolute path.
217:
1.135 leot 218: Default: NETBSDSRCDIR/../extsrc, if that exists; otherwise
1.115 apb 219: /usr/extsrc.
220:
1.105 wiz 221: MAKECONF The name of the make(1) configuration file. Only settable in
222: the process environment.
1.1 tv 223:
1.126 wiz 224: Default: "/etc/mk.conf"
1.1 tv 225:
1.105 wiz 226: MAKEVERBOSE
1.45 lukem 227: Level of verbosity of status messages. Supported values:
228:
1.80 apb 229: 0 No descriptive messages or commands executed by make(1)
230: are shown.
1.45 lukem 231:
1.80 apb 232: 1 Brief messages are shown describing what is being done,
1.104 wiz 233: but the actual commands executed by make(1) are not
234: displayed.
1.80 apb 235:
236: 2 Descriptive messages are shown as above (prefixed with a
237: `#'), and ordinary commands performed by make(1) are
238: displayed.
239:
240: 3 In addition to the above, all commands performed by
241: make(1) are displayed, even if they would ordinarily
1.126 wiz 242: have been hidden through use of the "@" prefix in the
1.80 apb 243: relevant makefile.
1.45 lukem 244:
1.80 apb 245: 4 In addition to the above, commands executed by make(1)
1.126 wiz 246: are traced through use of the sh(1) "-x" flag.
1.45 lukem 247:
1.105 wiz 248: Default: 2
1.45 lukem 249:
1.126 wiz 250: MKCROSSGDB Can be set to "yes" or "no". Create a cross-gdb as a host
251: tool.
1.106 wiz 252:
1.126 wiz 253: Default: "no"
1.106 wiz 254:
1.126 wiz 255: MKDEBUG Can be set to "yes" or "no". Indicates whether debug
1.106 wiz 256: information should be generated for all userland binaries
257: compiled. The result is collected as an additional debug.tgz
258: and xdebug.tgz set and installed in /usr/libdata/debug.
259:
1.126 wiz 260: Default: "no"
1.106 wiz 261:
1.126 wiz 262: MKDEBUGLIB Can be set to "yes" or "no". Indicates whether debug
1.106 wiz 263: information (see MKDEBUG) should also be generated for all
1.134 sevan 264: libraries built.
1.106 wiz 265:
1.126 wiz 266: Default: "no"
1.106 wiz 267:
1.126 wiz 268: MKDOC Can be set to "yes" or "no". Indicates whether system
1.105 wiz 269: documentation destined for DESTDIR/usr/share/doc will be
1.44 lukem 270: installed during a build.
1.1 tv 271:
1.126 wiz 272: Default: "yes"
1.1 tv 273:
1.126 wiz 274: MKEXTSRC Can be set to "yes" or "no". Indicates whether extsrc is
1.115 apb 275: built from EXTSRCSRCDIR.
276:
1.126 wiz 277: Default: "no"
1.115 apb 278:
1.126 wiz 279: MKHTML Can be set to "yes" or "no". Indicates whether preformatted
280: HTML manual pages will be built and installed
1.77 lukem 281:
1.126 wiz 282: Default: "yes"
1.77 lukem 283:
1.126 wiz 284: MKHOSTOBJ Can be set to "yes" or "no". If set to "yes", then for
1.4 tv 285: programs intended to be run on the compile host, the name,
286: release, and architecture of the host operating system will
287: be suffixed to the name of the object directory created by
1.126 wiz 288: "make obj". (This allows multiple host systems to compile
289: NetBSD for a single target.) If set to "no", then programs
1.4 tv 290: built to be run on the compile host will use the same object
291: directory names as programs built to be run on the target.
292:
1.126 wiz 293: Default: "no"
1.4 tv 294:
1.126 wiz 295: MKINFO Can be set to "yes" or "no". Indicates whether GNU Info
1.134 sevan 296: files will be created and installed during a build. GNU Info
297: files are used for providing documentation by most of the
298: compilation tools.
1.1 tv 299:
1.126 wiz 300: Default: "yes"
1.1 tv 301:
1.126 wiz 302: MKKDEBUG Can be set to "yes" or "no". Force generation of full-debug
303: symbol versions of all kernels compiled. Alongside of the
304: netbsd kernel file, an unstripped version netbsd.gdb is
1.106 wiz 305: created. This is useful if a cross-gdb is built as well (see
306: MKCROSSGDB).
307:
1.126 wiz 308: Default: "no"
1.106 wiz 309:
1.126 wiz 310: MKKMOD Can be set to "yes" or "no". Indicates whether kernel
1.95 apb 311: modules are built and installed.
312:
1.126 wiz 313: Default: "yes"
1.95 apb 314:
1.126 wiz 315: MKLINT Can be set to "yes" or "no". Indicates whether lint(1) will
316: be run against portions of the NetBSD source code during the
317: build, and whether lint libraries will be installed into
1.105 wiz 318: DESTDIR/usr/libdata/lint.
1.1 tv 319:
1.126 wiz 320: Default: "yes"
1.1 tv 321:
1.126 wiz 322: MKMAN Can be set to "yes" or "no". Indicates whether manual pages
323: will be installed during a build.
1.1 tv 324:
1.126 wiz 325: Default: "yes"
1.1 tv 326:
1.126 wiz 327: MKNLS Can be set to "yes" or "no". Indicates whether Native
1.44 lukem 328: Language System locale zone files will be compiled and
329: installed during a build.
1.1 tv 330:
1.126 wiz 331: Default: "yes"
1.1 tv 332:
1.126 wiz 333: MKOBJ Can be set to "yes" or "no". Indicates whether object
334: directories will be created when running "make obj". If set
335: to "no", then all built files will be located inside the
336: regular source tree.
1.1 tv 337:
1.126 wiz 338: Default: "yes"
1.1 tv 339:
1.126 wiz 340: Note that setting MKOBJ to "no" is not recommended and may
1.70 dholland 341: cause problems when updating the tree with cvs(1).
342:
1.126 wiz 343: MKPIC Can be set to "yes" or "no". Indicates whether shared
1.1 tv 344: objects and libraries will be created and installed during a
1.126 wiz 345: build. If set to "no", the entire built system will be
1.1 tv 346: statically linked.
347:
1.130 sevan 348: Default: Platform dependent. As of this writing, all
349: platforms except m68000 default to "yes".
1.1 tv 350:
1.105 wiz 351: MKPICINSTALL
1.126 wiz 352: Can be set to "yes" or "no". Indicates whether the ar(1)
1.105 wiz 353: format libraries (lib*_pic.a), used to generate shared
1.44 lukem 354: libraries, are installed during a build.
1.1 tv 355:
1.126 wiz 356: Default: "yes"
1.1 tv 357:
1.126 wiz 358: MKPROFILE Can be set to "yes" or "no". Indicates whether profiled
1.105 wiz 359: libraries (lib*_p.a) will be built and installed during a
1.1 tv 360: build.
361:
1.126 wiz 362: Default: "yes"; however, some platforms turn off MKPROFILE by
363: default at times due to toolchain problems with profiled
1.1 tv 364: code.
365:
1.126 wiz 366: MKREPRO Can be set to "yes" or "no". Create reproducible builds.
1.100 wiz 367: This enables different switches to make two builds from the
368: same source tree result in the same build results.
369:
1.126 wiz 370: Default: "no" This may be set to "yes" by giving build.sh the
371: -P option.
1.100 wiz 372:
1.122 wiz 373: MKREPRO_TIMESTAMP
374: Unix timestamp. When MKREPRO is set, the timestamp of all
375: files in the sets will be set to this value.
376:
1.124 christos 377: Default: Unset. This may be set automatically to the latest
378: source tree timestamp using cvslatest(1) by giving build.sh
379: the -P option.
1.122 wiz 380:
1.126 wiz 381: MKSHARE Can be set to "yes" or "no". Indicates whether files
1.105 wiz 382: destined to reside in DESTDIR/usr/share will be built and
1.139 ! kamil 383: installed during a build. If set to "no", then all of MKDOC,
! 384: MKINFO, MKMAN, and MKNLS will be set to "no" unconditionally.
1.1 tv 385:
1.126 wiz 386: Default: "yes"
1.1 tv 387:
1.105 wiz 388: MKSTRIPIDENT
1.126 wiz 389: Can be set to "yes" or "no". Indicates whether RCS IDs, for
390: use with ident(1), should be stripped from program binaries
391: and shared libraries.
1.78 apb 392:
1.126 wiz 393: Default: "no"
1.78 apb 394:
1.126 wiz 395: MKSTRIPSYM Can be set to "yes" or "no". Indicates whether all local
396: symbols should be stripped from shared libraries. If "yes",
1.125 ozaki-r 397: strip all local symbols from shared libraries; the affect is
1.126 wiz 398: equivalent to the -x option of ld(1). If "no", strip only
399: temporary local symbols; the affect is equivalent to the -X
400: option of ld(1). Keeping non-temporary local symbols such as
1.125 ozaki-r 401: static function names is useful on using DTrace for userland
402: libraries and getting a backtrace from a rump kernel loading
403: shared libraries.
404:
1.126 wiz 405: Default: "yes"
1.125 ozaki-r 406:
1.126 wiz 407: MKUNPRIVED Can be set to "yes" or "no". Indicates whether an
1.104 wiz 408: unprivileged install will occur. The user, group,
409: permissions, and file flags, will not be set on the installed
1.52 jmc 410: items; instead the information will be appended to a file
1.105 wiz 411: called METALOG in DESTDIR. The contents of METALOG are used
1.52 jmc 412: during the generation of the distribution tar files to ensure
413: that the appropriate file ownership is stored.
1.38 lukem 414:
1.126 wiz 415: Default: "no"
1.38 lukem 416:
1.126 wiz 417: MKUPDATE Can be set to "yes" or "no". Indicates whether all install
418: operations intended to write to DESTDIR will compare file
419: timestamps before installing, and skip the install phase if
420: the destination files are up-to-date. This also has
1.44 lukem 421: implications on full builds (see next subsection).
1.38 lukem 422:
1.126 wiz 423: Default: "no"
1.38 lukem 424:
1.126 wiz 425: MKX11 Can be set to "yes" or "no". Indicates whether X11 is built
426: from X11SRCDIR.
1.49 lukem 427:
1.126 wiz 428: Default: "no"
1.49 lukem 429:
1.105 wiz 430: TOOLDIR Directory to hold the host tools, once built. If specified,
1.59 apb 431: must be an absolute path. This directory should be unique to
1.104 wiz 432: a given host system and NetBSD source tree. (However,
1.105 wiz 433: multiple targets may share the same TOOLDIR; the target-
1.104 wiz 434: dependent files have unique names.) If unset, a default
435: based on the uname(1) information of the host platform will
1.105 wiz 436: be created in the .OBJDIR of src.
1.1 tv 437:
1.105 wiz 438: Default: Unset.
1.1 tv 439:
1.105 wiz 440: USETOOLS Indicates whether the tools specified by TOOLDIR should be
1.126 wiz 441: used as part of a build in progress. Must be set to "yes" if
442: cross-compiling.
1.1 tv 443:
1.105 wiz 444: yes Use the tools from TOOLDIR.
1.1 tv 445:
1.105 wiz 446: no Do not use the tools from TOOLDIR, but refuse to build
1.1 tv 447: native compilation tool components that are version-
448: specific for that tool.
449:
1.105 wiz 450: never Do not use the tools from TOOLDIR, even when building
1.104 wiz 451: native tool components. This is similar to the
1.105 wiz 452: traditional NetBSD build method, but does not verify
1.104 wiz 453: that the compilation tools in use are up-to-date
454: enough in order to build the tree successfully. This
455: may cause build or runtime problems when building the
456: whole NetBSD source tree.
1.1 tv 457:
1.126 wiz 458: Default: "yes", unless TOOLCHAIN_MISSING is set to "yes".
1.71 dholland 459:
1.126 wiz 460: USETOOLS is also set to "no" when using <bsd.*.mk> outside
1.71 dholland 461: the NetBSD source tree.
1.1 tv 462:
1.121 mrg 463: X11SRCDIR Directory containing the modular Xorg source. If specified,
464: must be an absolute path. The main modular Xorg source is
465: found in X11SRCDIR/external/mit.
1.49 lukem 466:
1.135 leot 467: Default: NETBSDSRCDIR/../xsrc, if that exists; otherwise
1.105 wiz 468: /usr/xsrc.
1.49 lukem 469:
1.105 wiz 470: "make" variables for full builds
1.126 wiz 471: These variables only affect the top level "Makefile" and do not affect
1.7 lukem 472: manually building subtrees of the NetBSD source code.
1.1 tv 473:
1.126 wiz 474: INSTALLWORLDDIR Location for the "make installworld" target to install
1.59 apb 475: to. If specified, must be an absolute path.
1.1 tv 476:
1.126 wiz 477: Default: "/"
1.1 tv 478:
1.126 wiz 479: MKOBJDIRS Can be set to "yes" or "no". Indicates whether object
480: directories will be created automatically (via a "make
481: obj" pass) at the start of a build.
1.1 tv 482:
1.126 wiz 483: Default: "no"
1.1 tv 484:
1.126 wiz 485: If using build.sh, the default is "yes". This may be
486: set back to "no" by giving build.sh the -o option.
1.70 dholland 487:
1.126 wiz 488: MKUPDATE Can be set to "yes" or "no". If set, then in addition
489: to the effects described for MKUPDATE=yes above, this
490: implies the effects of NOCLEANDIR (i.e., "make cleandir"
491: is avoided).
1.38 lukem 492:
1.126 wiz 493: Default: "no"
1.38 lukem 494:
1.105 wiz 495: If using build.sh, this may be set by giving the -u
1.70 dholland 496: option.
497:
1.105 wiz 498: NBUILDJOBS Now obsolete. Use the make(1) option -j, instead. See
1.70 dholland 499: below.
1.1 tv 500:
1.105 wiz 501: Default: Unset.
1.1 tv 502:
1.126 wiz 503: NOCLEANDIR If set, avoids the "make cleandir" phase of a full
1.20 lukem 504: build. This has the effect of allowing only changed
505: files in a source tree to be recompiled. This can speed
506: up builds when updating only a few files in the tree.
1.1 tv 507:
1.105 wiz 508: Default: Unset.
1.1 tv 509:
1.105 wiz 510: See also MKUPDATE.
1.70 dholland 511:
1.126 wiz 512: NODISTRIBDIRS If set, avoids the "make distrib-dirs" phase of a full
1.105 wiz 513: build. This skips running mtree(8) on DESTDIR, useful
1.20 lukem 514: on systems where building as an unprivileged user, or
515: where it is known that the system-wide mtree files have
516: not changed.
1.1 tv 517:
1.105 wiz 518: Default: Unset.
1.1 tv 519:
1.126 wiz 520: NOINCLUDES If set, avoids the "make includes" phase of a full
1.20 lukem 521: build. This has the effect of preventing make(1) from
1.44 lukem 522: thinking that some programs are out-of-date simply
523: because the system include files have changed. However,
1.20 lukem 524: this option should not be used when updating the entire
525: NetBSD source tree arbitrarily; it is suggested to use
1.105 wiz 526: MKUPDATE=yes instead in that case.
1.1 tv 527:
1.105 wiz 528: Default: Unset.
1.1 tv 529:
1.105 wiz 530: RELEASEDIR If set, specifies the directory to which a release(7)
1.126 wiz 531: layout will be written at the end of a "make release".
1.59 apb 532: If specified, must be an absolute path.
1.20 lukem 533:
1.105 wiz 534: Default: Unset.
1.20 lukem 535:
1.105 wiz 536: Note: build.sh will provide a default of releasedir (in
537: the top-level .OBJDIR) unless run in `expert' mode.
1.30 lukem 538:
1.105 wiz 539: BUILDING
540: "make" command line options
1.52 jmc 541: This is not a summary of all the options available to make(1); only the
542: options used most frequently with NetBSD builds are listed here.
1.1 tv 543:
1.105 wiz 544: -j njob Run up to njob make(1) subjobs in parallel. Makefiles should
1.52 jmc 545: use .WAIT or have explicit dependencies as necessary to
1.74 apb 546: enforce build ordering.
1.10 sommerfe 547:
1.105 wiz 548: -m dir Specify the default directory for searching for system
1.104 wiz 549: Makefile segments, mainly the <bsd.*.mk> files. When building
550: any full NetBSD source tree, this should be set to the
1.126 wiz 551: "share/mk" directory in the source tree. This is set
1.104 wiz 552: automatically when building from the top level, or when using
1.105 wiz 553: build.sh.
1.1 tv 554:
1.105 wiz 555: -n Display the commands that would have been executed, but do not
1.1 tv 556: actually execute them. This will still cause recursion to
557: take place.
558:
1.105 wiz 559: -V var Print make(1)'s idea of the value of var. Does not build any
1.1 tv 560: targets.
561:
1.105 wiz 562: var=value Set the variable var to value, overriding any setting
563: specified by the process environment, the MAKECONF
1.104 wiz 564: configuration file, or the system Makefile segments.
1.1 tv 565:
1.105 wiz 566: "make" targets
1.1 tv 567: These default targets may be built by running make(1) in any subtree of
568: the NetBSD source code. It is recommended that none of these be used
1.126 wiz 569: from the top level Makefile; as a specific exception, "make obj" and
570: "make cleandir" are useful in that context.
1.1 tv 571:
1.105 wiz 572: all Build programs, libraries, and preformatted documentation.
1.1 tv 573:
1.105 wiz 574: clean Remove program and library object code files.
1.1 tv 575:
1.105 wiz 576: cleandir Same as clean, but also remove preformatted documentation,
1.126 wiz 577: dependency files generated by "make depend", and any other
1.49 lukem 578: files known to be created at build time.
1.1 tv 579:
1.105 wiz 580: depend Create dependency files (.depend) containing more detailed
1.44 lukem 581: information about the dependencies of source code on header
1.1 tv 582: files. Allows programs to be recompiled automatically when a
583: dependency changes.
584:
1.126 wiz 585: dependall Does a "make depend" immediately followed by a "make all".
1.10 sommerfe 586: This improves cache locality of the build since both passes
587: read the source files in their entirety.
1.1 tv 588:
1.105 wiz 589: distclean Synonym for cleandir.
1.49 lukem 590:
1.105 wiz 591: includes Build and install system header files. Typically needed
1.44 lukem 592: before any system libraries or programs can be built.
1.1 tv 593:
1.105 wiz 594: install Install programs, libraries, and documentation into DESTDIR.
595: Few files will be installed to DESTDIR/dev, DESTDIR/etc,
596: DESTDIR/root or DESTDIR/var in order to prevent user supplied
1.27 lukem 597: configuration data from being overwritten.
1.1 tv 598:
1.105 wiz 599: lint Run lint(1) against the C source code, where appropriate, and
1.1 tv 600: generate system-installed lint libraries.
601:
1.105 wiz 602: obj Create object directories to be used for built files, instead
1.1 tv 603: of building directly in the source tree.
604:
1.105 wiz 605: tags Create ctags(1) searchable function lists usable by the ex(1)
1.1 tv 606: and vi(1) text editors.
607:
1.105 wiz 608: "make" targets for the top level
1.1 tv 609: Additional make(1) targets are usable specifically from the top source
610: level to facilitate building the entire NetBSD source tree.
611:
1.105 wiz 612: build Build the entire NetBSD system (except the kernel). This
1.68 reed 613: orders portions of the source tree such that prerequisites
614: will be built in the proper order.
1.20 lukem 615:
1.126 wiz 616: distribution Do a "make build", and then install a full distribution
1.105 wiz 617: (which does not include a kernel) into DESTDIR, including
618: files in DESTDIR/dev, DESTDIR/etc, DESTDIR/root and
619: DESTDIR/var.
1.20 lukem 620:
1.126 wiz 621: buildworld As per "make distribution", except that it ensures that
1.105 wiz 622: DESTDIR is not the root directory.
1.20 lukem 623:
1.105 wiz 624: installworld Install the distribution from DESTDIR to INSTALLWORLDDIR,
1.70 dholland 625: which defaults to the root directory. Ensures that
1.105 wiz 626: INSTALLWORLDDIR is not the root directory if cross
1.104 wiz 627: compiling.
1.20 lukem 628:
1.105 wiz 629: The INSTALLSETS environment variable may be set to a space-
1.95 apb 630: separated list of distribution sets to be installed. By
1.126 wiz 631: default, all sets except "etc" and "xetc" are installed, so
632: most files in INSTALLWORLDDIR/etc will not be installed or
633: modified.
1.61 apb 634:
1.105 wiz 635: Note: Before performing this operation with
636: INSTALLWORLDDIR=/, it is highly recommended that you
1.61 apb 637: upgrade your kernel and reboot. After performing this
638: operation, it is recommended that you use etcupdate(8) to
1.105 wiz 639: update files in INSTALLWORLDDIR/etc, and postinstall(8) to
1.102 abs 640: check for or fix inconsistencies.
1.20 lukem 641:
1.105 wiz 642: sets Create distribution sets from DESTDIR into
643: RELEASEDIR/RELEASEMACHINEDIR/binary/sets. Should be run
1.126 wiz 644: after "make distribution", as "make build" alone does not
645: install all of the required files.
1.25 lukem 646:
1.105 wiz 647: sourcesets Create source sets of the source tree into
648: RELEASEDIR/source/sets.
1.31 lukem 649:
1.105 wiz 650: syspkgs Create syspkgs from DESTDIR into
651: RELEASEDIR/RELEASEMACHINEDIR/binary/syspkgs. Should be run
1.126 wiz 652: after "make distribution", as "make build" alone does not
653: install all of the required files.
1.54 apb 654:
1.126 wiz 655: release Do a "make distribution", build kernels, distribution
656: media, and install sets (this as per "make sets"), and then
657: package the system into a standard release layout as
1.105 wiz 658: described by release(7). This requires that RELEASEDIR be
1.25 lukem 659: set (see above).
1.1 tv 660:
1.105 wiz 661: iso-image Create a NetBSD installation CD-ROM image in the
1.114 snj 662: RELEASEDIR/images directory. The CD-ROM file system will
663: have a layout as described in release(7).
1.62 apb 664:
665: For most machine types, the CD-ROM will be bootable, and
1.104 wiz 666: will automatically run the sysinst(8) menu-based
667: installation program, which can be used to install or
668: upgrade a NetBSD system. Bootable CD-ROMs also contain
669: tools that may be useful in repairing a damaged NetBSD
670: installation.
1.62 apb 671:
1.126 wiz 672: Before "make iso-image" is attempted, RELEASEDIR must be
673: populated by "make release" or equivalent.
1.62 apb 674:
675: Note that other, smaller, CD-ROM images may be created in
1.105 wiz 676: the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
1.126 wiz 677: directory by "make release". These smaller images usually
678: contain the same tools as the larger images in
1.114 snj 679: RELEASEDIR/images, but do not contain additional content
680: such as the distribution sets.
1.62 apb 681:
682: Note that the mac68k port still uses an older method of
1.104 wiz 683: creating CD-ROM images. This requires the mkisofs(1)
684: utility, which is not part of NetBSD, but which can be
1.105 wiz 685: installed from pkgsrc/sysutils/cdrtools.
1.56 apb 686:
1.105 wiz 687: iso-image-source
1.64 jnemeth 688: Create a NetBSD installation CD-ROM image in the
1.114 snj 689: RELEASEDIR/images directory. The CD-ROM file system will
690: have a layout as described in release(7). It will have top
1.64 jnemeth 691: level directories for the machine type and source.
692:
693: For most machine types, the CD-ROM will be bootable, and
1.104 wiz 694: will automatically run the sysinst(8) menu-based
695: installation program, which can be used to install or
696: upgrade a NetBSD system. Bootable CD-ROMs also contain
697: tools that may be useful in repairing a damaged NetBSD
698: installation.
1.64 jnemeth 699:
1.126 wiz 700: Before "make iso-image-source" is attempted, RELEASEDIR
701: must be populated by "make sourcesets release" or
1.104 wiz 702: equivalent.
1.64 jnemeth 703:
704: Note that other, smaller, CD-ROM images may be created in
1.105 wiz 705: the RELEASEDIR/RELEASEMACHINEDIR/installation/cdrom
1.126 wiz 706: directory by "make release". These smaller images usually
707: contain the same tools as the larger images in
1.114 snj 708: RELEASEDIR/images, but do not contain additional content
709: such as the distribution sets.
1.64 jnemeth 710:
711: Note that the mac68k port still uses an older method of
1.104 wiz 712: creating CD-ROM images. This requires the mkisofs(1)
713: utility, which is not part of NetBSD, but which can be
1.105 wiz 714: installed from pkgsrc/sysutils/cdrtools.
1.64 jnemeth 715:
1.105 wiz 716: install-image
1.98 apb 717: Create a bootable NetBSD installation disk image in the
1.127 plunky 718: RELEASEDIR/images directory. The installation disk image
719: is suitable for copying to bootable USB flash memory
720: sticks, etc., for machines which are able to boot from such
721: devices. The file system in the bootable disk image will
722: have a layout as described in release(7).
1.97 tsutsui 723:
724: The installation image is bootable, and will automatically
725: run the sysinst(8) menu-based installation program, which
1.98 apb 726: can be used to install or upgrade a NetBSD system. The
727: image also contains tools that may be useful in repairing a
728: damaged NetBSD installation.
1.97 tsutsui 729:
1.126 wiz 730: Before "make install-image" is attempted, RELEASEDIR must
731: be populated by "make release" or equivalent. The build
732: must have been performed with MKUNPRIVED=yes because "make
733: install-image" relies on information in DESTDIR/METALOG.
1.97 tsutsui 734:
1.120 pgoyette 735: live-image Create NetBSD live images in the RELEASEDIR/images
1.104 wiz 736: directory. The live image contains all necessary files to
737: boot NetBSD up to multi-user mode, including all files
738: which should be extracted during installation, NetBSD
739: disklabel, bootloaders, etc.
740:
741: The live image is suitable for use as a disk image in
742: virtual machine environments such as QEMU, and also useful
743: to boot NetBSD from a USB flash memory stick on a real
1.98 apb 744: machine, without the need for installation.
1.97 tsutsui 745:
1.126 wiz 746: Before "make live-image" is attempted, RELEASEDIR must be
747: populated by "make release" or equivalent. The build must
748: have been performed with MKUNPRIVED=yes because "make
749: install-image" relies on information in DESTDIR/METALOG.
1.97 tsutsui 750:
1.105 wiz 751: regression-tests
1.20 lukem 752: Can only be run after building the regression tests in the
1.126 wiz 753: directory "regress". Runs those compiled regression tests
754: on the local host. Note that most tests are now managed
755: instead using atf(7); this target should probably run those
756: as well but currently does not.
1.1 tv 757:
1.105 wiz 758: The "build.sh" script
1.96 apb 759: This script file is a shell script designed to build the entire NetBSD
1.104 wiz 760: system on any host with a suitable modern shell and some common
1.105 wiz 761: utilities. The required shell features are described under the HOST_SH
1.104 wiz 762: variable.
1.96 apb 763:
764: If a host system's default shell does support the required features, then
765: we suggest that you explicitly specify a suitable shell using a command
766: like
767:
1.105 wiz 768: /path/to/suitable/shell build.sh [options]
1.96 apb 769:
1.105 wiz 770: The above command will usually enable build.sh to automatically set
771: HOST_SH=/path/to/suitable/shell, but if that fails, then the following
1.96 apb 772: set of commands may be used instead:
773:
1.105 wiz 774: HOST_SH=/path/to/suitable/shell
1.96 apb 775: export HOST_SH
1.105 wiz 776: ${HOST_SH} build.sh [options]
1.96 apb 777:
1.105 wiz 778: If build.sh detects that it is being executed under an unsuitable shell,
1.96 apb 779: it attempts to exec a suitable shell instead, or prints an error message.
1.105 wiz 780: If HOST_SH is not set explicitly, then build.sh sets a default using
1.96 apb 781: heuristics dependent on the host platform, or from the shell under which
1.105 wiz 782: build.sh is executed (if that can be determined), or using the first copy
783: of sh found in PATH.
1.1 tv 784:
785: All cross-compile builds, and most native builds, of the entire system
1.126 wiz 786: should make use of build.sh rather than just running "make". This way,
1.104 wiz 787: the make(1) program will be bootstrapped properly, in case the host
1.126 wiz 788: system has an older or incompatible "make" program.
1.1 tv 789:
1.105 wiz 790: When compiling the entire system via build.sh, many make(1) variables are
1.1 tv 791: set for you in order to help encapsulate the build process. In the list
1.105 wiz 792: of options below, variables that are automatically set by build.sh are
1.1 tv 793: noted where applicable.
794:
1.105 wiz 795: The following operations are supported by build.sh:
1.22 lukem 796:
1.126 wiz 797: build Build the system as per "make build". Before the main part
798: of the build commences, this command runs the obj operation
799: (unless the -o option is given), "make cleandir" (unless
800: the -u option is given), and the tools operation.
1.22 lukem 801:
1.126 wiz 802: distribution Build a full distribution as per "make distribution". This
803: command first runs the build operation.
1.22 lukem 804:
1.126 wiz 805: release Build a full release as per "make release". This command
1.105 wiz 806: first runs the distribution operation.
1.22 lukem 807:
1.105 wiz 808: makewrapper Create the nbmake-MACHINE wrapper. This operation is
1.104 wiz 809: automatically performed for any of the other operations.
1.23 lukem 810:
1.126 wiz 811: cleandir Perform "make cleandir".
1.75 lukem 812:
1.126 wiz 813: obj Perform "make obj".
1.22 lukem 814:
1.105 wiz 815: tools Build and install the host tools from src/tools. This
1.126 wiz 816: command will first run "make obj" and "make cleandir" in
817: the tools subdirectory unless the -o or -u options
1.104 wiz 818: (respectively) are given.
1.22 lukem 819:
1.126 wiz 820: install=idir Install the contents of DESTDIR to idir, using "make
821: installworld". Note that files that are part of the "etc"
822: or "xetc" sets will not be installed, unless overridden by
823: the INSTALLSETS environment variable.
1.35 lukem 824:
1.105 wiz 825: kernel=kconf Build a new kernel. The kconf argument is the name of a
826: configuration file suitable for use by config(1). If kconf
1.22 lukem 827: does not contain any `/' characters, the configuration file
1.105 wiz 828: is expected to be found in the KERNCONFDIR directory, which
829: is typically sys/arch/MACHINE/conf. The new kernel will be
830: built in a subdirectory of KERNOBJDIR, which is typically
831: sys/arch/MACHINE/compile or an associated object directory.
1.70 dholland 832:
1.105 wiz 833: This command does not imply the tools command; run the
834: tools command first unless it is certain that the tools
1.70 dholland 835: already exist and are up to date.
836:
1.126 wiz 837: This command will run "make cleandir" on the kernel in
1.105 wiz 838: question first unless the -u option is given.
1.22 lukem 839:
1.106 wiz 840: kernel.gdb=kconf
841: Build a new kernel with debug information. Similar to the
842: above kernel=kconf operation, but creates a netbsd.gdb file
843: alongside of the kernel netbsd, which contains a full
844: symbol table and can be used for debugging (for example
845: with a cross-gdb built by MKCROSSGDB).
846:
1.113 uebayasi 847: kernels This command will build all kernels defined in port
848: specific release build procedure.
1.111 uebayasi 849:
1.112 uebayasi 850: This command internally calls the kernel=kconf operation
851: for each found kernel configuration file.
1.111 uebayasi 852:
1.105 wiz 853: modules This command will build kernel modules and install them
854: into DESTDIR.
1.86 jnemeth 855:
1.105 wiz 856: releasekernel=kconf
1.70 dholland 857: Install a gzip(1)ed copy of the kernel previously built by
1.105 wiz 858: kernel=kconf into
859: RELEASEDIR/RELEASEMACHINEDIR/binary/kernel, usually as
1.126 wiz 860: netbsd-kconf.gz, although the "netbsd" prefix is determined
861: from the "config" directives in kconf.
1.24 lukem 862:
1.126 wiz 863: sets Perform "make sets".
1.31 lukem 864:
1.126 wiz 865: sourcesets Perform "make sourcesets".
1.22 lukem 866:
1.126 wiz 867: syspkgs Perform "make syspkgs".
1.54 apb 868:
1.126 wiz 869: iso-image Perform "make iso-image".
1.56 apb 870:
1.105 wiz 871: iso-image-source
1.126 wiz 872: Perform "make iso-image-source".
1.65 jnemeth 873:
1.105 wiz 874: install-image
1.126 wiz 875: Perform "make install-image".
1.97 tsutsui 876:
1.126 wiz 877: live-image Perform "make live-image".
1.97 tsutsui 878:
1.109 apb 879: list-arch Prints a list of valid MACHINE and MACHINE_ARCH settings,
880: the default MACHINE_ARCH for each MACHINE, and aliases for
881: MACHINE/MACHINE_ARCH pairs, and then exits. The -m or -a
882: options (or both) may be used to specify glob patterns that
883: will be used to narrow the list of results; for example,
1.131 leot 884: "build.sh -m 'evb*' -a '*arm*' list-arch" will list all
1.109 apb 885: known MACHINE/MACHINE_ARCH values in which either MACHINE
886: or ALIAS matches the pattern `evb*', and MACHINE_ARCH
887: matches the pattern `*arm*'.
888:
1.105 wiz 889: The following command line options alter the behaviour of the build.sh
1.51 wiz 890: operations described above:
1.1 tv 891:
1.109 apb 892: -a arch Set the value of MACHINE_ARCH to arch. See the -m option for
893: more information.
1.9 thorpej 894:
1.105 wiz 895: -B buildid
896: Set the value of BUILDID to buildid. This will also append the
1.126 wiz 897: build identifier to the name of the "make" wrapper script so
1.37 lukem 898: that the resulting name is of the form
1.126 wiz 899: "nbmake-MACHINE-BUILDID".
1.1 tv 900:
1.105 wiz 901: -C cdextras
902: Append cdextras to the CDEXTRA variable, which is a space-
1.104 wiz 903: separated list of files or directories that will be added to
1.126 wiz 904: the CD-ROM image that may be create by the "iso-image" or
905: "iso-image-source" operations. Files will be added to the root
906: of the CD-ROM image, whereas directories will be copied
1.87 apb 907: recursively. If relative paths are specified, they will be
908: converted to absolute paths before being used. Multiple paths
1.105 wiz 909: may be specified via multiple -C options, or via a single
1.87 apb 910: option whose argument contains multiple space-separated paths.
1.66 jnemeth 911:
1.136 uwe 912: -c compiler
913: Select the compiler for the toolchain to build NetBSD and for
914: inclusion in the NetBSD distribution. Supported choices:
915:
916: clang
917:
918: gcc [default]
919:
920: The compiler used to build the toolchain can be different; see
921: HOST_CC and HOST_CXX.
922:
1.105 wiz 923: -D dest Set the value of DESTDIR to dest. If a relative path is
1.104 wiz 924: specified, it will be converted to an absolute path before
925: being used.
926:
1.105 wiz 927: -E Set `expert' mode. This overrides various sanity checks, and
928: allows: DESTDIR does not have to be set to a non-root path for
929: builds, and MKUNPRIVED=yes does not have to be set when
1.104 wiz 930: building as a non-root user.
1.23 lukem 931:
1.105 wiz 932: Note: It is highly recommended that you know what you are doing
1.23 lukem 933: when you use this option.
1.19 lukem 934:
1.105 wiz 935: -h Print a help message.
1.51 wiz 936:
1.105 wiz 937: -j njob Run up to njob make(1) subjobs in parallel; passed through to
1.74 apb 938: make(1). If you see failures for reasons other than running
1.105 wiz 939: out of memory while using build.sh with -j, please save
1.104 wiz 940: complete build logs so the failures can be analyzed.
1.74 apb 941:
1.105 wiz 942: To achieve the fastest builds, -j values between (1 + the
1.104 wiz 943: number of CPUs) and (2 * the number of CPUs) are recommended.
944: Use lower values on machines with limited memory or I/O
945: bandwidth.
946:
1.126 wiz 947: -M obj Set MAKEOBJDIRPREFIX to obj. Unsets MAKEOBJDIR. See "-O obj"
948: for more information.
1.104 wiz 949:
1.105 wiz 950: For instance, if the source directory is /usr/src, a setting of
1.126 wiz 951: "-M /usr/obj" will place build-time files under
1.105 wiz 952: /usr/obj/usr/src/bin, /usr/obj/usr/src/lib,
953: /usr/obj/usr/src/usr.bin, and so forth.
1.88 apb 954:
1.73 apb 955: If a relative path is specified, it will be converted to an
1.105 wiz 956: absolute path before being used. build.sh imposes the
957: restriction that the argument to the -M option must not begin
1.126 wiz 958: with a "$" (dollar sign) character; otherwise it would be too
1.104 wiz 959: difficult to determine whether the value is an absolute or a
960: relative path. If the directory does not already exist,
1.105 wiz 961: build.sh will create it.
1.18 lukem 962:
1.109 apb 963: -m mach Set the value of MACHINE to mach, unless the mach argument is
964: an alias that refers to a MACHINE/MACHINE_ARCH pair, in which
965: case both MACHINE and MACHINE_ARCH are set from the alias.
966: Such aliases are interpreted entirely by build.sh; they are not
967: used by any other part of the build system. The MACHINE_ARCH
968: setting implied by mach will override any value of MACHINE_ARCH
969: in the process environment, but will not override a value set
970: by the -a option. All cross builds require -m, but if unset on
971: a NetBSD host, the host's value of MACHINE will be detected and
972: used automatically.
973:
974: See the list-arch operation for a way to get a list of valid
975: MACHINE and MACHINE_ARCH settings.
1.1 tv 976:
1.105 wiz 977: -N noiselevel
1.126 wiz 978: Set the "noisyness" level of the build, by setting MAKEVERBOSE
979: to noiselevel.
1.45 lukem 980:
1.105 wiz 981: -n Show the commands that would be executed by build.sh, but do
1.126 wiz 982: not make any changes. This is similar in concept to "make -n".
1.1 tv 983:
1.105 wiz 984: -O obj Create an appropriate transform macro for MAKEOBJDIR that will
985: place the built object files under obj. Unsets
986: MAKEOBJDIRPREFIX.
1.88 apb 987:
1.126 wiz 988: For instance, a setting of "-O /usr/obj" will place build-time
989: files under /usr/obj/bin, /usr/obj/lib, /usr/obj/usr.bin, and
990: so forth.
1.88 apb 991:
992: If a relative path is specified, it will be converted to an
1.105 wiz 993: absolute path before being used. build.sh imposes the
994: restriction that the argument to the -O option must not contain
1.126 wiz 995: a "$" (dollar sign) character. If the directory does not
1.105 wiz 996: already exist, build.sh will create it.
1.73 apb 997:
1.105 wiz 998: In normal use, exactly one of the -M or -O options should be
999: specified. If neither -M nor -O is specified, then a default
1.78 apb 1000: object directory will be chosen according to rules in
1001: <bsd.obj.mk>. Relying on this default is not recommended
1002: because it is determined by complex rules that are influenced
1003: by the values of several variables and by the location of the
1004: source directory.
1.18 lukem 1005:
1.109 apb 1006: Note that placing the obj directory location outside of the
1007: default source tree hierarchy makes it easier to manually clear
1.126 wiz 1008: out old files in the event the "make cleandir" operation is
1.109 apb 1009: unable to do so. (See CAVEATS below.)
1010:
1011: Note also that use of one of -M or -O is the only means of
1012: building multiple machine architecture userlands from the same
1013: source tree without cleaning between builds (in which case, one
1014: would specify distinct obj locations for each).
1015:
1.126 wiz 1016: -o Set the value of MKOBJDIRS to "no". Otherwise, it will be
1017: automatically set to "yes". This default is opposite to the
1.105 wiz 1018: behaviour when not using build.sh.
1.1 tv 1019:
1.105 wiz 1020: -R rel Set the value of RELEASEDIR to rel. If a relative path is
1.59 apb 1021: specified, it will be converted to an absolute path before
1022: being used.
1.18 lukem 1023:
1.105 wiz 1024: -r Remove the contents of DESTDIR and TOOLDIR before building
1.1 tv 1025: (provides a clean starting point). This will skip deleting
1.105 wiz 1026: DESTDIR if building on a native system to the root directory.
1.1 tv 1027:
1.105 wiz 1028: -S seed Change the value of BUILDSEED to seed. This should rarely be
1.72 perry 1029: necessary.
1030:
1.105 wiz 1031: -T tools Set the value of TOOLDIR to tools. If a relative path is
1.104 wiz 1032: specified, it will be converted to an absolute path before
1.126 wiz 1033: being used. If set, the bootstrap "make" will only be rebuilt
1034: if the source files for make(1) have changed.
1.104 wiz 1035:
1.105 wiz 1036: -U Set MKUNPRIVED=yes.
1.104 wiz 1037:
1.105 wiz 1038: -u Set MKUPDATE=yes.
1.104 wiz 1039:
1.105 wiz 1040: -V var=[value]
1041: Set the environment variable var to an optional value. This is
1042: propagated to the nbmake wrapper.
1043:
1044: -w wrapper
1045: Create the nbmake wrapper script (see below) in a custom
1046: location, specified by wrapper. This allows, for instance, to
1047: place the wrapper in PATH automatically. Note that wrapper is
1.59 apb 1048: the full name of the file, not just a directory name. If a
1049: relative path is specified, it will be converted to an absolute
1050: path before being used.
1.1 tv 1051:
1.105 wiz 1052: -X x11src
1053: Set the value of X11SRCDIR to x11src. If a relative path is
1.59 apb 1054: specified, it will be converted to an absolute path before
1055: being used.
1.49 lukem 1056:
1.105 wiz 1057: -x Set MKX11=yes.
1.49 lukem 1058:
1.115 apb 1059: -Y extsrcdir
1060: Set the value of EXTSRCSRCDIR to extsrcdir. If a relative path
1061: is specified, it will be converted to an absolute path before
1062: being used.
1063:
1064: -y Set MKEXTSRC=yes.
1065:
1.105 wiz 1066: -Z var Unset ("zap") the environment variable var. This is propagated
1067: to the nbmake wrapper.
1.40 lukem 1068:
1.105 wiz 1069: The "nbmake-MACHINE" wrapper script
1070: If using the build.sh script to build NetBSD, a nbmake-MACHINE script
1071: will be created in TOOLDIR/bin upon the first build to assist in building
1.1 tv 1072: subtrees on a cross-compile host.
1073:
1.105 wiz 1074: nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
1.126 wiz 1075: the up-to-date version of "nbmake" installed into TOOLDIR/bin with
1.105 wiz 1076: several key variables pre-set, including MACHINE, MACHINE_ARCH, and
1077: TOOLDIR. nbmake-MACHINE will also set variables specified with -V, and
1078: unset variables specified with -Z.
1.40 lukem 1079:
1.105 wiz 1080: This script can be symlinked into a directory listed in PATH, or called
1.1 tv 1081: with an absolute path.
1082:
1.105 wiz 1083: EXAMPLES
1.78 apb 1084: 1. % ./build.sh [options] tools kernel=GENERIC
1.28 lukem 1085:
1086: Build a new toolchain, and use the new toolchain to configure and
1087: build a new GENERIC kernel.
1088:
1.78 apb 1089: 2. % ./build.sh [options] -U distribution
1.28 lukem 1090:
1.105 wiz 1091: Using unprivileged mode, build a complete distribution to a DESTDIR
1092: directory that build.sh selects (and will display).
1.28 lukem 1093:
1.78 apb 1094: 3. # ./build.sh [options] -U install=/
1.28 lukem 1095:
1.105 wiz 1096: As root, install to / the distribution that was built by example 2.
1097: Even though this is run as root, -U is required so that the
1098: permissions stored in DESTDIR/METALOG are correctly applied to the
1099: files as they're copied to /.
1.28 lukem 1100:
1.78 apb 1101: 4. % ./build.sh [options] -U -u release
1.28 lukem 1102:
1.105 wiz 1103: Using unprivileged mode, build a complete release to DESTDIR and
1104: RELEASEDIR directories that build.sh selects (and will display).
1.126 wiz 1105: MKUPDATE=yes (-u) is set to prevent the "make cleandir", so that if
1106: this is run after example 2, it doesn't need to redo that portion of
1107: the release build.
1.16 lukem 1108:
1.105 wiz 1109: OBSOLETE VARIABLES
1110: NBUILDJOBS Use the make(1) option -j instead.
1.15 lukem 1111:
1.105 wiz 1112: USE_NEW_TOOLCHAIN
1.15 lukem 1113: The new toolchain is now the default. To disable, use
1.105 wiz 1114: TOOLCHAIN_MISSING=yes.
1.10 sommerfe 1115:
1.105 wiz 1116: SEE ALSO
1.62 apb 1117: make(1), hier(7), release(7), etcupdate(8), postinstall(8), sysinst(8),
1.105 wiz 1118: pkgsrc/sysutils/cdrtools
1.1 tv 1119:
1.105 wiz 1120: HISTORY
1121: The build.sh based build scheme was introduced for NetBSD 1.6 as
1122: USE_NEW_TOOLCHAIN, and re-worked to TOOLCHAIN_MISSING after that.
1.1 tv 1123:
1.109 apb 1124: CAVEATS
1125: After significant updates to third-party components in the source tree,
1.126 wiz 1126: the "make cleandir" operation may be insufficient to clean out old files
1127: in object directories. Instead, one may have to manually remove the
1128: files. Consult the UPDATING file for notices concerning this.
1.109 apb 1129:
1.137 uwe 1130: NetBSD October 13, 2020 NetBSD
CVSweb <webmaster@jp.NetBSD.org>