xref: /netbsd-src/doc/BUILDING.mdoc (revision bdc22b2e01993381dcefeff2bc9b56ca75a4235c)
1.\"	$NetBSD: BUILDING.mdoc,v 1.124 2018/02/16 10:05:01 leot Exp $
2.\"
3.\" Copyright (c) 2001-2011 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Todd Vierling and Luke Mewburn.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" NOTE: After changing this file, run "make regen" in the src/doc
31.\" directory, and check in both src/BUILDING and src/doc/BUILDING.mdoc.
32.\"
33.\" Toolchain prefix for commands
34.ds toolprefix nb
35.
36.Dd October 21, 2017
37.Dt BUILDING 8
38.Os NetBSD
39.
40.Sh NAME
41.
42.Nm BUILDING
43.Nd Procedure for building
44.Nx
45from source code.
46.
47.Sh REQUIREMENTS
48.
49.Nx
50is designed to be buildable on most POSIX-compliant host systems.
51The basic build procedure is the same whether compiling
52.Em natively
53(on the same
54.Nx
55architecture) or
56.Em cross compiling
57(on another architecture or OS).
58.Pp
59This source tree contains a special subtree,
60.Dq tools ,
61which uses the host system to create a build toolchain for the target
62architecture.
63The host system must have at least C and C++
64compilers in order to create the toolchain
65.Nm ( make
66is not required); all other tools are created as part of the
67.Nx
68build process.
69(See the environment variables section below if you need
70to override or manually select your compilers.)
71.
72.Sh FILES
73.
74.Ss Source tree layout
75.
76.Bl -tag -width "BUILDING.mdoc"
77.It Pa doc/BUILDING.mdoc
78This document (in -mdoc troff format; the original copy).
79.It Pa BUILDING
80This document (in plaintext).
81.It Pa tools/compat/README
82Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
83.It Pa Makefile
84The main Makefile for
85.Nx ;
86should only be run for native builds with an appropriately up-to-date
87version of
88.Nx
89.Xr make 1 .
90Intended for expert use with knowlege of its shortcomings, it has been superseded
91by the
92.Nm build.sh
93shell script as the recommended means for building
94.Nx .
95.It Pa UPDATING
96Special notes for updating from an earlier revision of
97.Nx .
98It is important to read this file before every build of an updated
99source tree.
100.It Pa build.sh
101Bourne-compatible shell script used for building the host build tools
102and the
103.Nx
104system from scratch.
105Can be used for both native and cross builds, and should be used instead of
106.Xr make 1
107as it performs additional checks to prevent common issues going undetected, such
108as building with an outdated version of
109.Xr make 1 .
110.It Pa crypto/dist/ , dist/ , gnu/dist/
111Sources imported verbatim from third parties, without mangling the
112existing build structure.
113Other source trees in
114.Sy bin
115through
116.Sy usr.sbin
117use the
118.Nx
119.Xr make 1
120.Dq reachover
121Makefile semantics when building these programs for a native host.
122.It Pa external , sys/external
123Sources and build infrastructure for components imported (mostly) unchanged
124from upstream maintainers, sorted by applicable license.
125This is (slowly) replacing the
126.Pa crypto/dist ,
127.Pa dist ,
128and
129.Pa gnu/dist
130directories.
131.It Pa distrib/ , etc/
132Sources for items used when making a full release snapshot, such as
133files installed in
134.Sy DESTDIR Ns Pa /etc
135on the destination system, boot media, and release notes.
136.It Pa tests/ , regress/
137Regression test harness.
138Can be cross-compiled, but only run natively.
139.Pa tests/
140uses the
141.Xr atf 7
142test framework;
143.Pa regress/
144contains older tests that have not yet been migrated to
145.Xr atf 7 .
146.It Pa sys/
147.Nx
148kernel sources.
149.It Pa tools/
150.Dq Reachover
151build structure for the host build tools.
152This has a special method of determining out-of-date status.
153.It Pa bin/ ... usr.sbin/
154Sources to the
155.Nx
156userland (non-kernel) programs.
157If any of these directories are missing, they will be skipped during the build.
158.It Pa external/mit/xorg/
159.Dq Reachover
160build structure for modular Xorg; the source is in
161.Sy X11SRCDIR .
162.It Pa extsrc/
163.Dq Reachover
164build structure for externally added programs and libraries;
165the source is in
166.Sy EXTSRCSRCDIR .
167.El
168.
169.Ss Build tree layout
170.
171The
172.Nx
173build tree is described in
174.Xr hier 7 ,
175and the release layout is described in
176.Xr release 7 .
177.
178.Sh CONFIGURATION
179.
180.Ss Environment variables
181.
182Several environment variables control the behaviour of
183.Nx
184builds.
185.
186.Bl -tag -width "MAKEOBJDIRPREFIX"
187.
188.
189.It Sy HOST_SH
190Path name to a shell available on the host system
191and suitable for use during the build.
192The
193.Nx
194build system requires a modern Bourne-like shell
195with POSIX-compliant features,
196and also requires support for the
197.Dq local
198keyword to declare local variables in shell functions
199(which is a widely-implemented but non-standardised feature).
200.Pp
201Depending on the host system, a suitable shell may be
202.Pa /bin/sh ,
203.Pa /usr/xpg4/bin/sh ,
204.Pa /bin/ksh
205(provided it is a variant of ksh that supports the
206.Dq local
207keyword,
208such as ksh88, but not ksh93),
209or
210.Pa /usr/local/bin/bash .
211.Pp
212Most parts of the build require
213.Sy HOST_SH
214to be an absolute path; however,
215.Nm build.sh
216allows it to be a simple command name, which will be converted
217to an absolute path by searching the
218.Sy PATH .
219.
220.It Sy HOST_CC
221Path name to C compiler used to create the toolchain.
222.
223.It Sy HOST_CXX
224Path name to C++ compiler used to create the toolchain.
225.
226.It Sy MACHINE
227Machine type, e.g.,
228.Dq macppc .
229.
230.It Sy MACHINE_ARCH
231Machine architecture, e.g.,
232.Dq powerpc .
233.
234.It Sy MAKE
235Path name to invoke
236.Xr make 1
237as.
238.
239.It Sy MAKEFLAGS
240Flags to invoke
241.Xr make 1
242with.
243Note that
244.Sy build.sh
245ignores the value of
246.Sy MAKEFLAGS
247passed in the environment, but allows
248.Sy MAKEFLAGS
249to be set via the
250.Fl V
251option.
252.
253.It Sy MAKEOBJDIR
254Directory to use as the
255.Sy .OBJDIR
256for the current directory.
257The value is subjected to variable expansion by
258.Xr make 1 .
259Typical usage is to set this variable to a value involving the use of
260.Sq ${.CURDIR:S...}
261or
262.Sq ${.CURDIR:C...} ,
263to derive the value of
264.Sy .OBJDIR
265from the value of
266.Sy .CURDIR .
267Used only if
268.Sy MAKEOBJDIRPREFIX
269is not defined.
270.Sy MAKEOBJDIR
271can be provided only in the environment or via the
272.Fl O
273flag of
274.Nm build.sh ;
275it cannot usefully be set inside a Makefile, including
276.Pa mk.conf
277or
278.Sy ${MAKECONF} .
279.
280.It Sy MAKEOBJDIRPREFIX
281Top level directory of the object directory tree.
282The value is subjected to variable expansion by
283.Xr make 1 .
284.Sy build.sh
285will create the
286${MAKEOBJDIRPREFIX}
287directory if necessary, but if
288.Xr make 1
289is used without
290.Sy build.sh ,
291then rules in
292.Aq bsd.obj.mk
293will abort the build if the
294${MAKEOBJDIRPREFIX}
295directory does not exist.
296If the value is defined and valid, then
297${MAKEOBJDIRPREFIX}/${.CURDIR}
298is used as the
299.Sy .OBJDIR
300for the current directory.
301The current directory may be read only.
302.Sy MAKEOBJDIRPREFIX
303can be provided only in the environment or via the
304.Fl M
305flag of
306.Nm build.sh ;
307it cannot usefully be set inside a Makefile, including
308.Pa mk.conf
309or
310.Sy ${MAKECONF} .
311.
312.El
313.
314.Ss \*qmake\*q variables
315.
316.de YorN
317Can be set to
318.Dq yes
319or
320.Dq no .
321..
322.de DFLT
323.Pp
324.Em Default :
325..
326.de DFLTu
327.DFLT
328Unset.
329..
330.de DFLTy
331.DFLT
332.Dq yes
333..
334.de DFLTn
335.DFLT
336.Dq no
337..
338Several variables control the behavior of
339.Nx
340builds.
341Unless otherwise specified, these variables may be set in
342either the process environment or the
343.Xr make 1
344configuration file specified by
345.Sy MAKECONF .
346.
347.Bl -tag -width "MKCATPAGES"
348.
349.It Sy BUILDID
350Identifier for the build.
351If set, this should be a short string that is suitable for use as
352part of a file or directory name.
353The identifier will be appended to
354object directory names, and can be consulted in the
355.Xr make 1
356configuration file in order to set additional build parameters,
357such as compiler flags.
358It will also be used as part of the kernel version string,
359which can be printed by
360.Dq Li uname \-v .
361.DFLTu
362.
363.It Sy BUILDINFO
364This may be a multi-line string containing information about the build.
365This will appear in
366.Sy DESTDIR Ns Pa /etc/release ,
367and it will be stored in the
368.Va buildinfo
369variable in any kernels that are built.
370When such kernels are booted, the
371.Xr sysctl 7
372.Va kern.buildinfo
373variable will report this value.
374The string may contain backslash escape sequences, such as
375.Dq "\e\e"
376(representing a backslash character)
377and
378.Dq "\en"
379(representing a newline).
380.DFLTu
381.
382.It Sy BUILDSEED
383GCC uses random numbers when compiling C++ code.
384This variable seeds the gcc random number generator using
385the -frandom-seed flag with this value.
386By default, it is set to NetBSD-(majorversion).
387Using a fixed value causes C++ binaries to be the same when
388built from the same sources, resulting in identical (reproducible) builds.
389Additional information is available in the GCC
390documentation of -frandom-seed.
391.
392.It Sy DESTDIR
393Directory to contain the built
394.Nx
395system.
396If set, special options are passed to the compilation tools to
397prevent their default use of the host system's
398.Pa /usr/include , /usr/lib ,
399and so forth.
400This pathname must be an absolute path, and should
401.Em not
402end with a slash
403.Pq /
404character.
405(For installation into the system's root directory, set
406.Sy DESTDIR
407to an empty string, not to
408.Dq / ) .
409The directory must reside on a file system which supports long file
410names and hard links.
411.DFLT
412Empty string if
413.Sy USETOOLS
414is
415.Dq yes ;
416unset otherwise.
417.Pp
418.Em Note :
419.Sy build.sh
420will provide a default of
421.Pa destdir. Ns Sy MACHINE
422(in the top-level
423.Sy .OBJDIR )
424unless run in
425.Sq expert
426mode.
427.
428.It Sy EXTSRCSRCDIR
429Directory containing sources of externally added programs
430and libraries.
431If specified, must be an absolute path.
432.DFLT
433.Sy NETBSDRCDIR Ns Pa /../extsrc ,
434if that exists; otherwise
435.Pa /usr/extsrc .
436.
437.It Sy MAKECONF
438The name of the
439.Xr make 1
440configuration file.
441.Em Only settable in the process environment.
442.DFLT
443.Dq /etc/mk.conf
444.
445.It Sy MAKEVERBOSE
446Level of verbosity of status messages.
447Supported values:
448.Bl -tag -width xxx
449.It 0
450No descriptive messages or commands executed by
451.Xr make 1
452are shown.
453.It 1
454Brief messages are shown describing what is being done,
455but the actual commands executed by
456.Xr make 1
457are not displayed.
458.It 2
459Descriptive messages are shown as above (prefixed with a
460.Sq # ) ,
461and ordinary commands performed by
462.Xr make 1
463are displayed.
464.It 3
465In addition to the above, all commands performed by
466.Xr make 1
467are displayed, even if they would ordinarily have been hidden
468through use of the
469.Dq \&@
470prefix in the relevant makefile.
471.It 4
472In addition to the above, commands executed by
473.Xr make 1
474are traced through use of the
475.Xr sh 1
476.Dq Fl x
477flag.
478.El
479.DFLT
4802
481.
482.It Sy MKCATPAGES
483.YorN
484Indicates whether preformatted plaintext manual pages will be created
485during a build.
486.DFLTn
487.
488.It Sy MKCROSSGDB
489.YorN
490Create a cross-gdb as a host tool.
491.DFLTn
492.
493.It Sy MKDEBUG
494.YorN
495Indicates whether debug information should be generated for all userland
496binaries compiled.
497The result is collected as an additional
498.Sy debug.tgz
499and
500.Sy xdebug.tgz
501set and installed in
502.Pa /usr/libdata/debug .
503.DFLTn
504.
505.It Sy MKDEBUGLIB
506.YorN
507Indicates whether debug information (see
508.Sy MKDEBUG )
509should also be generated for all libraries build.
510.DFLTn
511.
512.It Sy MKDOC
513.YorN
514Indicates whether system documentation destined for
515.Sy DESTDIR Ns Pa /usr/share/doc
516will be installed during a build.
517.DFLTy
518.
519.It Sy MKEXTSRC
520.YorN
521Indicates whether extsrc is built from
522.Sy EXTSRCSRCDIR .
523.DFLTn
524.
525.It Sy MKHTML
526.YorN
527Indicates whether preformatted HTML manual pages will be built
528and installed
529.DFLTy
530.
531.It Sy MKHOSTOBJ
532.YorN
533If set to
534.Dq yes ,
535then for programs intended to be run on the compile host,
536the name, release, and architecture of the host operating system
537will be suffixed to the name of the object directory created by
538.Dq make obj .
539(This allows multiple host systems to compile NetBSD for a single target.)
540If set to
541.Dq no ,
542then programs built to be run on the compile host will use the same
543object directory names as programs built to be run on the target.
544.DFLTn
545.
546.It Sy MKINFO
547.YorN
548Indicates whether GNU Info files, used for the documentation for
549most of the compilation tools, will be created and installed during a
550build.
551.DFLTy
552.
553.It Sy MKKDEBUG
554.YorN
555Force generation of full-debug symbol versions of all kernels compiled.
556Alongside of the
557.Pa netbsd
558kernel file, an unstripped version
559.Pa netbsd.gdb
560is created.
561This is useful if a cross-gdb is built as well (see
562.Sy MKCROSSGDB ) .
563.DFLTn
564.
565.It Sy MKKMOD
566.YorN
567Indicates whether kernel modules are built and installed.
568.DFLTy
569.
570.It Sy MKLINT
571.YorN
572Indicates whether
573.Xr lint 1
574will be run against portions of the
575.Nx
576source code during the build, and whether lint libraries will be
577installed into
578.Sy DESTDIR Ns Pa /usr/libdata/lint .
579.DFLTy
580.
581.It Sy MKMAN
582.YorN
583Indicates whether manual pages will be installed during a build.
584.DFLTy
585.
586.It Sy MKNLS
587.YorN
588Indicates whether Native Language System locale zone files will be
589compiled and installed during a build.
590.DFLTy
591.
592.It Sy MKOBJ
593.YorN
594Indicates whether object directories will be created when running
595.Dq make obj .
596If set to
597.Dq no ,
598then all built files will be located inside the regular source tree.
599.DFLTy
600.Pp
601Note that setting
602.Sy MKOBJ
603to
604.Dq no
605is not recommended and may cause problems when updating the tree with
606.Xr cvs 1 .
607.
608.It Sy MKPIC
609.YorN
610Indicates whether shared objects and libraries will be created and
611installed during a build.
612If set to
613.Dq no ,
614the entire built system will be statically linked.
615.DFLT
616Platform dependent.
617As of this writing, all platforms except
618.Sy m68000
619default to
620.Dq yes .
621.
622.It Sy MKPICINSTALL
623.YorN
624Indicates whether the
625.Xr ar 1
626format libraries
627.Sy ( lib*_pic.a ) ,
628used to generate shared libraries, are installed during a build.
629.DFLTy
630.
631.It Sy MKPROFILE
632.YorN
633Indicates whether profiled libraries
634.Sy ( lib*_p.a )
635will be built and installed during a build.
636.DFLT
637.Dq yes ;
638however, some platforms turn off
639.Sy MKPROFILE
640by default at times due to toolchain problems with profiled code.
641.
642.It Sy MKREPRO
643.YorN
644Create reproducible builds.
645This enables different switches to make two builds from the same
646source tree result in the same build results.
647.DFLTn
648This may be set to
649.Dq yes
650by giving
651.Sy build.sh
652the
653.Fl P
654option.
655.
656.It Sy MKREPRO_TIMESTAMP
657Unix timestamp.
658When
659.Sy MKREPRO
660is set, the timestamp of all files in the sets will be set
661to this value.
662.DFLTu
663This may be set automatically to the latest source tree timestamp
664using
665.Xr cvslatest 1
666by giving
667.Sy build.sh
668the
669.Fl P
670option.
671.
672.It Sy MKSHARE
673.YorN
674Indicates whether files destined to reside in
675.Sy DESTDIR Ns Pa /usr/share
676will be built and installed during a build.
677If set to
678.Dq no ,
679then all of
680.Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
681and
682.Sy MKNLS
683will be set to
684.Dq no
685unconditionally.
686.DFLTy
687.
688.It Sy MKSTRIPIDENT
689.YorN
690Indicates whether RCS IDs, for use with
691.Xr ident 1 ,
692should be stripped from program binaries and shared libraries.
693.DFLTn
694.
695.It Sy MKSTRIPSYM
696.YorN
697Indicates whether all local symbols should be stripped from shared libraries.
698If
699.Dq yes ,
700strip all local symbols from shared libraries;
701the affect is equivalent to the
702.Fl x
703option of
704.Xr  ld 1 .
705If
706.Dq no ,
707strip only temporary local symbols; the affect is equivalent
708to the
709.Fl X
710option of
711.Xr ld 1 .
712Keeping non-temporary local symbols
713such as static function names is useful on using DTrace for
714userland libraries and getting a backtrace from a rump kernel
715loading shared libraries.
716.DFLTy
717.
718.It Sy MKUNPRIVED
719.YorN
720Indicates whether an unprivileged install will occur.
721The user, group, permissions, and file flags, will not be set on
722the installed items; instead the information will be appended to
723a file called
724.Pa METALOG
725in
726.Sy DESTDIR .
727The contents of
728.Pa METALOG
729are used during the generation of the distribution tar files to ensure
730that the appropriate file ownership is stored.
731.DFLTn
732.
733.It Sy MKUPDATE
734.YorN
735Indicates whether all install operations intended to write to
736.Sy DESTDIR
737will compare file timestamps before installing, and skip the install
738phase if the destination files are up-to-date.
739This also has implications on full builds (see next subsection).
740.DFLTn
741.
742.It Sy MKX11
743.YorN
744Indicates whether X11 is built from
745.Sy X11SRCDIR .
746.DFLTn
747.
748.It Sy TOOLDIR
749Directory to hold the host tools, once built.
750If specified, must be an absolute path.
751This directory should be unique to a given host system and
752.Nx
753source tree.
754(However, multiple targets may share the same
755.Sy TOOLDIR ;
756the target-dependent files have unique names.)  If unset, a default based
757on the
758.Xr uname 1
759information of the host platform will be created in the
760.Sy .OBJDIR
761of
762.Pa src .
763.DFLTu
764.
765.It Sy USETOOLS
766Indicates whether the tools specified by
767.Sy TOOLDIR
768should be used as part of a build in progress.
769Must be set to
770.Dq yes
771if cross-compiling.
772.Bl -tag -width "never"
773.It Sy yes
774Use the tools from
775.Sy TOOLDIR .
776.It Sy no
777Do not use the tools from
778.Sy TOOLDIR ,
779but refuse to build native compilation tool components that are
780version-specific for that tool.
781.It Sy never
782Do not use the tools from
783.Sy TOOLDIR ,
784even when building native tool components.
785This is similar to the traditional
786.Nx
787build method, but does
788.Em not
789verify that the compilation tools in use are up-to-date enough in order
790to build the tree successfully.
791This may cause build or runtime problems when building the whole
792.Nx
793source tree.
794.El
795.DFLT
796.Dq yes ,
797unless
798.Sy TOOLCHAIN_MISSING
799is set to
800.Dq yes .
801.Pp
802.Sy USETOOLS
803is also set to
804.Dq no
805when using
806.Aq bsd.*.mk
807outside the
808.Nx
809source tree.
810.
811.It Sy X11SRCDIR
812Directory containing the modular Xorg source.
813If specified, must be an absolute path.
814The main modular Xorg source is found in
815.Sy X11SRCDIR Ns Pa /external/mit .
816.DFLT
817.Sy NETBSDRCDIR Ns Pa /../xsrc ,
818if that exists; otherwise
819.Pa /usr/xsrc .
820.
821.El
822.
823.Ss \*qmake\*q variables for full builds
824These variables only affect the top level
825.Dq Makefile
826and do not affect manually building subtrees of the
827.Nx
828source code.
829.
830.Bl -tag -width "INSTALLWORLDDIR"
831.
832.It Sy INSTALLWORLDDIR
833Location for the
834.Dq make installworld
835target to install to.
836If specified, must be an absolute path.
837.DFLT
838.Dq /
839.
840.It Sy MKOBJDIRS
841.YorN
842Indicates whether object directories will be created automatically
843(via a
844.Dq make obj
845pass) at the start of a build.
846.DFLTn
847.Pp
848If using
849.Sy build.sh ,
850the default is
851.Dq yes .
852This may be set back to
853.Dq no
854by giving
855.Sy build.sh
856the
857.Fl o
858option.
859.
860.It Sy MKUPDATE
861.YorN
862If set, then in addition to the effects described for
863.Sy MKUPDATE=yes
864above, this implies the effects of
865.Sy NOCLEANDIR
866(i.e.,
867.Dq make cleandir
868is avoided).
869.DFLTn
870.Pp
871If using
872.Sy build.sh ,
873this may be set by giving the
874.Fl u
875option.
876.
877.It Sy NBUILDJOBS
878Now obsolete.
879Use the
880.Xr make 1
881option
882.Fl j ,
883instead.
884See below.
885.DFLTu
886.
887.It Sy NOCLEANDIR
888If set, avoids the
889.Dq make cleandir
890phase of a full build.
891This has the effect of allowing only changed
892files in a source tree to be recompiled.
893This can speed up builds when updating only a few files in the tree.
894.DFLTu
895.Pp
896See also
897.Sy MKUPDATE .
898.
899.It Sy NODISTRIBDIRS
900If set, avoids the
901.Dq make distrib-dirs
902phase of a full build.
903This skips running
904.Xr mtree 8
905on
906.Sy DESTDIR ,
907useful on systems where building as an unprivileged user, or where it is
908known that the system-wide mtree files have not changed.
909.DFLTu
910.
911.It Sy NOINCLUDES
912If set, avoids the
913.Dq make includes
914phase of a full build.
915This has the effect of preventing
916.Xr make 1
917from thinking that some programs are out-of-date simply because the
918system include files have changed.
919However, this option should not be used when updating the entire
920.Nx
921source tree arbitrarily; it is suggested to use
922.Sy MKUPDATE=yes
923instead in that case.
924.DFLTu
925.
926.It Sy RELEASEDIR
927If set, specifies the directory to which a
928.Xr release 7
929layout will be written at the end of a
930.Dq make release .
931If specified, must be an absolute path.
932.DFLTu
933.Pp
934.Em Note :
935.Sy build.sh
936will provide a default of
937.Pa releasedir
938(in the top-level
939.Sy .OBJDIR )
940unless run in
941.Sq expert
942mode.
943.
944.El
945.
946.Sh BUILDING
947.
948.Ss \*qmake\*q command line options
949This is not a summary of all the options available to
950.Xr make 1 ;
951only the options used most frequently with
952.Nx
953builds are listed here.
954.
955.Bl -tag -width "var=value"
956.
957.It Fl j Ar njob
958Run up to
959.Ar njob
960.Xr make 1
961subjobs in parallel.
962Makefiles should use .WAIT or have explicit dependencies
963as necessary to enforce build ordering.
964.
965.It Fl m Ar dir
966Specify the default directory for searching for system Makefile
967segments, mainly the
968.Aq bsd.*.mk
969files.
970When building any full
971.Nx
972source tree, this should be set to the
973.Dq Pa share/mk
974directory in the source tree.
975This is set automatically when building from the top level, or when using
976.Sy build.sh .
977.
978.It Fl n
979Display the commands that would have been executed, but do not
980actually execute them.
981This will still cause recursion to take place.
982.
983.It Fl V Ar var
984Print
985.Xr make 1 Ns 's
986idea of the value of
987.Ar var .
988Does not build any targets.
989.
990.It Em var=value
991Set the variable
992.Em var
993to
994.Em value ,
995overriding any setting specified by the process environment, the
996.Sy MAKECONF
997configuration file, or the system Makefile segments.
998.
999.El
1000.
1001.Ss \*qmake\*q targets
1002.
1003These default targets may be built by running
1004.Xr make 1
1005in any subtree of the
1006.Nx
1007source code.
1008It is recommended that none of these be used from the top
1009level Makefile; as a specific exception,
1010.Dq make obj
1011and
1012.Dq make cleandir
1013are useful in that context.
1014.
1015.Bl -tag -width "dependall"
1016.
1017.It Sy all
1018Build programs, libraries, and preformatted documentation.
1019.
1020.It Sy clean
1021Remove program and library object code files.
1022.
1023.It Sy cleandir
1024Same as
1025.Sy clean ,
1026but also remove preformatted documentation, dependency files generated
1027by
1028.Dq make depend ,
1029and any other files known to be created at build time.
1030.
1031.It Sy depend
1032Create dependency files
1033.Sy ( .depend )
1034containing more detailed information about the dependencies of source
1035code on header files.
1036Allows programs to be recompiled automatically when a dependency changes.
1037.
1038.It Sy dependall
1039Does a
1040.Dq make depend
1041immediately followed by a
1042.Dq make all .
1043This improves cache locality of the build since both passes read the source
1044files in their entirety.
1045.
1046.It Sy distclean
1047Synonym for
1048.Sy cleandir .
1049.
1050.It Sy includes
1051Build and install system header files.
1052Typically needed before any system libraries or programs can be built.
1053.
1054.It Sy install
1055Install programs, libraries, and documentation into
1056.Sy DESTDIR .
1057Few files will be installed to
1058.Sy DESTDIR Ns Pa /dev ,
1059.Sy DESTDIR Ns Pa /etc ,
1060.Sy DESTDIR Ns Pa /root
1061or
1062.Sy DESTDIR Ns Pa /var
1063in order to prevent user supplied configuration data from being overwritten.
1064.It Sy lint
1065Run
1066.Xr lint 1
1067against the C source code, where appropriate, and generate
1068system-installed lint libraries.
1069.
1070.It Sy obj
1071Create object directories to be used for built files, instead of
1072building directly in the source tree.
1073.
1074.It Sy tags
1075Create
1076.Xr ctags 1
1077searchable function lists usable by the
1078.Xr ex 1
1079and
1080.Xr vi 1
1081text editors.
1082.
1083.El
1084.
1085.Ss \*qmake\*q targets for the top level
1086.
1087Additional
1088.Xr make 1
1089targets are usable specifically from the top source level to facilitate
1090building the entire
1091.Nx
1092source tree.
1093.
1094.Bl -tag -width "distribution"
1095.
1096.It Sy build
1097Build the entire
1098.Nx
1099system (except the kernel).
1100This orders portions of the source tree such that prerequisites
1101will be built in the proper order.
1102.
1103.It Sy distribution
1104Do a
1105.Dq make build ,
1106and then install a full distribution (which does not include a kernel) into
1107.Sy DESTDIR ,
1108including files in
1109.Sy DESTDIR Ns Pa /dev ,
1110.Sy DESTDIR Ns Pa /etc ,
1111.Sy DESTDIR Ns Pa /root
1112and
1113.Sy DESTDIR Ns Pa /var .
1114.
1115.It Sy buildworld
1116As per
1117.Dq make distribution ,
1118except that it ensures that
1119.Sy DESTDIR
1120is not the root directory.
1121.
1122.It Sy installworld
1123Install the distribution from
1124.Sy DESTDIR
1125to
1126.Sy INSTALLWORLDDIR ,
1127which defaults to the root directory.
1128Ensures that
1129.Sy INSTALLWORLDDIR
1130is not the root directory if cross compiling.
1131.Pp
1132The
1133.Sy INSTALLSETS
1134environment variable may be set to a space-separated list of
1135distribution sets to be installed.
1136By default, all sets except
1137.Dq etc
1138and
1139.Dq xetc
1140are installed, so most files in
1141.Sy INSTALLWORLDDIR Ns Pa /etc
1142will not be installed or modified.
1143.Pp
1144.Em Note :
1145Before performing this operation with
1146.Sy INSTALLWORLDDIR Ns = Ns Pa / ,
1147it is highly recommended that you upgrade your kernel and reboot.
1148After performing this operation,
1149it is recommended that you use
1150.Xr etcupdate 8
1151to update files in
1152.Sy INSTALLWORLDDIR Ns Pa /etc ,
1153and
1154.Xr postinstall 8
1155to check for or fix inconsistencies.
1156.It Sy sets
1157Create distribution sets from
1158.Sy DESTDIR
1159into
1160.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets .
1161Should be run after
1162.Dq make distribution ,
1163as
1164.Dq make build
1165alone does not install all of the required files.
1166.
1167.It Sy sourcesets
1168Create source sets of the source tree into
1169.Sy RELEASEDIR Ns Pa /source/sets .
1170.
1171.It Sy syspkgs
1172Create syspkgs from
1173.Sy DESTDIR
1174into
1175.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs .
1176Should be run after
1177.Dq make distribution ,
1178as
1179.Dq make build
1180alone does not install all of the required files.
1181.
1182.It Sy release
1183Do a
1184.Dq make distribution ,
1185build kernels, distribution media, and install sets
1186(this as per
1187.Dq make sets ) ,
1188and
1189then package the system into a standard release layout as described by
1190.Xr release 7 .
1191This requires that
1192.Sy RELEASEDIR
1193be set (see above).
1194.
1195.It Sy iso-image
1196Create a
1197.Nx
1198installation CD-ROM image in the
1199.Sy RELEASEDIR Ns Pa /images
1200directory.
1201The CD-ROM file system will have a layout as described in
1202.Xr release 7 .
1203.Pp
1204For most machine types, the CD-ROM will be bootable, and will automatically
1205run the
1206.Xr sysinst 8
1207menu-based installation program, which can be used to install or upgrade a
1208.Nx
1209system.
1210Bootable CD-ROMs also contain tools that may be useful in
1211repairing a damaged
1212.Nx
1213installation.
1214.Pp
1215Before
1216.Dq make iso-image
1217is attempted, RELEASEDIR must be populated by
1218.Dq make release
1219or equivalent.
1220.Pp
1221Note that other, smaller, CD-ROM images may be created in the
1222.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1223directory by
1224.Dq "make release" .
1225These smaller images usually contain the same tools as the larger images in
1226.Sy RELEASEDIR Ns Pa /images ,
1227but do not contain additional content such as the distribution sets.
1228.Pp
1229Note that the mac68k port still uses an older method of creating
1230CD-ROM images.
1231This requires the
1232.Xr mkisofs 1
1233utility, which is not part of
1234.Nx ,
1235but which can be installed from
1236.Pa pkgsrc/sysutils/cdrtools .
1237.
1238.It Sy iso-image-source
1239Create a
1240.Nx
1241installation CD-ROM image in the
1242.Sy RELEASEDIR Ns Pa /images
1243directory.
1244The CD-ROM file system will have a layout as described in
1245.Xr release 7 .
1246It will have top level directories for the machine type and source.
1247.Pp
1248For most machine types, the CD-ROM will be bootable, and will automatically
1249run the
1250.Xr sysinst 8
1251menu-based installation program, which can be used to install or upgrade a
1252.Nx
1253system.
1254Bootable CD-ROMs also contain tools that may be useful in
1255repairing a damaged
1256.Nx
1257installation.
1258.Pp
1259Before
1260.Dq make iso-image-source
1261is attempted, RELEASEDIR must be populated by
1262.Dq make sourcesets release
1263or equivalent.
1264.Pp
1265Note that other, smaller, CD-ROM images may be created in the
1266.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1267directory by
1268.Dq make release .
1269These smaller images usually contain the same tools as the larger images in
1270.Sy RELEASEDIR Ns Pa /images ,
1271but do not contain additional content such as the distribution sets.
1272.Pp
1273Note that the mac68k port still uses an older method of creating
1274CD-ROM images.
1275This requires the
1276.Xr mkisofs 1
1277utility, which is not part of
1278.Nx ,
1279but which can be installed from
1280.Pa pkgsrc/sysutils/cdrtools .
1281.
1282.It Sy install-image
1283Create a bootable
1284.Nx
1285installation disk image in the
1286.Sy RELEASEDIR Ns Pa /images
1287directory.
1288The installation disk image is suitable for copying to
1289bootable USB flash memory sticks, etc., for machines which
1290are able to boot from such devices.
1291The file system in the bootable disk image will have a layout
1292as described in
1293.Xr release 7 .
1294.Pp
1295The installation image is bootable, and will automatically
1296run the
1297.Xr sysinst 8
1298menu-based installation program, which can be used to install or upgrade a
1299.Nx
1300system.
1301The image also contains tools that may be
1302useful in repairing a damaged
1303.Nx
1304installation.
1305.Pp
1306Before
1307.Dq make install-image
1308is attempted,
1309.Sy RELEASEDIR
1310must be populated by
1311.Dq make release
1312or equivalent.
1313The build must have been performed with
1314.Sy MKUNPRIVED=yes
1315because
1316.Dq make install-image
1317relies on information in
1318.Sy DESTDIR Ns Pa /METALOG .
1319.
1320.It Sy live-image
1321Create
1322.Nx
1323live images in the
1324.Sy RELEASEDIR/images
1325directory.
1326The live image contains all necessary files
1327to boot
1328.Nx
1329up to multi-user mode, including all files
1330which should be extracted during installation,
1331.Nx
1332disklabel, bootloaders, etc.
1333.Pp
1334The live image is suitable for use as a disk image in
1335virtual machine environments such as QEMU,
1336and also useful to boot
1337.Nx
1338from a USB flash memory stick
1339on a real machine, without the need for installation.
1340.Pp
1341Before
1342.Dq make live-image
1343is attempted, RELEASEDIR must be populated by
1344.Dq make release
1345or equivalent.
1346The build must have been performed with
1347.Sy MKUNPRIVED=yes
1348because
1349.Dq make install-image
1350relies on information in
1351.Sy DESTDIR Ns Pa /METALOG .
1352.
1353.It Sy regression-tests
1354Can only be run after building the regression tests in the directory
1355.Dq regress .
1356Runs those compiled regression tests on the local host.
1357Note that most tests are now managed instead using
1358.Xr atf 7 ;
1359this target should probably run those as well but currently does not.
1360.
1361.El
1362.
1363.Ss The \*qbuild.sh\*q script
1364.
1365This script file is a shell script designed to build the
1366entire
1367.Nx
1368system on any host with a suitable modern shell and some common
1369utilities.
1370The required shell features are described under the
1371.Sy HOST_SH
1372variable.
1373.Pp
1374If a host system's default shell does support the required
1375features, then we suggest that you explicitly specify
1376a suitable shell using a command like
1377.Bd -unfilled -offset indent
1378.Li /path/to/suitable/shell build.sh Op Ar options
1379.Ed
1380.Pp
1381The above command will usually enable
1382.Nm build.sh
1383to automatically set
1384.Sy HOST_SH Ns Cm = Ns Pa /path/to/suitable/shell ,
1385but if that fails, then the following set of commands may be used instead:
1386.Bd -unfilled -offset indent
1387.Li HOST_SH= Ns Va /path/to/suitable/shell
1388.Li export HOST_SH
1389.Li ${HOST_SH} build.sh Op Ar options
1390.Ed
1391.Pp
1392If
1393.Sy build.sh
1394detects that it is being executed under an unsuitable shell, it attempts
1395to exec a suitable shell instead, or prints an error message.
1396If
1397.Sy HOST_SH
1398is not set explicitly, then
1399.Nm build.sh
1400sets a default using heuristics dependent on the host platform,
1401or from the shell under which
1402.Nm build.sh
1403is executed (if that can be determined),
1404or using the first copy of
1405.Pa sh
1406found in
1407.Sy PATH .
1408.Pp
1409All cross-compile builds, and most native builds, of the entire system
1410should make use of
1411.Sy build.sh
1412rather than just running
1413.Dq make .
1414This way, the
1415.Xr make 1
1416program will be bootstrapped properly, in case the host system has an
1417older or incompatible
1418.Dq make
1419program.
1420.Pp
1421When compiling the entire system via
1422.Sy build.sh ,
1423many
1424.Xr make 1
1425variables are set for you in order to help encapsulate the build
1426process.
1427In the list of options below, variables that are automatically set by
1428.Sy build.sh
1429are noted where applicable.
1430.
1431.Pp
1432The following operations are supported by
1433.Sy build.sh :
1434.
1435.Bl -tag -width "distribution"
1436.
1437.It Sy build
1438Build the system as per
1439.Dq make build .
1440Before the main part of the build commences, this command runs the
1441.Sy obj
1442operation (unless the
1443.Fl o
1444option is given),
1445.Dq make cleandir
1446(unless the
1447.Fl u
1448option is given),
1449and the
1450.Sy tools
1451operation.
1452.
1453.It Sy distribution
1454Build a full distribution as per
1455.Dq make distribution .
1456This command first runs the
1457.Sy build
1458operation.
1459.
1460.It Sy release
1461Build a full release as per
1462.Dq make release .
1463This command first runs the
1464.Sy distribution
1465operation.
1466.
1467.It Sy makewrapper
1468Create the
1469.Sy \*[toolprefix]make-MACHINE
1470wrapper.
1471This operation is automatically performed for any of the other
1472operations.
1473.
1474.It Sy cleandir
1475Perform
1476.Dq make cleandir .
1477.
1478.It Sy obj
1479Perform
1480.Dq make obj .
1481.
1482.It Sy tools
1483Build and install the host tools from
1484.Pa src/tools .
1485This command will first run
1486.Dq make obj
1487and
1488.Dq make cleandir
1489in the
1490.Pa tools
1491subdirectory unless the
1492.Fl o
1493or
1494.Fl u
1495options (respectively) are given.
1496.
1497.It Sy install Ns = Ns Ar idir
1498Install the contents of
1499.Sy DESTDIR
1500to
1501.Ar idir ,
1502using
1503.Dq make installworld .
1504Note that files that are part of the
1505.Dq etc
1506or
1507.Dq xetc
1508sets will not be installed, unless overridden by
1509the INSTALLSETS environment variable.
1510.
1511.It Sy kernel Ns = Ns Ar kconf
1512Build a new kernel.
1513The
1514.Ar kconf
1515argument is the name of a configuration file suitable
1516for use by
1517.Xr config 1 .
1518If
1519.Ar kconf
1520does not contain any
1521.Sq /
1522characters, the configuration file is expected to be found in the
1523.Sy KERNCONFDIR
1524directory, which is typically
1525.Pa sys/arch/MACHINE/conf .
1526The new kernel will be built in a subdirectory of
1527.Sy KERNOBJDIR ,
1528which is typically
1529.Pa sys/arch/MACHINE/compile
1530or an associated object directory.
1531.Pp
1532This command does
1533.Em not
1534imply the
1535.Sy tools
1536command; run the
1537.Sy tools
1538command first unless it is
1539.Em certain
1540that the tools already exist and are up to date.
1541.Pp
1542This command will run
1543.Dq make cleandir
1544on the kernel in question first unless the
1545.Fl u
1546option is given.
1547.
1548.It Sy kernel.gdb Ns = Ns Ar kconf
1549Build a new kernel with debug information.
1550Similar to the above
1551.Sy kernel Ns = Ns Ar kconf
1552operation, but creates a
1553.Pa netbsd.gdb
1554file alongside of the kernel
1555.Pa netbsd ,
1556which contains a full symbol table and can be used for debugging
1557(for example with a cross-gdb built by
1558.Sy MKCROSSGDB ) .
1559.It Sy kernels
1560This command will build all kernels defined in port specific release build
1561procedure.
1562.Pp
1563This command internally calls the
1564.Sy kernel Ns = Ns Ar kconf
1565operation for each found kernel configuration file.
1566.It Sy modules
1567This command will build kernel modules and install them into
1568.Sy DESTDIR .
1569.
1570.It Sy releasekernel Ns = Ns Ar kconf
1571Install a
1572.Xr gzip 1 Ns ed
1573copy of the kernel previously built by
1574.Sy kernel Ns = Ns Ar kconf
1575into
1576.Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel ,
1577usually as
1578.Pa netbsd- Ns Ar kconf Ns Pa .gz ,
1579although the
1580.Dq Pa netbsd
1581prefix is determined from the
1582.Dq Sy config
1583directives in
1584.Ar kconf .
1585.
1586.It Sy sets
1587Perform
1588.Dq make sets .
1589.
1590.It Sy sourcesets
1591Perform
1592.Dq make sourcesets .
1593.
1594.It Sy syspkgs
1595Perform
1596.Dq make syspkgs .
1597.
1598.It Sy iso-image
1599Perform
1600.Dq make iso-image .
1601.
1602.It Sy iso-image-source
1603Perform
1604.Dq make iso-image-source .
1605.
1606.It Sy install-image
1607Perform
1608.Dq make install-image .
1609.
1610.It Sy live-image
1611Perform
1612.Dq make live-image .
1613.
1614.It Sy list-arch
1615Prints a list of valid
1616.Sy MACHINE
1617and
1618.Sy MACHINE_ARCH
1619settings, the default
1620.Sy MACHINE_ARCH
1621for each
1622.Sy MACHINE ,
1623and aliases for
1624.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
1625pairs, and then exits.
1626The
1627.Fl m
1628or
1629.Fl a
1630options (or both) may be used to specify glob patterns
1631that will be used to narrow the list of results;
1632for example,
1633.Dq Li build.sh -m 'evb*' -a '*arm*' list-arch
1634will list all known
1635.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
1636values in which either
1637.Sy MACHINE
1638or
1639.Sy ALIAS
1640matches the pattern
1641.Ql evb* ,
1642and
1643.Sy MACHINE_ARCH
1644matches the pattern
1645.Ql *arm* .
1646.
1647.El
1648.
1649.Pp
1650The following command line options alter the behaviour of the
1651.Sy build.sh
1652operations described above:
1653.
1654.Bl -tag -width "-T tools"
1655.
1656.It Fl a Ar arch
1657Set the value of
1658.Sy MACHINE_ARCH
1659to
1660.Ar arch .
1661See the
1662.Fl m
1663option for more information.
1664.
1665.It Fl B Ar buildid
1666Set the value of
1667.Sy BUILDID
1668to
1669.Ar buildid .
1670This will also append the build identifier to the name of the
1671.Dq make
1672wrapper script so that the resulting name is of the form
1673.Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1674.
1675.It Fl C Ar cdextras
1676Append
1677.Ar cdextras
1678to the
1679.Sy CDEXTRA
1680variable,
1681which is a space-separated list of files or directories that will be
1682added to the CD-ROM image that may be create by the
1683.Dq iso-image
1684or
1685.Dq iso-image-source
1686operations.
1687Files will be added to the root of the CD-ROM image, whereas directories
1688will be copied recursively.
1689If relative paths are specified, they will be converted to
1690absolute paths before being used.
1691Multiple paths may be specified via multiple
1692.Fl C
1693options, or via a single option whose argument contains multiple
1694space-separated paths.
1695.
1696.It Fl D Ar dest
1697Set the value of
1698.Sy DESTDIR
1699to
1700.Ar dest .
1701If a relative path is specified, it will be converted to an
1702absolute path before being used.
1703.
1704.It Fl E
1705Set
1706.Sq expert
1707mode.
1708This overrides various sanity checks, and allows:
1709.Sy DESTDIR
1710does not have to be set to a non-root path for builds,
1711and
1712.Sy MKUNPRIVED=yes
1713does not have to be set when building as a non-root user.
1714.Pp
1715.Em Note :
1716It is highly recommended that you know what you are doing when
1717you use this option.
1718.
1719.It Fl h
1720Print a help message.
1721.
1722.It Fl j Ar njob
1723Run up to
1724.Ar njob
1725.Xr make 1
1726subjobs in parallel;
1727passed through to
1728.Xr make 1 .
1729If you see failures for reasons other than running out of memory
1730while using
1731.Sy build.sh
1732with
1733.Fl j ,
1734please save complete build logs
1735so the failures can be analyzed.
1736.Pp
1737To achieve the fastest builds,
1738.Fl j
1739values between (1 + the number of CPUs) and (2 * the number of CPUs)
1740are recommended.
1741Use lower values on machines with limited memory or I/O bandwidth.
1742.
1743.It Fl M Ar obj
1744Set
1745.Sy MAKEOBJDIRPREFIX
1746to
1747.Ar obj .
1748Unsets
1749.Sy MAKEOBJDIR .
1750See
1751.Dq Fl O Ar obj
1752for more information.
1753.Pp
1754For instance, if the source directory is
1755.Pa /usr/src ,
1756a setting of
1757.Dq Fl M Pa /usr/obj
1758will place build-time files under
1759.Pa /usr/obj/usr/src/bin ,
1760.Pa /usr/obj/usr/src/lib ,
1761.Pa /usr/obj/usr/src/usr.bin ,
1762and so forth.
1763.Pp
1764If a relative path is specified, it will be converted to an
1765absolute path before being used.
1766.Sy build.sh
1767imposes the restriction that the argument to the
1768.Fl M
1769option must not begin with a
1770.Dq \&$
1771(dollar sign)
1772character; otherwise it would be too difficult
1773to determine whether the value is an absolute or a relative path.
1774If the directory does not already exist,
1775.Sy build.sh
1776will create it.
1777.
1778.It Fl m Ar mach
1779Set the value of
1780.Sy MACHINE
1781to
1782.Ar mach ,
1783unless the
1784.Ar mach
1785argument is an alias that refers to a
1786.Sy MACHINE Ns No / Ns Sy MACHINE_ARCH
1787pair, in which case both
1788.Sy MACHINE
1789and
1790.Sy MACHINE_ARCH
1791are set from the alias.
1792Such aliases are interpreted entirely by
1793.Sy build.sh ;
1794they are not used by any other part of the build system.
1795The
1796.Sy MACHINE_ARCH
1797setting implied by
1798.Ar mach
1799will override any value of
1800.Sy MACHINE_ARCH
1801in the process environment, but will not override a value set by the
1802.Fl a
1803option.
1804All cross builds require
1805.Fl m ,
1806but if unset on a NetBSD host, the host's value of MACHINE will be
1807detected and used automatically.
1808.Pp
1809See the
1810.Cm list-arch
1811operation for a way to get a list of valid
1812.Sy MACHINE
1813and
1814.Sy MACHINE_ARCH
1815settings.
1816.
1817.It Fl N Ar noiselevel
1818Set the
1819.Dq noisyness
1820level of the build, by setting
1821.Sy MAKEVERBOSE
1822to
1823.Ar noiselevel .
1824.
1825.It Fl n
1826Show the commands that would be executed by
1827.Sy build.sh ,
1828but do not make any changes.
1829This is similar in concept to
1830.Dq make -n .
1831.
1832.It Fl O Ar obj
1833Create an appropriate transform macro for
1834.Sy MAKEOBJDIR
1835that will place the built object files under
1836.Ar obj .
1837Unsets
1838.Sy MAKEOBJDIRPREFIX .
1839.Pp
1840For instance, a setting of
1841.Dq Fl O Pa /usr/obj
1842will place build-time files under
1843.Pa /usr/obj/bin ,
1844.Pa /usr/obj/lib ,
1845.Pa /usr/obj/usr.bin ,
1846and so forth.
1847.Pp
1848If a relative path is specified, it will be converted to an
1849absolute path before being used.
1850.Sy build.sh
1851imposes the restriction that the argument to the
1852.Fl O
1853option must not contain a
1854.Dq \&$
1855(dollar sign)
1856character.
1857If the directory does not already exist,
1858.Sy build.sh
1859will create it.
1860.Pp
1861In normal use, exactly one of the
1862.Fl M
1863or
1864.Fl O
1865options should be specified.
1866If neither
1867.Fl M
1868nor
1869.Fl O
1870is specified, then a default object directory will be chosen
1871according to rules in
1872.Aq bsd.obj.mk .
1873Relying on this default is not recommended because
1874it is determined by complex rules that are influenced
1875by the values of several variables and
1876by the location of the source directory.
1877.Pp
1878Note that placing the
1879.Ar obj
1880directory location outside of the default source tree hierarchy makes
1881it easier to manually clear out old files in the event the
1882.Dq make cleandir
1883operation is unable to do so.
1884(See
1885.Sx CAVEATS
1886below.)
1887.Pp
1888Note also that use of one of
1889.Fl M
1890or
1891.Fl O
1892is the only means of building multiple machine architecture userlands
1893from the same source tree without cleaning between builds (in which
1894case, one would specify distinct
1895.Ar obj
1896locations for each).
1897.It Fl o
1898Set the value of
1899.Sy MKOBJDIRS
1900to
1901.Dq no .
1902Otherwise, it will be automatically set to
1903.Dq yes .
1904This default is opposite to the behaviour when not using
1905.Sy build.sh .
1906.
1907.It Fl R Ar rel
1908Set the value of
1909.Sy RELEASEDIR
1910to
1911.Ar rel .
1912If a relative path is specified, it will be converted to an
1913absolute path before being used.
1914.
1915.It Fl r
1916Remove the contents of
1917.Sy DESTDIR
1918and
1919.Sy TOOLDIR
1920before building (provides a clean starting point).
1921This will skip deleting
1922.Sy DESTDIR
1923if building on a native system to the root directory.
1924.
1925.It Fl S Ar seed
1926Change the value of
1927.Sy BUILDSEED
1928to
1929.Ar seed .
1930This should rarely be necessary.
1931.
1932.It Fl T Ar tools
1933Set the value of
1934.Sy TOOLDIR
1935to
1936.Ar tools .
1937If a relative path is specified, it will be converted to an
1938absolute path before being used.
1939If set, the bootstrap
1940.Dq make
1941will only be rebuilt if the source files for
1942.Xr make 1
1943have changed.
1944.
1945.It Fl U
1946Set
1947.Sy MKUNPRIVED=yes .
1948.
1949.It Fl u
1950Set
1951.Sy MKUPDATE=yes .
1952.
1953.It Xo
1954.Fl V
1955.Sm off
1956.Ar var
1957.Li =
1958.Op Ar value
1959.Sm on
1960.Xc
1961Set the environment variable
1962.Ar var
1963to an optional
1964.Ar value .
1965This is propagated to the
1966.Sy \*[toolprefix]make
1967wrapper.
1968.
1969.It Fl w Ar wrapper
1970Create the
1971.Sy \*[toolprefix]make
1972wrapper script (see below) in a custom location,
1973specified by
1974.Ar wrapper .
1975This allows, for instance, to place the wrapper in
1976.Sy PATH
1977automatically.
1978Note that
1979.Ar wrapper
1980is the full name of the file, not just a directory name.
1981If a relative path is specified, it will be converted to an
1982absolute path before being used.
1983.
1984.It Fl X Ar x11src
1985Set the value of
1986.Sy X11SRCDIR
1987to
1988.Ar x11src .
1989If a relative path is specified, it will be converted to an
1990absolute path before being used.
1991.
1992.It Fl x
1993Set
1994.Sy MKX11=yes .
1995.
1996.It Fl Y Ar extsrcdir
1997Set the value of
1998.Sy EXTSRCSRCDIR
1999to
2000.Ar extsrcdir .
2001If a relative path is specified, it will be converted to an
2002absolute path before being used.
2003.
2004.It Fl y
2005Set
2006.Sy MKEXTSRC=yes .
2007.
2008.It Fl Z Ar var
2009Unset ("zap") the environment variable
2010.Ar var .
2011This is propagated to the
2012.Sy \*[toolprefix]make
2013wrapper.
2014.
2015.El
2016.
2017.Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
2018.
2019If using the
2020.Sy build.sh
2021script to build
2022.Nx ,
2023a
2024.Sy \*[toolprefix]make-MACHINE
2025script will be created in
2026.Sy TOOLDIR Ns Pa /bin
2027upon the first build to assist in building subtrees on a cross-compile
2028host.
2029.Pp
2030.Sy \*[toolprefix]make-MACHINE
2031can be invoked in lieu of
2032.Xr make 1 ,
2033and will instead call the up-to-date version of
2034.Dq \*[toolprefix]make
2035installed into
2036.Sy TOOLDIR Ns Pa /bin
2037with several key variables pre-set, including
2038.Sy MACHINE , MACHINE_ARCH ,
2039and
2040.Sy TOOLDIR .
2041.Sy \*[toolprefix]make-MACHINE
2042will also set variables specified with
2043.Fl V ,
2044and unset variables specified with
2045.Fl Z .
2046.Pp
2047This script can be symlinked into a directory listed in
2048.Sy PATH ,
2049or called with an absolute path.
2050.
2051.Sh EXAMPLES
2052.
2053.Bl -enum
2054.
2055.It
2056.Li "% ./build.sh [options] tools kernel=GENERIC"
2057.Pp
2058Build a new toolchain, and use the new toolchain to
2059configure and build a new GENERIC kernel.
2060.
2061.It
2062.Li "% ./build.sh [options] -U distribution"
2063.Pp
2064Using unprivileged mode,
2065build a complete distribution to a
2066.Sy DESTDIR
2067directory that
2068.Sy build.sh
2069selects (and will display).
2070.
2071.It
2072.Li "# ./build.sh [options] -U install=/"
2073.Pp
2074As root, install to
2075.Pa /
2076the distribution that was built
2077by example 2.
2078Even though this is run as root,
2079.Fl U
2080is required so that the permissions stored in
2081.Sy DESTDIR Ns Pa /METALOG
2082are correctly applied to the files as they're copied to
2083.Pa / .
2084.
2085.It
2086.Li "% ./build.sh [options] -U -u release"
2087.Pp
2088Using unprivileged mode,
2089build a complete release to
2090.Sy DESTDIR
2091and
2092.Sy RELEASEDIR
2093directories that
2094.Sy build.sh
2095selects (and will display).
2096.Sy MKUPDATE=yes
2097.Pq Fl u
2098is set to prevent the
2099.Dq make cleandir ,
2100so that if this is run after example 2, it doesn't need to redo that
2101portion of the release build.
2102.El
2103.
2104.Sh OBSOLETE VARIABLES
2105.
2106.Bl -tag -width "NBUILDJOBS"
2107.
2108.It Sy NBUILDJOBS
2109Use the
2110.Xr make 1
2111option
2112.Fl j
2113instead.
2114.
2115.It Sy USE_NEW_TOOLCHAIN
2116The new toolchain is now the default.
2117To disable, use
2118.Sy TOOLCHAIN_MISSING=yes .
2119.El
2120.Sh SEE ALSO
2121.Xr make 1 ,
2122.Xr hier 7 ,
2123.Xr release 7 ,
2124.Xr etcupdate 8 ,
2125.Xr postinstall 8 ,
2126.Xr sysinst 8 ,
2127.Pa pkgsrc/sysutils/cdrtools
2128.
2129.Sh HISTORY
2130.
2131The
2132.Nm build.sh
2133based build scheme was introduced for
2134.Nx 1.6
2135as
2136.Sy USE_NEW_TOOLCHAIN ,
2137and re-worked to
2138.Sy TOOLCHAIN_MISSING
2139after that.
2140.
2141.Sh CAVEATS
2142.
2143After significant updates to third-party components in the source
2144tree, the
2145.Dq make cleandir
2146operation may be insufficient to clean out old files in object
2147directories.
2148Instead, one may have to manually remove the files.
2149Consult the
2150.Pa UPDATING
2151file for notices concerning this.
2152