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