| blob | 6a31c6fdea930218fc2e291bd7c5cc9a92e59697 |
1 .\" $NetBSD: BUILDING.mdoc,v 1.79 2009/10/02 07:43:01 cegger Exp $
2 .\"
3 .\" Copyright (c) 2001-2008 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 build-docs" to generate the
31 .\" proper plaintext versions, and check in all BUILDING.* files!
32 .\"
33 .\" Toolchain prefix for commands
34 .ds toolprefix nb
35 .
36 .Dd May 1, 2009
37 .Dt BUILDING 8
38 .Os NetBSD
39 .
40 .Sh NAME
41 .
42 .Nm BUILDING
43 .Nd Procedure for building
44 .Nx
45 from source code.
46 .
47 .Sh REQUIREMENTS
48 .
49 .Nx
50 is designed to be buildable on most POSIX-compliant host systems.
51 The basic build procedure is the same whether compiling
52 .Em natively
53 (on the same
54 .Nx
55 architecture) or
56 .Em cross compiling
57 (on another architecture or OS).
58 .Pp
59 This source tree contains a special subtree,
60 .Dq tools ,
61 which uses the host system to create a build toolchain for the target
62 architecture.
63 The host system must have at least C and C++
64 compilers in order to create the toolchain
65 .Nm ( make
66 is not required); all other tools are created as part of the
67 .Nx
68 build process.
69 (See the environment variables section below if you need
70 to 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 Sy doc/BUILDING.mdoc
78 This document (in -mdoc troff format; the original copy).
79 .It Sy BUILDING
80 This document (in plaintext).
81 .It Sy tools/compat/README
82 Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
83 .It Sy Makefile
84 The main Makefile for
85 .Nx ;
86 should only be run for native builds with an appropriately up-to-date
87 version of
88 .Nx
89 .Xr make 1 .
90 (For building from out-of-date systems or on a non-native host, see the
91 .Nm build.sh
92 shell script.)
93 .It Sy UPDATING
94 Special notes for updating from an earlier revision of
95 .Nx .
96 It is important to read this file before every build of an updated
97 source tree.
98 .It Sy build.sh
99 Bourne-compatible shell script used for building the host build tools
100 and the
101 .Nx
102 system from scratch.
103 Can be used for both native and cross builds, and should be used instead of
104 .Xr make 1
105 for any source tree that is updated and recompiled regularly.
106 .It Sy crypto/dist/ , dist/ , gnu/dist/
107 Sources imported verbatim from third parties, without mangling the
108 existing build structure.
109 Other source trees in
110 .Sy bin
111 through
112 .Sy usr.sbin
113 use the
114 .Nx
115 .Xr make 1
116 .Dq reachover
117 Makefile semantics when building these programs for a native host.
118 .It Sy distrib/ , etc/
119 Sources for items used when making a full release snapshot, such as
120 files installed in
121 .Sy DESTDIR Ns Pa /etc
122 on the destination system, boot media, and release notes.
123 .It Sy tests/ , regress/
124 Regression test harness.
125 Can be cross-compiled, but only run natively.
126 .Pa tests/
127 uses the
128 .Xr atf 7
129 test framework;
130 .Pa regress/
131 contains older tests that have not yet been migrated to
132 .Xr atf 7 .
133 .It Sy sys/
134 .Nx
135 kernel sources.
136 .It Sy tools/
137 .Dq Reachover
138 build structure for the host build tools.
139 This has a special method of determining out-of-date status.
140 .It Sy bin/ ... usr.sbin/
141 Sources to the
142 .Nx
143 userland (non-kernel) programs.
144 If any of these directories are missing, they will be skipped during the build.
145 .It Sy x11/
146 .Dq Reachover
147 build structure for X11R6; the source is in
148 .Sy X11SRCDIR .
149 .El
150 .
151 .Ss Build tree layout
152 .
153 The
154 .Nx
155 build tree is described in
156 .Xr hier 7 ,
157 and the release layout is described in
158 .Xr release 7 .
159 .Pp
160 .
161 .Sh CONFIGURATION
162 .
163 .Ss Environment variables
164 ..
165 Several environment variables control the behaviour of
166 .Nx
167 builds.
168 .
169 .Bl -tag -width "MAKEOBJDIRPREFIX"
170 .
171 .
172 .It Sy HOST_SH
173 Path name to a POSIX-compliant shell.
174 If this is not set explicitly, then the default is set
175 using heuristics dependent on the host platform,
176 or from the shell under which
177 .Nm build.sh
178 is executed (if that can be determined),
179 or using the first copy of
180 .Pa sh
181 found in
182 .Sy PATH .
183 If the host system's
184 .Pa /bin/sh
185 is not POSIX-compliant, we suggest that you build using
186 commands like
187 .Bd -unfilled -offset indent
188 .Li HOST_SH= Ns Va /path/to/working/shell
189 .Li export HOST_SH
190 .Li ${HOST_SH} build.sh Op Ar options
191 .Ed
192 .
193 .It Sy HOST_CC
194 Path name to C compiler used to create the toolchain.
195 .
196 .It Sy HOST_CXX
197 Path name to C++ compiler used to create the toolchain.
198 .
199 .It Sy MACHINE
200 Machine type, e.g.,
201 .Dq macppc .
202 .
203 .It Sy MACHINE_ARCH
204 Machine architecture, e.g.,
205 .Dq powerpc .
206 .
207 .It Sy MAKE
208 Path name to invoke
209 .Xr make 1
210 as.
211 .
212 .It Sy MAKEFLAGS
213 Flags to invoke
214 .Xr make 1
215 with.
216 .
217 .It Sy MAKEOBJDIR
218 Directory to use as the
219 .Sy .OBJDIR
220 for the current directory.
221 The value is subjected to variable expansion by
222 .Xr make 1 .
223 Typical usage is to set this variable to a value involving the use of
224 .Sq ${.CURDIR:S...}
225 or
226 .Sq ${.CURDIR:C...} ,
227 to derive the value of
228 .Sy .OBJDIR
229 from the value of
230 .Sy .CURDIR .
231 Used only if
232 .Sy MAKEOBJDIRPREFIX
233 is not defined.
234 .Sy MAKEOBJDIR
235 can be provided only in the environment or via the
236 .Fl O
237 flag of
238 .Nm build.sh ;
239 it cannot usefully be set inside a Makefile, including
240 .Pa mk.conf
241 or
242 .Sy ${MAKECONF} .
243 .
244 .It Sy MAKEOBJDIRPREFIX
245 Top level directory of the object directory tree.
246 The value is subjected to variable expansion by
247 .Xr make 1 .
248 .Sy build.sh
249 will create the
250 ${MAKEOBJDIRPREFIX}
251 directory if necessary, but if
252 .Xr make 1
253 is used without
254 .Sy build.sh ,
255 then rules in
256 .Aq bsd.obj.mk
257 will abort the build if the
258 ${MAKEOBJDIRPREFIX}
259 directory does not exist.
260 If the value is defined and valid, then
261 ${MAKEOBJDIRPREFIX}/${.CURDIR}
262 is used as the
263 .Sy .OBJDIR
264 for the current directory.
265 The current directory may be read only.
266 .Sy MAKEOBJDIRPREFIX
267 can be provided only in the environment or via the
268 .Fl M
269 flag of
270 .Nm build.sh ;
271 it cannot usefully be set inside a Makefile, including
272 .Pa mk.conf
273 or
274 .Sy ${MAKECONF} .
275 .
276 .El
277 .
278 .Ss \*qmake\*q variables
279 .
280 .de YorN
281 Can be set to
282 .Dq yes
283 or
284 .Dq no .
285 ..
286 .de DFLT
287 .Pp
288 .Em Default :
289 ..
290 .de DFLTu
291 .DFLT
292 Unset.
293 ..
294 .de DFLTy
295 .DFLT
296 .Dq yes
297 ..
298 .de DFLTn
299 .DFLT
300 .Dq no
301 ..
302 Several variables control the behavior of
303 .Nx
304 builds.
305 Unless otherwise specified, these variables may be set in
306 either the process environment or the
307 .Xr make 1
308 configuration file specified by
309 .Sy MAKECONF .
310 .
311 .Bl -tag -width "MKCATPAGES"
312 .
313 .It Sy BUILDID
314 Identifier for the build.
315 The identifier will be appended to
316 object directory names, and can be consulted in the
317 .Xr make 1
318 configuration file in order to set additional build parameters,
319 such as compiler flags.
320 .
321 .It Sy BUILDSEED
322 GCC uses random numbers when compiling C++ code.
323 This variable seeds the gcc random number generator using
324 the -frandom-seed flag with this value.
325 By default, it is set to NetBSD-(majorversion).
326 Using a fixed value causes C++ binaries to be the same when
327 built from the same sources, resulting in identical (reproducible) builds.
328 Additional information is available in the GCC
329 documentation of -frandom-seed.
330 .
331 .It Sy DESTDIR
332 Directory to contain the built
333 .Nx
334 system.
335 If set, special options are passed to the compilation tools to
336 prevent their default use of the host system's
337 .Sy /usr/include , /usr/lib ,
338 and so forth.
339 This pathname must be an absolute path, and should
340 .Em not
341 end with a slash
342 .Pq /
343 character.
344 (For installation into the system's root directory, set
345 .Sy DESTDIR
346 to an empty string, not to
347 .Dq / ) .
348 The directory must reside on a file system which supports long file
349 names and hard links.
350 .DFLT
351 Empty string if
352 .Sy USETOOLS
353 is
354 .Dq yes ;
355 unset otherwise.
356 .Pp
357 .Em Note :
358 .Sy build.sh
359 will provide a default of
360 .Pa destdir. Ns Sy MACHINE
361 (in the top-level
362 .Sy .OBJDIR )
363 unless run in
364 .Sq expert
365 mode.
366 .
367 .It Sy MAKECONF
368 The name of the
369 .Xr make 1
370 configuration file.
371 .Em Only settable in the process environment.
372 .DFLT
373 .Dq /etc/mk.conf
374 .
375 .It Sy MAKEVERBOSE
376 Level of verbosity of status messages.
377 Supported values:
378 .Bl -tag -width xxx
379 .It 0
380 No descriptive messages or commands executed by
381 .Xr make 1
382 are shown.
383 .It 1
384 Brief messages are shown describing what is being done,
385 but the actual commands executed by
386 .Xr make 1
387 are not displayed.
388 .It 2
389 Descriptive messages are shown as above (prefixed with a
390 .Sq # ) ,
391 and ordinary commands performed by
392 .Xr make 1
393 are displayed.
394 .It 3
395 In addition to the above, all commands performed by
396 .Xr make 1
397 are displayed, even if they would ordinarily have been hidden
398 through use of the
399 .Dq \&@
400 prefix in the relevant makefile.
401 .It 4
402 In addition to the above, commands executed by
403 .Xr make 1
404 are traced through use of the
405 .Xr sh 1
406 .Dq Fl x
407 flag.
408 .El
409 .DFLT
410 2
411 .
412 .It Sy MKCATPAGES
413 .YorN
414 Indicates whether preformatted plaintext manual pages will be created
415 during a build.
416 .DFLTy
417 .
418 .It Sy MKCRYPTO
419 .YorN
420 Indicates whether cryptographic code will be included in a build;
421 provided for the benefit of countries that do not allow strong
422 cryptography.
423 Will not affect use of the standard low-security password encryption system,
424 .Xr crypt 3 .
425 .DFLTy
426 .
427 .It Sy MKDOC
428 .YorN
429 Indicates whether system documentation destined for
430 .Sy DESTDIR Ns Pa /usr/share/doc
431 will be installed during a build.
432 .DFLTy
433 .
434 .It Sy MKHTML
435 .YorN
436 Indicates whether preformatted HTML manual pages will be built
437 and installed
438 .DFLTy
439 .
440 .It Sy MKHOSTOBJ
441 .YorN
442 If set to
443 .Dq yes ,
444 then for programs intended to be run on the compile host,
445 the name, release, and architecture of the host operating system
446 will be suffixed to the name of the object directory created by
447 .Dq make obj .
448 (This allows multiple host systems to compile NetBSD for a single target.)
449 If set to
450 .Dq no ,
451 then programs built to be run on the compile host will use the same
452 object directory names as programs built to be run on the target.
453 .DFLTn
454 .
455 .It Sy MKINFO
456 .YorN
457 Indicates whether GNU Info files, used for the documentation for
458 most of the compilation tools, will be created and installed during a
459 build.
460 .DFLTy
461 .
462 .It Sy MKLINT
463 .YorN
464 Indicates whether
465 .Xr lint 1
466 will be run against portions of the
467 .Nx
468 source code during the build, and whether lint libraries will be
469 installed into
470 .Sy DESTDIR Ns Pa /usr/libdata/lint .
471 .DFLTy
472 .
473 .It Sy MKMAN
474 .YorN
475 Indicates whether manual pages will be installed during a build.
476 .DFLTy
477 .
478 .It Sy MKNLS
479 .YorN
480 Indicates whether Native Language System locale zone files will be
481 compiled and installed during a build.
482 .DFLTy
483 .
484 .It Sy MKOBJ
485 .YorN
486 Indicates whether object directories will be created when running
487 .Dq make obj .
488 If set to
489 .Dq no ,
490 then all built files will be located inside the regular source tree.
491 .DFLTy
492 .Pp
493 Note that setting
494 .Sy MKOBJ
495 to
496 .Dq no
497 is not recommended and may cause problems when updating the tree with
498 .Xr cvs 1 .
499 .
500 .It Sy MKPIC
501 .YorN
502 Indicates whether shared objects and libraries will be created and
503 installed during a build.
504 If set to
505 .Dq no ,
506 the entire built system will be statically linked.
507 .DFLT
508 Platform dependent.
509 As of this writing, all platforms except
510 .Sy sh3
511 default to
512 .Dq yes .
513 .
514 .It Sy MKPICINSTALL
515 .YorN
516 Indicates whether the
517 .Xr ar 1
518 format libraries
519 .Sy ( lib*_pic.a ) ,
520 used to generate shared libraries, are installed during a build.
521 .DFLTy
522 .
523 .It Sy MKPROFILE
524 .YorN
525 Indicates whether profiled libraries
526 .Sy ( lib*_p.a )
527 will be built and installed during a build.
528 .DFLT
529 .Dq yes ;
530 however, some platforms turn off
531 .Sy MKPROFILE
532 by default at times due to toolchain problems with profiled code.
533 .
534 .It Sy MKSHARE
535 .YorN
536 Indicates whether files destined to reside in
537 .Sy DESTDIR Ns Pa /usr/share
538 will be built and installed during a build.
539 If set to
540 .Dq no ,
541 then all of
542 .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
543 and
544 .Sy MKNLS
545 will be set to
546 .Dq no
547 unconditionally.
548 .DFLTy
549 .
550 .It Sy MKSTRIPIDENT
551 .YorN
552 Indicates whether program binaries and shared libraries should be built
553 to include RCS IDs for use with
554 .Xr ident 1 .
555 .DFLTn
556 .
557 .It Sy MKSUBPIXEL
558 .YorN
559 For X builds, decides if subpixel rendering code in FreeType
560 is turned on.
561 Turned off by default because of patent issues.
562 .DFLTn
563 .
564 .It Sy MKTTINTERP
565 .YorN
566 For X builds, decides if the TrueType bytecode interpreter
567 is turned on.
568 See
569 .Pa http://www.freetype.org/patents.html
570 for details.
571 .DFLTn
572 .
573 .It Sy MKUNPRIVED
574 .YorN
575 Indicates whether an unprivileged install will occur.
576 The user, group, permissions, and file flags, will not be set on
577 the installed items; instead the information will be appended to
578 a file called
579 .Pa METALOG
580 in
581 .Sy DESTDIR .
582 The contents of
583 .Pa METALOG
584 are used during the generation of the distribution tar files to ensure
585 that the appropriate file ownership is stored.
586 .DFLTn
587 .
588 .It Sy MKUPDATE
589 .YorN
590 Indicates whether all install operations intended to write to
591 .Sy DESTDIR
592 will compare file timestamps before installing, and skip the install
593 phase if the destination files are up-to-date.
594 This also has implications on full builds (see next subsection).
595 .DFLTn
596 .
597 .It Sy MKX11
598 .YorN
599 Indicates whether X11 is built from
600 .Sy X11SRCDIR .
601 .DFLTn
602 .
603 .It Sy TOOLDIR
604 Directory to hold the host tools, once built.
605 If specified, must be an absolute path.
606 This directory should be unique to a given host system and
607 .Nx
608 source tree.
609 (However, multiple targets may share the same
610 .Sy TOOLDIR ;
611 the target-dependent files have unique names.) If unset, a default based
612 on the
613 .Xr uname 1
614 information of the host platform will be created in the
615 .Sy .OBJDIR
616 of
617 .Pa src .
618 .DFLTu
619 .
620 .It Sy USETOOLS
621 Indicates whether the tools specified by
622 .Sy TOOLDIR
623 should be used as part of a build in progress.
624 Must be set to
625 .Dq yes
626 if cross-compiling.
627 .Bl -tag -width "never"
628 .It Sy yes
629 Use the tools from
630 .Sy TOOLDIR .
631 .It Sy no
632 Do not use the tools from
633 .Sy TOOLDIR ,
634 but refuse to build native compilation tool components that are
635 version-specific for that tool.
636 .It Sy never
637 Do not use the tools from
638 .Sy TOOLDIR ,
639 even when building native tool components.
640 This is similar to the traditional
641 .Nx
642 build method, but does
643 .Em not
644 verify that the compilation tools in use are up-to-date enough in order
645 to build the tree successfully.
646 This may cause build or runtime problems when building the whole
647 .Nx
648 source tree.
649 .El
650 .DFLT
651 .Dq yes ,
652 unless
653 .Sy TOOLCHAIN_MISSING
654 is set to
655 .Dq yes .
656 .Pp
657 .Sy USETOOLS
658 is also set to
659 .Dq no
660 when using
661 .Aq bsd.*.mk
662 outside the
663 .Nx
664 source tree.
665 .
666 .It Sy X11SRCDIR
667 Directory containing the X11R6 source.
668 If specified, must be an absolute path.
669 The main X11R6 source is found in
670 .Sy X11SRCDIR Ns Pa /xfree/xc .
671 .DFLT
672 .Sy NETBSDRCDIR Ns Pa /../xsrc ,
673 if that exists; otherwise
674 .Pa /usr/xsrc .
675 .
676 .It Sy X11FLAVOUR
677 The style of X11 cross-built, set to either
678 .Dq Xorg
679 or
680 .Dq XFree86 .
681 .DFLT
682 .Dq Xorg
683 on amd64, i386, macppc, shark and sparc64 platforms,
684 .Dq XFree86
685 on everything else.
686 .
687 .El
688 .
689 .Ss \*qmake\*q variables for full builds
690 These variables only affect the top level
691 .Dq Makefile
692 and do not affect manually building subtrees of the
693 .Nx
694 source code.
695 .
696 .Bl -tag -width "INSTALLWORLDDIR"
697 .
698 .It Sy INSTALLWORLDDIR
699 Location for the
700 .Dq make installworld
701 target to install to.
702 If specified, must be an absolute path.
703 .DFLT
704 .Dq /
705 .
706 .It Sy MKOBJDIRS
707 .YorN
708 Indicates whether object directories will be created automatically
709 (via a
710 .Dq make obj
711 pass) at the start of a build.
712 .DFLTn
713 .Pp
714 If using
715 .Sy build.sh ,
716 the default is
717 .Dq yes .
718 This may be set back to
719 .Dq no
720 by giving
721 .Sy build.sh
722 the
723 .Fl o
724 option.
725 .
726 .It Sy MKUPDATE
727 .YorN
728 If set, then in addition to the effects described for
729 .Sy MKUPDATE=yes
730 above, this implies the effects of
731 .Sy NOCLEANDIR
732 (i.e.,
733 .Dq make cleandir
734 is avoided).
735 .DFLTn
736 .Pp
737 If using
738 .Sy build.sh ,
739 this may be set by giving the
740 .Fl u
741 option.
742 .
743 .It Sy NBUILDJOBS
744 Now obsolete.
745 Use the
746 .Xr make 1
747 option
748 .Fl j ,
749 instead.
750 See below.
751 .DFLTu
752 .
753 .It Sy NOCLEANDIR
754 If set, avoids the
755 .Dq make cleandir
756 phase of a full build.
757 This has the effect of allowing only changed
758 files in a source tree to be recompiled.
759 This can speed up builds when updating only a few files in the tree.
760 .DFLTu
761 .Pp
762 See also
763 .Sy MKUPDATE .
764 .
765 .It Sy NODISTRIBDIRS
766 If set, avoids the
767 .Dq make distrib-dirs
768 phase of a full build.
769 This skips running
770 .Xr mtree 8
771 on
772 .Sy DESTDIR ,
773 useful on systems where building as an unprivileged user, or where it is
774 known that the system-wide mtree files have not changed.
775 .DFLTu
776 .
777 .It Sy NOINCLUDES
778 If set, avoids the
779 .Dq make includes
780 phase of a full build.
781 This has the effect of preventing
782 .Xr make 1
783 from thinking that some programs are out-of-date simply because the
784 system include files have changed.
785 However, this option should not be used when updating the entire
786 .Nx
787 source tree arbitrarily; it is suggested to use
788 .Sy MKUPDATE=yes
789 instead in that case.
790 .DFLTu
791 .
792 .It Sy RELEASEDIR
793 If set, specifies the directory to which a
794 .Xr release 7
795 layout will be written at the end of a
796 .Dq make release .
797 If specified, must be an absolute path.
798 .DFLTu
799 .Pp
800 .Em Note :
801 .Sy build.sh
802 will provide a default of
803 .Pa releasedir
804 (in the top-level
805 .Sy .OBJDIR )
806 unless run in
807 .Sq expert
808 mode.
809 .
810 .El
811 .
812 .Sh BUILDING
813 .
814 .Ss \*qmake\*q command line options
815 This is not a summary of all the options available to
816 .Xr make 1 ;
817 only the options used most frequently with
818 .Nx
819 builds are listed here.
820 .
821 .Bl -tag -width "var=value"
822 .
823 .It Fl j Ar njob
824 Run up to
825 .Ar njob
826 .Xr make 1
827 subjobs in parallel.
828 Makefiles should use .WAIT or have explicit dependencies
829 as necessary to enforce build ordering.
830 .
831 .It Fl m Ar dir
832 Specify the default directory for searching for system Makefile
833 segments, mainly the
834 .Aq bsd.*.mk
835 files.
836 When building any full
837 .Nx
838 source tree, this should be set to the
839 .Dq share/mk
840 directory in the source tree.
841 This is set automatically when building from the top level, or when using
842 .Sy build.sh .
843 .
844 .It Fl n
845 Display the commands that would have been executed, but do not
846 actually execute them.
847 This will still cause recursion to take place.
848 .
849 .It Fl V Ar var
850 Print
851 .Xr make 1 Ns 's
852 idea of the value of
853 .Ar var .
854 Does not build any targets.
855 .
856 .It Em var=value
857 Set the variable
858 .Em var
859 to
860 .Em value ,
861 overriding any setting specified by the process environment, the
862 .Sy MAKECONF
863 configuration file, or the system Makefile segments.
864 .
865 .El
866 .
867 .Ss \*qmake\*q targets
868 .
869 These default targets may be built by running
870 .Xr make 1
871 in any subtree of the
872 .Nx
873 source code.
874 It is recommended that none of these be used from the top
875 level Makefile; as a specific exception,
876 .Dq make obj
877 and
878 .Dq make cleandir
879 are useful in that context.
880 .
881 .Bl -tag -width "dependall"
882 .
883 .It Sy all
884 Build programs, libraries, and preformatted documentation.
885 .
886 .It Sy clean
887 Remove program and library object code files.
888 .
889 .It Sy cleandir
890 Same as
891 .Sy clean ,
892 but also remove preformatted documentation, dependency files generated
893 by
894 .Dq make depend ,
895 and any other files known to be created at build time.
896 .
897 .It Sy depend
898 Create dependency files
899 .Sy ( .depend )
900 containing more detailed information about the dependencies of source
901 code on header files.
902 Allows programs to be recompiled automatically when a dependency changes.
903 .
904 .It Sy dependall
905 Does a
906 .Dq make depend
907 immediately followed by a
908 .Dq make all .
909 This improves cache locality of the build since both passes read the source
910 files in their entirety.
911 .
912 .It Sy distclean
913 Synonym for
914 .Sy cleandir .
915 .
916 .It Sy includes
917 Build and install system header files.
918 Typically needed before any system libraries or programs can be built.
919 .
920 .It Sy install
921 Install programs, libraries, and documentation into
922 .Sy DESTDIR .
923 Few files will be installed to
924 .Sy DESTDIR Ns Pa /dev ,
925 .Sy DESTDIR Ns Pa /etc ,
926 .Sy DESTDIR Ns Pa /root
927 or
928 .Sy DESTDIR Ns Pa /var
929 in order to prevent user supplied configuration data from being overwritten.
930 .It Sy lint
931 Run
932 .Xr lint 1
933 against the C source code, where appropriate, and generate
934 system-installed lint libraries.
935 .
936 .It Sy obj
937 Create object directories to be used for built files, instead of
938 building directly in the source tree.
939 .
940 .It Sy tags
941 Create
942 .Xr ctags 1
943 searchable function lists usable by the
944 .Xr ex 1
945 and
946 .Xr vi 1
947 text editors.
948 .
949 .El
950 .
951 .Ss \*qmake\*q targets for the top level
952 .
953 Additional
954 .Xr make 1
955 targets are usable specifically from the top source level to facilitate
956 building the entire
957 .Nx
958 source tree.
959 .
960 .Bl -tag -width "distribution"
961 .
962 .It Sy build
963 Build the entire
964 .Nx
965 system (except the kernel).
966 This orders portions of the source tree such that prerequisites
967 will be built in the proper order.
968 .
969 .It Sy distribution
970 Do a
971 .Dq make build ,
972 and then install a full distribution (which does not include a kernel) into
973 .Sy DESTDIR ,
974 including files in
975 .Sy DESTDIR Ns Pa /dev ,
976 .Sy DESTDIR Ns Pa /etc ,
977 .Sy DESTDIR Ns Pa /root
978 and
979 .Sy DESTDIR Ns Pa /var .
980 .
981 .It Sy buildworld
982 As per
983 .Dq make distribution ,
984 except that it ensures that
985 .Sy DESTDIR
986 is not the root directory.
987 .
988 .It Sy installworld
989 Install the distribution from
990 .Sy DESTDIR
991 to
992 .Sy INSTALLWORLDDIR ,
993 which defaults to the root directory.
994 Ensures that
995 .Sy INSTALLWORLDDIR
996 is not the root directory if cross compiling.
997 .Pp
998 The
999 .Sy INSTALLSETS
1000 environment variable may be set to a list of
1001 distribution sets to be installed.
1002 By default, all sets except
1003 .Dq etc
1004 and
1005 .Dq xetc
1006 are installed, so most files in
1007 .Sy INSTALLWORLDDIR Ns Pa /etc
1008 will not be installed or modified.
1009 .Pp
1010 .Em Note :
1011 Before performing this operation with
1012 .Sy INSTALLWORLDDIR Ns = Ns Pa / ,
1013 it is highly recommended that you upgrade your kernel and reboot.
1014 After performing this operation,
1015 it is recommended that you use
1016 .Xr etcupdate 8
1017 to update files in
1018 .Sy INSTALLWORLDDIR Ns Pa /etc
1019 and that you use
1020 .Xr postinstall 8
1021 to check for inconsistencies (and possibly to fix them).
1022 .It Sy sets
1023 Create distribution sets from
1024 .Sy DESTDIR
1025 into
1026 .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets .
1027 Should be run after
1028 .Dq make distribution ,
1029 as
1030 .Dq make build
1031 alone does not install all of the required files.
1032 .
1033 .It Sy sourcesets
1034 Create source sets of the source tree into
1035 .Sy RELEASEDIR Ns Pa /source/sets .
1036 .
1037 .It Sy syspkgs
1038 Create syspkgs from
1039 .Sy DESTDIR
1040 into
1041 .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs .
1042 Should be run after
1043 .Dq make distribution ,
1044 as
1045 .Dq make build
1046 alone does not install all of the required files.
1047 .
1048 .It Sy release
1049 Do a
1050 .Dq make distribution ,
1051 build kernels, distribution media, and install sets
1052 (this as per
1053 .Dq make sets ) ,
1054 and
1055 then package the system into a standard release layout as described by
1056 .Xr release 7 .
1057 This requires that
1058 .Sy RELEASEDIR
1059 be set (see above).
1060 .
1061 .It Sy iso-image
1062 Create a
1063 .Nx
1064 installation CD-ROM image in the
1065 .Sy RELEASEDIR Ns Pa /iso
1066 directory.
1067 The CD-ROM file system will have a layout as described in
1068 .Xr release 7 .
1069 .Pp
1070 For most machine types, the CD-ROM will be bootable, and will automatically
1071 run the
1072 .Xr sysinst 8
1073 menu-based installation program, which can be used to install or upgrade a
1074 .Nx
1075 system.
1076 Bootable CD-ROMs also contain tools that may be useful in
1077 repairing a damaged
1078 .Nx
1079 installation.
1080 .Pp
1081 Before
1082 .Dq make iso-image
1083 is attempted, RELEASEDIR must be populated by
1084 .Dq make release
1085 or equivalent.
1086 .Pp
1087 Note that other, smaller, CD-ROM images may be created in the
1088 .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1089 directory by
1090 .Dq "make release" .
1091 These smaller images usually contain the same tools as the larger images in
1092 .Sy RELEASEDIR Ns Pa /iso ,
1093 but do not contain additional content such as the distribution sets.
1094 .Pp
1095 Note that the mac68k port still uses an older method of creating
1096 CD-ROM images.
1097 This requires the
1098 .Xr mkisofs 1
1099 utility, which is not part of
1100 .Nx ,
1101 but which can be installed from
1102 .Pa pkgsrc/sysutils/cdrtools .
1103 .
1104 .It Sy iso-image-source
1105 Create a
1106 .Nx
1107 installation CD-ROM image in the
1108 .Sy RELEASEDIR Ns Pa /iso
1109 directory.
1110 The CD-ROM file system will have a layout as described in
1111 .Xr release 7 .
1112 It will have top level directories for the machine type and source.
1113 .Pp
1114 For most machine types, the CD-ROM will be bootable, and will automatically
1115 run the
1116 .Xr sysinst 8
1117 menu-based installation program, which can be used to install or upgrade a
1118 .Nx
1119 system.
1120 Bootable CD-ROMs also contain tools that may be useful in
1121 repairing a damaged
1122 .Nx
1123 installation.
1124 .Pp
1125 Before
1126 .Dq make iso-image-source
1127 is attempted, RELEASEDIR must be populated by
1128 .Dq make sourcesets release
1129 or equivalent.
1130 .Pp
1131 Note that other, smaller, CD-ROM images may be created in the
1132 .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1133 directory by
1134 .Dq make release .
1135 These smaller images usually contain the same tools as the larger images in
1136 .Sy RELEASEDIR Ns Pa /iso ,
1137 but do not contain additional content such as the distribution sets.
1138 .Pp
1139 Note that the mac68k port still uses an older method of creating
1140 CD-ROM images.
1141 This requires the
1142 .Xr mkisofs 1
1143 utility, which is not part of
1144 .Nx ,
1145 but which can be installed from
1146 .Pa pkgsrc/sysutils/cdrtools .
1147 .
1148 .It Sy regression-tests
1149 Can only be run after building the regression tests in the directory
1150 .Dq regress .
1151 Runs those compiled regression tests on the local host.
1152 Note that most tests are now managed instead using
1153 .Xr atf 7 ;
1154 this target should probably run those as well but currently does not.
1155 .
1156 .El
1157 .
1158 .Ss The \*qbuild.sh\*q script
1159 .
1160 This script file is a Bourne shell script designed to build the
1161 entire
1162 .Nx
1163 system on any host with a Bourne shell in
1164 .Sy /bin/sh ,
1165 including many that are not POSIX compliant.
1166 Note that if a host system's
1167 .Sy /bin/sh
1168 is unusually old and broken, the Korn Shell
1169 .Sy ( /bin/ksh ) ,
1170 if available, may be a usable alternative.
1171 .Pp
1172 All cross-compile builds, and most native builds, of the entire system
1173 should make use of
1174 .Sy build.sh
1175 rather than just running
1176 .Dq make .
1177 This way, the
1178 .Xr make 1
1179 program will be bootstrapped properly, in case the host system has an
1180 older or incompatible
1181 .Dq make
1182 program.
1183 .Pp
1184 When compiling the entire system via
1185 .Sy build.sh ,
1186 many
1187 .Xr make 1
1188 variables are set for you in order to help encapsulate the build
1189 process.
1190 In the list of options below, variables that are automatically set by
1191 .Sy build.sh
1192 are noted where applicable.
1193 .
1194 .Pp
1195 The following operations are supported by
1196 .Sy build.sh :
1197 .
1198 .Bl -tag -width "distribution"
1199 .
1200 .It Sy build
1201 Build the system as per
1202 .Dq make build .
1203 Before the main part of the build commences, this command runs the
1204 .Sy obj
1205 operation (unless the
1206 .Fl o
1207 option is given),
1208 .Dq make cleandir
1209 (unless the
1210 .Fl u
1211 option is given),
1212 and the
1213 .Sy tools
1214 operation.
1215 .
1216 .It Sy distribution
1217 Build a full distribution as per
1218 .Dq make distribution .
1219 This command first runs the
1220 .Sy build
1221 operation.
1222 .
1223 .It Sy release
1224 Build a full release as per
1225 .Dq make release .
1226 This command first runs the
1227 .Sy distribution
1228 operation.
1229 .
1230 .It Sy makewrapper
1231 Create the
1232 .Sy \*[toolprefix]make-MACHINE
1233 wrapper.
1234 This operation is automatically performed for any of the other
1235 operations.
1236 .
1237 .It Sy cleandir
1238 Perform
1239 .Dq make cleandir .
1240 .
1241 .It Sy obj
1242 Perform
1243 .Dq make obj .
1244 .
1245 .It Sy tools
1246 Build and install the host tools from
1247 .Pa src/tools .
1248 This command will first run
1249 .Dq make obj
1250 and
1251 .Dq make cleandir
1252 in the
1253 .Pa tools
1254 subdirectory unless the
1255 .Fl o
1256 or
1257 .Fl u
1258 options (respectively) are given.
1259 .
1260 .It Sy install Ns = Ns Ar idir
1261 Install the contents of
1262 .Sy DESTDIR
1263 to
1264 .Ar idir ,
1265 using
1266 .Dq make installworld .
1267 Note that files that are part of the
1268 .Dq etc
1269 or
1270 .Dq xetc
1271 sets will not be installed.
1272 .
1273 .It Sy kernel Ns = Ns Ar kconf
1274 Build a new kernel.
1275 The
1276 .Ar kconf
1277 argument is the name of a configuration file suitable
1278 for use by
1279 .Xr config 1 .
1280 If
1281 .Ar kconf
1282 does not contain any
1283 .Sq /
1284 characters, the configuration file is expected to be found in the
1285 .Sy KERNCONFDIR
1286 directory, which is typically
1287 .Sy sys/arch/MACHINE/conf .
1288 The new kernel will be built in a subdirectory of
1289 .Sy KERNOBJDIR ,
1290 which is typically
1291 .Sy sys/arch/MACHINE/compile
1292 or an associated object directory.
1293 .Pp
1294 This command does
1295 .Em not
1296 imply the
1297 .Sy tools
1298 command; run the
1299 .Sy tools
1300 command first unless it is
1301 .Em certain
1302 that the tools already exist and are up to date.
1303 .Pp
1304 This command will run
1305 .Dq make cleandir
1306 on the kernel in question first unless the
1307 .Fl u
1308 option is given.
1309 .
1310 .It Sy modules
1311 This command will build kernel modules and install them into
1312 .Sy DESTDIR .
1313 .
1314 .It Sy releasekernel Ns = Ns Ar kconf
1315 Install a
1316 .Xr gzip 1 Ns ed
1317 copy of the kernel previously built by
1318 .Sy kernel Ns = Ns Ar kconf
1319 into
1320 .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel ,
1321 usually as
1322 .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
1323 although the
1324 .Dq Pa netbsd
1325 prefix is determined from the
1326 .Dq Sy config
1327 directives in
1328 .Ar kconf .
1329 .
1330 .It Sy sets
1331 Perform
1332 .Dq make sets .
1333 .
1334 .It Sy sourcesets
1335 Perform
1336 .Dq make sourcesets .
1337 .
1338 .It Sy syspkgs
1339 Perform
1340 .Dq make syspkgs .
1341 .
1342 .It Sy iso-image
1343 Perform
1344 .Dq make iso-image .
1345 .
1346 .It Sy iso-image-source
1347 Perform
1348 .Dq make iso-image-source .
1349 .
1350 .El
1351 .
1352 .Pp
1353 The following command line options alter the behaviour of the
1354 .Sy build.sh
1355 operations described above:
1356 .
1357 .Bl -tag -width "-T tools"
1358 .
1359 .It Fl a Ar arch
1360 Set the value of
1361 .Sy MACHINE_ARCH
1362 to
1363 .Ar arch .
1364 .
1365 .It Fl B Ar buildid
1366 Set the value of
1367 .Sy BUILDID
1368 to
1369 .Ar buildid .
1370 This will also append the build identifier to the name of the
1371 .Dq make
1372 wrapper script so that the resulting name is of the form
1373 .Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1374 .
1375 .It Fl C Ar cdextras
1376 Append
1377 .Ar cdextras
1378 to the
1379 .Sy CDEXTRA
1380 variable,
1381 which is a space-separated list of files or directories that will be
1382 added to the CD-ROM image that may be create by the
1383 .Dq iso-image
1384 or
1385 .Dq iso-image-source
1386 operations.
1387 Files will be added to the root of the CD-ROM image, whereas directories
1388 will be copied recursively.
1389 If relative paths are specified, they will be converted to
1390 absolute paths before being used.
1391 Multiple paths may be specified via multiple
1392 .Fl C
1393 options, or via a single option whose argument contains multiple
1394 space-separated paths.
1395 .
1396 .It Fl D Ar dest
1397 Set the value of
1398 .Sy DESTDIR
1399 to
1400 .Ar dest .
1401 If a relative path is specified, it will be converted to an
1402 absolute path before being used.
1403 .
1404 .It Fl E
1405 Set
1406 .Sq expert
1407 mode.
1408 This overrides various sanity checks, and allows:
1409 .Sy DESTDIR
1410 does not have to be set to a non-root path for builds,
1411 and
1412 .Sy MKUNPRIVED=yes
1413 does not have to be set when building as a non-root user.
1414 .Pp
1415 .Em Note :
1416 It is highly recommended that you know what you are doing when
1417 you use this option.
1418 .
1419 .It Fl h
1420 Print a help message.
1421 .
1422 .It Fl j Ar njob
1423 Run up to
1424 .Ar njob
1425 .Xr make 1
1426 subjobs in parallel;
1427 passed through to
1428 .Xr make 1 .
1429 If you see failures for reasons other than running out of memory
1430 while using
1431 .Sy build.sh
1432 with
1433 .Fl j ,
1434 please save complete build logs
1435 so the failures can be analyzed.
1436 .Pp
1437 To achieve the fastest builds,
1438 .Fl j
1439 values between (1 + the number of CPUs) and (2 * the number of CPUs)
1440 are recommended.
1441 Use lower values on machines with limited memory or I/O bandwidth.
1442 .
1443 .It Fl M Ar obj
1444 Set
1445 .Sy MAKEOBJDIRPREFIX
1446 to
1447 .Ar obj .
1448 Unsets
1449 .Sy MAKEOBJDIR .
1450 See
1451 .Dq Fl O obj
1452 for more information.
1453 .Pp
1454 For instance, if the source directory is
1455 .Pa /usr/src ,
1456 a setting of
1457 .Dq Fl M Pa /usr/obj
1458 will place build-time files under
1459 .Pa /usr/obj/usr/src/bin ,
1460 .Pa /usr/obj/usr/src/lib ,
1461 .Pa /usr/obj/usr/src/usr.bin ,
1462 and so forth.
1463 .Pp
1464 If a relative path is specified, it will be converted to an
1465 absolute path before being used.
1466 .Sy build.sh
1467 imposes the restriction that the argument to the
1468 .Fl M
1469 option must not begin with a
1470 .Dq \&$
1471 (dollar sign)
1472 character; otherwise it would be too difficult
1473 to determine whether the value is an absolute or a relative path.
1474 If the directory does not already exist,
1475 .Sy build.sh
1476 will create it.
1477 .
1478 .It Fl m Ar mach
1479 Set the value of
1480 .Sy MACHINE
1481 to
1482 .Ar mach ,
1483 except in some special cases listed below.
1484 This will also override any value of
1485 .Sy MACHINE_ARCH
1486 in the process environment with a value deduced from
1487 .Ar mach ,
1488 unless
1489 .Fl a
1490 is specified.
1491 All cross builds require
1492 .Fl m ,
1493 but if unset on a NetBSD host, the host's value of MACHINE will be
1494 detected and used automatically.
1495 .Pp
1496 Some machines support multiple values for
1497 .Sy MACHINE_ARCH .
1498 The following special cases for the
1499 .Ar mach
1500 argument are defined to set the listed values of
1501 .Sy MACHINE
1502 and
1503 .Sy MACHINE_ARCH :
1504 .Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
1505 .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
1506 .It evbarm Ta evbarm Ta (not set)
1507 .It evbarm-eb Ta evbarm Ta armeb
1508 .It evbarm-el Ta evbarm Ta arm
1509 .It evbmips Ta evbmips Ta (not set)
1510 .It evbmips-eb Ta evbmips Ta mipseb
1511 .It evbmips-el Ta evbmips Ta mipsel
1512 .It evbsh3 Ta evbsh3 Ta (not set)
1513 .It evbsh3-eb Ta evbsh3 Ta sh3eb
1514 .It evbsh3-el Ta evbsh3 Ta sh3el
1515 .It sbmips Ta sbmips Ta (not set)
1516 .It sbmips-eb Ta sbmips Ta mipseb
1517 .It sbmips-el Ta sbmips Ta mipsel
1518 .El
1519 .
1520 .It Fl N Ar noiselevel
1521 Set the
1522 .Dq noisyness
1523 level of the build, by setting
1524 .Sy MAKEVERBOSE
1525 to
1526 .Ar noiselevel .
1527 .
1528 .It Fl n
1529 Show the commands that would be executed by
1530 .Sy build.sh ,
1531 but do not make any changes.
1532 This is similar in concept to
1533 .Dq make -n .
1534 .
1535 .It Fl O Ar obj
1536 Create an appropriate transform macro for
1537 .Sy MAKEOBJDIR
1538 that will place the built object files under
1539 .Ar obj .
1540 Unsets
1541 .Sy MAKEOBJDIRPREFIX .
1542 .Pp
1543 For instance, a setting of
1544 .Dq Fl O Pa /usr/obj
1545 will place build-time files under
1546 .Pa /usr/obj/bin ,
1547 .Pa /usr/obj/lib ,
1548 .Pa /usr/obj/usr.bin ,
1549 and so forth.
1550 .Pp
1551 If a relative path is specified, it will be converted to an
1552 absolute path before being used.
1553 .Sy build.sh
1554 imposes the restriction that the argument to the
1555 .Fl O
1556 option must not contain a
1557 .Dq \&$
1558 (dollar sign)
1559 character.
1560 If the directory does not already exist,
1561 .Sy build.sh
1562 will create it.
1563 .Pp
1564 In normal use, exactly one of the
1565 .Fl M
1566 or
1567 .Fl O
1568 options should be specified.
1569 If neither
1570 .Fl M
1571 nor
1572 .Fl O
1573 is specified, then a default object directory will be chosen
1574 according to rules in
1575 .Aq bsd.obj.mk .
1576 Relying on this default is not recommended because
1577 it is determined by complex rules that are influenced
1578 by the values of several variables and
1579 by the location of the source directory.
1580 .It Fl o
1581 Set the value of
1582 .Sy MKOBJDIRS
1583 to
1584 .Dq no .
1585 Otherwise, it will be automatically set to
1586 .Dq yes .
1587 This default is opposite to the behaviour when not using
1588 .Sy build.sh .
1589 .
1590 .It Fl R Ar rel
1591 Set the value of
1592 .Sy RELEASEDIR
1593 to
1594 .Ar rel .
1595 If a relative path is specified, it will be converted to an
1596 absolute path before being used.
1597 .
1598 .It Fl r
1599 Remove the contents of
1600 .Sy DESTDIR
1601 and
1602 .Sy TOOLDIR
1603 before building (provides a clean starting point).
1604 This will skip deleting
1605 .Sy DESTDIR
1606 if building on a native system to the root directory.
1607 .
1608 .It Fl S Ar seed
1609 Change the value of
1610 .Sy BUILDSEED
1611 to
1612 .Ar seed .
1613 This should rarely be necessary.
1614 .
1615 .It Fl T Ar tools
1616 Set the value of
1617 .Sy TOOLDIR
1618 to
1619 .Ar tools .
1620 If a relative path is specified, it will be converted to an
1621 absolute path before being used.
1622 If set, the bootstrap
1623 .Dq make
1624 will only be rebuilt if the source files for
1625 .Xr make 1
1626 have changed.
1627 .
1628 .It Fl U
1629 Set
1630 .Sy MKUNPRIVED=yes .
1631 .
1632 .It Fl u
1633 Set
1634 .Sy MKUPDATE=yes .
1635 .
1636 .It Xo
1637 .Fl V
1638 .Sm off
1639 .Ar var
1640 .Li =
1641 .Op Ar value
1642 .Sm on
1643 .Xc
1644 Set the environment variable
1645 .Ar var
1646 to an optional
1647 .Ar value .
1648 This is propagated to the
1649 .Sy \*[toolprefix]make
1650 wrapper.
1651 .
1652 .It Fl w Ar wrapper
1653 Create the
1654 .Sy \*[toolprefix]make
1655 wrapper script (see below) in a custom location,
1656 specified by
1657 .Ar wrapper .
1658 This allows, for instance, to place the wrapper in
1659 .Sy PATH
1660 automatically.
1661 Note that
1662 .Ar wrapper
1663 is the full name of the file, not just a directory name.
1664 If a relative path is specified, it will be converted to an
1665 absolute path before being used.
1666 .
1667 .It Fl X Ar x11src
1668 Set the value of
1669 .Sy X11SRCDIR
1670 to
1671 .Ar x11src .
1672 If a relative path is specified, it will be converted to an
1673 absolute path before being used.
1674 .
1675 .It Fl x
1676 Set
1677 .Sy MKX11=yes .
1678 .
1679 .It Fl Z Ar var
1680 Unset ("zap") the environment variable
1681 .Ar var .
1682 This is propagated to the
1683 .Sy \*[toolprefix]make
1684 wrapper.
1685 .
1686 .El
1687 .
1688 .Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
1689 .
1690 If using the
1691 .Sy build.sh
1692 script to build
1693 .Nx ,
1694 a
1695 .Sy \*[toolprefix]make-MACHINE
1696 script will be created in
1697 .Sy TOOLDIR/bin
1698 upon the first build to assist in building subtrees on a cross-compile
1699 host.
1700 .Pp
1701 .Sy \*[toolprefix]make-MACHINE
1702 can be invoked in lieu of
1703 .Xr make 1 ,
1704 and will instead call the up-to-date version of
1705 .Dq \*[toolprefix]make
1706 installed into
1707 .Sy TOOLDIR/bin
1708 with several key variables pre-set, including
1709 .Sy MACHINE , MACHINE_ARCH ,
1710 and
1711 .Sy TOOLDIR .
1712 .Sy \*[toolprefix]make-MACHINE
1713 will also set variables specified with
1714 .Fl V ,
1715 and unset variables specified with
1716 .Fl Z .
1717 .Pp
1718 This script can be symlinked into a directory listed in
1719 .Sy PATH ,
1720 or called with an absolute path.
1721 .
1722 .Sh EXAMPLES
1723 .
1724 .Bl -enum
1725 .
1726 .It
1727 .Li "% ./build.sh [options] tools kernel=GENERIC"
1728 .Pp
1729 Build a new toolchain, and use the new toolchain to
1730 configure and build a new GENERIC kernel.
1731 .
1732 .It
1733 .Li "% ./build.sh [options] -U distribution"
1734 .Pp
1735 Using unprivileged mode,
1736 build a complete distribution to a
1737 .Sy DESTDIR
1738 directory that
1739 .Sy build.sh
1740 selects (and will display).
1741 .
1742 .It
1743 .Li "# ./build.sh [options] -U install=/"
1744 .Pp
1745 As root, install to
1746 .Pa /
1747 the distribution that was built
1748 by example 2.
1749 Even though this is run as root,
1750 .Fl U
1751 is required so that the permissions stored in
1752 .Sy DESTDIR Ns Pa /METALOG
1753 are correctly applied to the files as they're copied to
1754 .Pa / .
1755 .
1756 .It
1757 .Li "% ./build.sh [options] -U -u release"
1758 .Pp
1759 Using unprivileged mode,
1760 build a complete release to
1761 .Sy DESTDIR
1762 and
1763 .Sy RELEASEDIR
1764 directories that
1765 .Sy build.sh
1766 selects (and will display).
1767 .Sy MKUPDATE=yes
1768 .Pq Fl u
1769 is set to prevent the
1770 .Dq make cleandir ,
1771 so that if this is run after example 2, it doesn't need to redo that
1772 portion of the release build.
1773 .El
1774 .
1775 .Sh OBSOLETE VARIABLES
1776 .
1777 .Bl -tag -width "NBUILDJOBS"
1778 .
1779 .It Sy NBUILDJOBS
1780 Use the
1781 .Xr make 1
1782 option
1783 .Fl j
1784 instead.
1785 .
1786 .It Sy USE_NEW_TOOLCHAIN
1787 The new toolchain is now the default.
1788 To disable, use
1789 .Sy TOOLCHAIN_MISSING=yes .
1790 .El
1791 .Sh SEE ALSO
1792 .Xr make 1 ,
1793 .Xr hier 7 ,
1794 .Xr release 7 ,
1795 .Xr etcupdate 8 ,
1796 .Xr postinstall 8 ,
1797 .Xr sysinst 8 ,
1798 .Pa pkgsrc/sysutils/cdrtools
1799 .
1800 .Sh HISTORY
1801 .
1802 The
1803 .Nm build.sh
1804 based build scheme was introduced for
1805 .Nx 1.6
1806 as
1807 .Sy USE_NEW_TOOLCHAIN ,
1808 and re-worked to
1809 .Sy TOOLCHAIN_MISSING
1810 after that.