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