Annotation of src/doc/BUILDING.mdoc, Revision 1.87.2.1
1.87.2.1! riz 1: .\" $NetBSD$
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.82 apb 36: .Dd September 9, 2011
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.71 mrg 290: it cannot usefully be set inside a Makefile, including
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: .
558: .It Sy MKSHARE
559: .YorN
560: Indicates whether files destined to reside in
1.14 lukem 561: .Sy DESTDIR Ns Pa /usr/share
1.6 wiz 562: will be built and installed during a build.
563: If set to
1.1 lukem 564: .Dq no ,
565: then all of
566: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
567: and
568: .Sy MKNLS
569: will be set to
570: .Dq no
571: unconditionally.
572: .DFLTy
573: .
1.66 joerg 574: .It Sy MKSTRIPIDENT
575: .YorN
576: Indicates whether program binaries and shared libraries should be built
577: to include RCS IDs for use with
578: .Xr ident 1 .
579: .DFLTn
580: .
1.25 lukem 581: .It Sy MKUNPRIVED
582: .YorN
583: Indicates whether an unprivileged install will occur.
1.1 lukem 584: The user, group, permissions, and file flags, will not be set on
1.37 jmc 585: the installed items; instead the information will be appended to
1.1 lukem 586: a file called
587: .Pa METALOG
588: in
589: .Sy DESTDIR .
590: The contents of
591: .Pa METALOG
1.37 jmc 592: are used during the generation of the distribution tar files to ensure
1.1 lukem 593: that the appropriate file ownership is stored.
1.25 lukem 594: .DFLTn
1.1 lukem 595: .
1.25 lukem 596: .It Sy MKUPDATE
597: .YorN
598: Indicates whether all install operations intended to write to
1.1 lukem 599: .Sy DESTDIR
600: will compare file timestamps before installing, and skip the install
1.6 wiz 601: phase if the destination files are up-to-date.
602: This also has implications on full builds (see next subsection).
1.25 lukem 603: .DFLTn
604: .
1.34 lukem 605: .It Sy MKX11
606: .YorN
1.68 mrg 607: Indicates whether X11 is built from
1.34 lukem 608: .Sy X11SRCDIR .
609: .DFLTn
610: .
1.25 lukem 611: .It Sy TOOLDIR
612: Directory to hold the host tools, once built.
1.46 apb 613: If specified, must be an absolute path.
1.25 lukem 614: This directory should be unique to a given host system and
615: .Nx
616: source tree.
617: (However, multiple targets may share the same
618: .Sy TOOLDIR ;
619: the target-dependent files have unique names.) If unset, a default based
620: on the
621: .Xr uname 1
622: information of the host platform will be created in the
623: .Sy .OBJDIR
624: of
1.26 lukem 625: .Pa src .
1.1 lukem 626: .DFLTu
627: .
628: .It Sy USETOOLS
629: Indicates whether the tools specified by
630: .Sy TOOLDIR
1.6 wiz 631: should be used as part of a build in progress.
632: Must be set to
1.1 lukem 633: .Dq yes
634: if cross-compiling.
635: .Bl -tag -width "never"
636: .It Sy yes
637: Use the tools from
638: .Sy TOOLDIR .
639: .It Sy no
640: Do not use the tools from
641: .Sy TOOLDIR ,
642: but refuse to build native compilation tool components that are
643: version-specific for that tool.
644: .It Sy never
645: Do not use the tools from
646: .Sy TOOLDIR ,
1.6 wiz 647: even when building native tool components.
648: This is similar to the traditional
1.1 lukem 649: .Nx
650: build method, but does
651: .Em not
652: verify that the compilation tools in use are up-to-date enough in order
1.6 wiz 653: to build the tree successfully.
654: This may cause build or runtime problems when building the whole
1.1 lukem 655: .Nx
656: source tree.
657: .El
1.58 dholland 658: .DFLT
659: .Dq yes ,
660: unless
661: .Sy TOOLCHAIN_MISSING
662: is set to
663: .Dq yes .
664: .Pp
665: .Sy USETOOLS
666: is also set to
667: .Dq no
668: when using
669: .Aq bsd.*.mk
670: outside the
671: .Nx
672: source tree.
1.1 lukem 673: .
1.34 lukem 674: .It Sy X11SRCDIR
675: Directory containing the X11R6 source.
1.46 apb 676: If specified, must be an absolute path.
1.34 lukem 677: The main X11R6 source is found in
678: .Sy X11SRCDIR Ns Pa /xfree/xc .
679: .DFLT
1.80 apb 680: .Sy NETBSDRCDIR Ns Pa /../xsrc ,
681: if that exists; otherwise
682: .Pa /usr/xsrc .
1.34 lukem 683: .
1.68 mrg 684: .It Sy X11FLAVOUR
685: The style of X11 cross-built, set to either
686: .Dq Xorg
687: or
688: .Dq XFree86 .
689: .DFLT
690: .Dq Xorg
1.70 mrg 691: on amd64, i386, macppc, shark and sparc64 platforms,
1.68 mrg 692: .Dq XFree86
693: on everything else.
694: .
1.1 lukem 695: .El
696: .
697: .Ss \*qmake\*q variables for full builds
698: These variables only affect the top level
699: .Dq Makefile
700: and do not affect manually building subtrees of the
701: .Nx
702: source code.
703: .
1.7 lukem 704: .Bl -tag -width "INSTALLWORLDDIR"
705: .
706: .It Sy INSTALLWORLDDIR
707: Location for the
708: .Dq make installworld
709: target to install to.
1.46 apb 710: If specified, must be an absolute path.
1.7 lukem 711: .DFLT
712: .Dq /
1.1 lukem 713: .
714: .It Sy MKOBJDIRS
715: .YorN
716: Indicates whether object directories will be created automatically
717: (via a
718: .Dq make obj
719: pass) at the start of a build.
1.21 lukem 720: .DFLTn
1.57 dholland 721: .Pp
722: If using
723: .Sy build.sh ,
724: the default is
725: .Dq yes .
726: This may be set back to
727: .Dq no
728: by giving
729: .Sy build.sh
730: the
731: .Fl o
732: option.
1.1 lukem 733: .
1.25 lukem 734: .It Sy MKUPDATE
735: .YorN
736: If set, then in addition to the effects described for
737: .Sy MKUPDATE=yes
738: above, this implies the effects of
739: .Sy NOCLEANDIR
740: (i.e.,
741: .Dq make cleandir
742: is avoided).
743: .DFLTn
1.57 dholland 744: .Pp
745: If using
746: .Sy build.sh ,
747: this may be set by giving the
748: .Fl u
749: option.
1.25 lukem 750: .
1.1 lukem 751: .It Sy NBUILDJOBS
1.6 wiz 752: Now obsolete.
753: Use the
1.1 lukem 754: .Xr make 1
755: option
1.4 lukem 756: .Fl j ,
1.57 dholland 757: instead.
758: See below.
1.1 lukem 759: .DFLTu
760: .
761: .It Sy NOCLEANDIR
762: If set, avoids the
763: .Dq make cleandir
1.6 wiz 764: phase of a full build.
765: This has the effect of allowing only changed
766: files in a source tree to be recompiled.
767: This can speed up builds when updating only a few files in the tree.
1.1 lukem 768: .DFLTu
1.57 dholland 769: .Pp
770: See also
771: .Sy MKUPDATE .
1.1 lukem 772: .
773: .It Sy NODISTRIBDIRS
774: If set, avoids the
775: .Dq make distrib-dirs
1.6 wiz 776: phase of a full build.
777: This skips running
1.1 lukem 778: .Xr mtree 8
779: on
780: .Sy DESTDIR ,
781: useful on systems where building as an unprivileged user, or where it is
782: known that the system-wide mtree files have not changed.
783: .DFLTu
784: .
785: .It Sy NOINCLUDES
786: If set, avoids the
787: .Dq make includes
1.6 wiz 788: phase of a full build.
789: This has the effect of preventing
1.1 lukem 790: .Xr make 1
791: from thinking that some programs are out-of-date simply because the
1.6 wiz 792: system include files have changed.
793: However, this option should not be used when updating the entire
1.1 lukem 794: .Nx
795: source tree arbitrarily; it is suggested to use
1.25 lukem 796: .Sy MKUPDATE=yes
1.57 dholland 797: instead in that case.
1.1 lukem 798: .DFLTu
799: .
800: .It Sy RELEASEDIR
801: If set, specifies the directory to which a
802: .Xr release 7
803: layout will be written at the end of a
804: .Dq make release .
1.46 apb 805: If specified, must be an absolute path.
1.1 lukem 806: .DFLTu
1.17 lukem 807: .Pp
808: .Em Note :
809: .Sy build.sh
810: will provide a default of
811: .Pa releasedir
812: (in the top-level
813: .Sy .OBJDIR )
814: unless run in
815: .Sq expert
1.57 dholland 816: mode.
1.1 lukem 817: .
818: .El
819: .
820: .Sh BUILDING
821: .
822: .Ss \*qmake\*q command line options
1.37 jmc 823: This is not a summary of all the options available to
1.1 lukem 824: .Xr make 1 ;
825: only the options used most frequently with
826: .Nx
827: builds are listed here.
828: .
829: .Bl -tag -width "var=value"
830: .
1.4 lukem 831: .It Fl j Ar njob
1.1 lukem 832: Run up to
1.4 lukem 833: .Ar njob
1.1 lukem 834: .Xr make 1
835: subjobs in parallel.
1.37 jmc 836: Makefiles should use .WAIT or have explicit dependencies
1.1 lukem 837: as necessary to enforce build ordering.
838: .
1.4 lukem 839: .It Fl m Ar dir
1.1 lukem 840: Specify the default directory for searching for system Makefile
841: segments, mainly the
842: .Aq bsd.*.mk
1.6 wiz 843: files.
844: When building any full
1.1 lukem 845: .Nx
846: source tree, this should be set to the
847: .Dq share/mk
1.6 wiz 848: directory in the source tree.
1.57 dholland 849: This is set automatically when building from the top level, or when using
850: .Sy build.sh .
1.1 lukem 851: .
1.4 lukem 852: .It Fl n
1.1 lukem 853: Display the commands that would have been executed, but do not
1.6 wiz 854: actually execute them.
855: This will still cause recursion to take place.
1.1 lukem 856: .
1.32 zuntum 857: .It Fl V Ar var
1.1 lukem 858: Print
859: .Xr make 1 Ns 's
860: idea of the value of
1.4 lukem 861: .Ar var .
1.1 lukem 862: Does not build any targets.
863: .
864: .It Em var=value
865: Set the variable
866: .Em var
867: to
868: .Em value ,
869: overriding any setting specified by the process environment, the
870: .Sy MAKECONF
871: configuration file, or the system Makefile segments.
872: .
873: .El
874: .
875: .Ss \*qmake\*q targets
876: .
877: These default targets may be built by running
878: .Xr make 1
879: in any subtree of the
880: .Nx
1.6 wiz 881: source code.
882: It is recommended that none of these be used from the top
1.1 lukem 883: level Makefile; as a specific exception,
884: .Dq make obj
885: and
886: .Dq make cleandir
887: are useful in that context.
888: .
889: .Bl -tag -width "dependall"
890: .
891: .It Sy all
892: Build programs, libraries, and preformatted documentation.
893: .
894: .It Sy clean
895: Remove program and library object code files.
896: .
897: .It Sy cleandir
898: Same as
899: .Sy clean ,
900: but also remove preformatted documentation, dependency files generated
901: by
902: .Dq make depend ,
903: and any other files known to be created at build time.
904: .
905: .It Sy depend
906: Create dependency files
907: .Sy ( .depend )
908: containing more detailed information about the dependencies of source
1.6 wiz 909: code on header files.
910: Allows programs to be recompiled automatically when a dependency changes.
1.1 lukem 911: .
912: .It Sy dependall
913: Does a
914: .Dq make depend
915: immediately followed by a
916: .Dq make all .
917: This improves cache locality of the build since both passes read the source
918: files in their entirety.
919: .
1.34 lukem 920: .It Sy distclean
921: Synonym for
922: .Sy cleandir .
923: .
1.1 lukem 924: .It Sy includes
1.6 wiz 925: Build and install system header files.
926: Typically needed before any system libraries or programs can be built.
1.1 lukem 927: .
928: .It Sy install
929: Install programs, libraries, and documentation into
930: .Sy DESTDIR .
931: Few files will be installed to
1.14 lukem 932: .Sy DESTDIR Ns Pa /dev ,
933: .Sy DESTDIR Ns Pa /etc ,
934: .Sy DESTDIR Ns Pa /root
1.1 lukem 935: or
1.14 lukem 936: .Sy DESTDIR Ns Pa /var
1.1 lukem 937: in order to prevent user supplied configuration data from being overwritten.
938: .It Sy lint
939: Run
940: .Xr lint 1
941: against the C source code, where appropriate, and generate
942: system-installed lint libraries.
943: .
944: .It Sy obj
945: Create object directories to be used for built files, instead of
946: building directly in the source tree.
947: .
948: .It Sy tags
949: Create
950: .Xr ctags 1
951: searchable function lists usable by the
952: .Xr ex 1
953: and
954: .Xr vi 1
955: text editors.
956: .
957: .El
958: .
959: .Ss \*qmake\*q targets for the top level
960: .
961: Additional
962: .Xr make 1
963: targets are usable specifically from the top source level to facilitate
964: building the entire
965: .Nx
966: source tree.
967: .
1.7 lukem 968: .Bl -tag -width "distribution"
1.1 lukem 969: .
970: .It Sy build
971: Build the entire
972: .Nx
1.55 reed 973: system (except the kernel).
1.6 wiz 974: This orders portions of the source tree such that prerequisites
1.1 lukem 975: will be built in the proper order.
976: .
1.7 lukem 977: .It Sy distribution
978: Do a
979: .Dq make build ,
1.55 reed 980: and then install a full distribution (which does not include a kernel) into
1.9 lukem 981: .Sy DESTDIR ,
982: including files in
1.14 lukem 983: .Sy DESTDIR Ns Pa /dev ,
984: .Sy DESTDIR Ns Pa /etc ,
985: .Sy DESTDIR Ns Pa /root
1.9 lukem 986: and
1.14 lukem 987: .Sy DESTDIR Ns Pa /var .
1.7 lukem 988: .
989: .It Sy buildworld
990: As per
991: .Dq make distribution ,
992: except that it ensures that
993: .Sy DESTDIR
994: is not the root directory.
995: .
996: .It Sy installworld
997: Install the distribution from
998: .Sy DESTDIR
999: to
1.57 dholland 1000: .Sy INSTALLWORLDDIR ,
1001: which defaults to the root directory.
1.7 lukem 1002: Ensures that
1003: .Sy INSTALLWORLDDIR
1.37 jmc 1004: is not the root directory if cross compiling.
1.7 lukem 1005: .Pp
1.48 apb 1006: The
1007: .Sy INSTALLSETS
1.83 apb 1008: environment variable may be set to a space-separated list of
1.48 apb 1009: distribution sets to be installed.
1010: By default, all sets except
1011: .Dq etc
1012: and
1013: .Dq xetc
1.57 dholland 1014: are installed, so most files in
1.48 apb 1015: .Sy INSTALLWORLDDIR Ns Pa /etc
1.57 dholland 1016: will not be installed or modified.
1.48 apb 1017: .Pp
1.7 lukem 1018: .Em Note :
1.48 apb 1019: Before performing this operation with
1020: .Sy INSTALLWORLDDIR Ns = Ns Pa / ,
1021: it is highly recommended that you upgrade your kernel and reboot.
1022: After performing this operation,
1023: it is recommended that you use
1024: .Xr etcupdate 8
1025: to update files in
1026: .Sy INSTALLWORLDDIR Ns Pa /etc
1027: and that you use
1028: .Xr postinstall 8
1029: to check for inconsistencies (and possibly to fix them).
1.12 lukem 1030: .It Sy sets
1031: Create distribution sets from
1032: .Sy DESTDIR
1033: into
1.56 lukem 1034: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/sets .
1.12 lukem 1035: Should be run after
1.57 dholland 1036: .Dq make distribution ,
1037: as
1.12 lukem 1038: .Dq make build
1.57 dholland 1039: alone does not install all of the required files.
1.12 lukem 1040: .
1.18 lukem 1041: .It Sy sourcesets
1042: Create source sets of the source tree into
1043: .Sy RELEASEDIR Ns Pa /source/sets .
1044: .
1.40 apb 1045: .It Sy syspkgs
1046: Create syspkgs from
1047: .Sy DESTDIR
1048: into
1.56 lukem 1049: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/syspkgs .
1.40 apb 1050: Should be run after
1.57 dholland 1051: .Dq make distribution ,
1052: as
1.40 apb 1053: .Dq make build
1.57 dholland 1054: alone does not install all of the required files.
1.40 apb 1055: .
1.1 lukem 1056: .It Sy release
1057: Do a
1.9 lukem 1058: .Dq make distribution ,
1.12 lukem 1059: build kernels, distribution media, and install sets
1060: (this as per
1061: .Dq make sets ) ,
1062: and
1.1 lukem 1063: then package the system into a standard release layout as described by
1064: .Xr release 7 .
1065: This requires that
1066: .Sy RELEASEDIR
1067: be set (see above).
1068: .
1.57 dholland 1069: .It Sy iso-image
1.49 apb 1070: Create a
1071: .Nx
1072: installation CD-ROM image in the
1073: .Sy RELEASEDIR Ns Pa /iso
1074: directory.
1075: The CD-ROM file system will have a layout as described in
1076: .Xr release 7 .
1077: .Pp
1078: For most machine types, the CD-ROM will be bootable, and will automatically
1079: run the
1080: .Xr sysinst 8
1081: menu-based installation program, which can be used to install or upgrade a
1082: .Nx
1083: system.
1084: Bootable CD-ROMs also contain tools that may be useful in
1085: repairing a damaged
1086: .Nx
1087: installation.
1088: .Pp
1089: Before
1090: .Dq make iso-image
1091: is attempted, RELEASEDIR must be populated by
1.42 apb 1092: .Dq make release
1093: or equivalent.
1.49 apb 1094: .Pp
1095: Note that other, smaller, CD-ROM images may be created in the
1.56 lukem 1096: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1.49 apb 1097: directory by
1098: .Dq "make release" .
1099: These smaller images usually contain the same tools as the larger images in
1100: .Sy RELEASEDIR Ns Pa /iso ,
1101: but do not contain additional content such as the distribution sets.
1102: .Pp
1103: Note that the mac68k port still uses an older method of creating
1104: CD-ROM images.
1.42 apb 1105: This requires the
1106: .Xr mkisofs 1
1107: utility, which is not part of
1108: .Nx ,
1109: but which can be installed from
1.43 apb 1110: .Pa pkgsrc/sysutils/cdrtools .
1.42 apb 1111: .
1.63 lukem 1112: .It Sy iso-image-source
1.51 jnemeth 1113: Create a
1114: .Nx
1115: installation CD-ROM image in the
1116: .Sy RELEASEDIR Ns Pa /iso
1117: directory.
1118: The CD-ROM file system will have a layout as described in
1119: .Xr release 7 .
1120: It will have top level directories for the machine type and source.
1121: .Pp
1122: For most machine types, the CD-ROM will be bootable, and will automatically
1123: run the
1124: .Xr sysinst 8
1125: menu-based installation program, which can be used to install or upgrade a
1126: .Nx
1127: system.
1128: Bootable CD-ROMs also contain tools that may be useful in
1129: repairing a damaged
1130: .Nx
1131: installation.
1132: .Pp
1133: Before
1134: .Dq make iso-image-source
1135: is attempted, RELEASEDIR must be populated by
1136: .Dq make sourcesets release
1137: or equivalent.
1138: .Pp
1139: Note that other, smaller, CD-ROM images may be created in the
1.56 lukem 1140: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/cdrom
1.51 jnemeth 1141: directory by
1142: .Dq make release .
1143: These smaller images usually contain the same tools as the larger images in
1144: .Sy RELEASEDIR Ns Pa /iso ,
1145: but do not contain additional content such as the distribution sets.
1146: .Pp
1147: Note that the mac68k port still uses an older method of creating
1148: CD-ROM images.
1149: This requires the
1150: .Xr mkisofs 1
1151: utility, which is not part of
1152: .Nx ,
1153: but which can be installed from
1154: .Pa pkgsrc/sysutils/cdrtools .
1155: .
1.86 apb 1156: .It Sy install-image
1157: Create a bootable
1158: .Nx
1159: installation disk image in the
1160: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/installimage
1161: directory.
1.87 apb 1162: The installation disk image is suitable for copying to
1163: bootable USB flash memory sticks, etc., for machines which
1164: are able to boot from such devices.
1165: The file system in the bootable disk image will have a layout
1.86 apb 1166: as described in
1167: .Xr release 7 .
1168: .Pp
1169: The installation image is bootable, and will automatically
1170: run the
1171: .Xr sysinst 8
1172: menu-based installation program, which can be used to install or upgrade a
1173: .Nx
1174: system.
1.87 apb 1175: The image also contains tools that may be
1.86 apb 1176: useful in repairing a damaged
1177: .Nx
1178: installation.
1179: .Pp
1180: Before
1181: .Dq make install-image
1.87 apb 1182: is attempted,
1183: .Sy RELEASEDIR
1184: must be populated by
1.86 apb 1185: .Dq make release
1.87 apb 1186: or equivalent.
1187: The build must have been performed with
1188: .Sy MKUNPRIVED=yes
1189: because
1190: .Dq make install-image
1191: relies on information in
1192: .Sy DESTDIR Ns Pa /METALOG .
1.86 apb 1193: .
1194: .It live-image
1195: Create
1196: .Nx
1197: live images in the
1198: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /installation/liveimage
1199: directory.
1200: The live image contains all necessary files
1201: to boot
1202: .Nx
1.87 apb 1203: up to multi-user mode, including all files
1.86 apb 1204: which should be extracted during installation,
1205: .Nx
1.87 apb 1206: disklabel, bootloaders, etc.
1.86 apb 1207: .Pp
1.87 apb 1208: The live image is suitable for use as a disk image in
1209: virtual machine environments such as QEMU,
1210: and also useful to boot
1.86 apb 1211: .Nx
1.87 apb 1212: from a USB flash memory stick
1213: on a real machine, without the need for installation.
1.86 apb 1214: .Pp
1215: Before
1216: .Dq make live-image
1217: is attempted, RELEASEDIR must be populated by
1218: .Dq make release
1.87.2.1! riz 1219: or equivalent.
1.87 apb 1220: The build must have been performed with
1221: .Sy MKUNPRIVED=yes
1222: because
1223: .Dq make install-image
1224: relies on information in
1225: .Sy DESTDIR Ns Pa /METALOG .
1.86 apb 1226: .
1.1 lukem 1227: .It Sy regression-tests
1228: Can only be run after building the regression tests in the directory
1229: .Dq regress .
1.57 dholland 1230: Runs those compiled regression tests on the local host.
1231: Note that most tests are now managed instead using
1232: .Xr atf 7 ;
1233: this target should probably run those as well but currently does not.
1.1 lukem 1234: .
1235: .El
1236: .
1237: .Ss The \*qbuild.sh\*q script
1238: .
1.85 apb 1239: This script file is a shell script designed to build the
1.1 lukem 1240: entire
1241: .Nx
1.85 apb 1242: system on any host with a suitable modern shell and some common
1243: utilities.
1244: The required shell features are described under the
1245: .Sy HOST_SH
1246: variable.
1247: .Pp
1248: If a host system's default shell does support the required
1249: features, then we suggest that you explicitly specify
1250: a suitable shell using a command like
1251: .Bd -unfilled -offset indent
1252: .Li /path/to/suitable/shell build.sh Op Ar options
1253: .Ed
1254: .Pp
1255: The above command will usually enable
1256: .Nm build.sh
1257: to automatically set
1258: .Sy HOST_SH Ns Cm = Ns Pa /path/to/suitable/shell ,
1259: but if that fails, then the following set of commands may be used instead:
1260: .Bd -unfilled -offset indent
1261: .Li HOST_SH= Ns Va /path/to/suitable/shell
1262: .Li export HOST_SH
1263: .Li ${HOST_SH} build.sh Op Ar options
1264: .Ed
1265: .Pp
1266: If
1267: .Sy build.sh
1268: detects that it is being executed under an unsuitable shell, it attempts
1269: to exec a suitable shell instead, or prints an error message.
1270: If
1271: .Sy HOST_SH
1272: is not set explicitly, then
1273: .Nm build.sh
1274: sets a default using heuristics dependent on the host platform,
1275: or from the shell under which
1276: .Nm build.sh
1277: is executed (if that can be determined),
1278: or using the first copy of
1279: .Pa sh
1280: found in
1281: .Sy PATH .
1.1 lukem 1282: .Pp
1283: All cross-compile builds, and most native builds, of the entire system
1284: should make use of
1285: .Sy build.sh
1286: rather than just running
1287: .Dq make .
1288: This way, the
1289: .Xr make 1
1290: program will be bootstrapped properly, in case the host system has an
1291: older or incompatible
1292: .Dq make
1293: program.
1294: .Pp
1295: When compiling the entire system via
1296: .Sy build.sh ,
1297: many
1298: .Xr make 1
1299: variables are set for you in order to help encapsulate the build
1.6 wiz 1300: process.
1301: In the list of options below, variables that are automatically set by
1.1 lukem 1302: .Sy build.sh
1303: are noted where applicable.
1.9 lukem 1304: .
1.1 lukem 1305: .Pp
1.9 lukem 1306: The following operations are supported by
1.1 lukem 1307: .Sy build.sh :
1308: .
1.9 lukem 1309: .Bl -tag -width "distribution"
1310: .
1311: .It Sy build
1312: Build the system as per
1313: .Dq make build .
1.57 dholland 1314: Before the main part of the build commences, this command runs the
1.9 lukem 1315: .Sy obj
1.57 dholland 1316: operation (unless the
1317: .Fl o
1318: option is given),
1319: .Dq make cleandir
1320: (unless the
1321: .Fl u
1322: option is given),
1323: and the
1.9 lukem 1324: .Sy tools
1.57 dholland 1325: operation.
1.9 lukem 1326: .
1327: .It Sy distribution
1328: Build a full distribution as per
1329: .Dq make distribution .
1.57 dholland 1330: This command first runs the
1.9 lukem 1331: .Sy build
1332: operation.
1333: .
1334: .It Sy release
1335: Build a full release as per
1336: .Dq make release .
1.57 dholland 1337: This command first runs the
1.9 lukem 1338: .Sy distribution
1339: operation.
1340: .
1.10 lukem 1341: .It Sy makewrapper
1342: Create the
1.13 lukem 1343: .Sy \*[toolprefix]make-MACHINE
1.10 lukem 1344: wrapper.
1345: This operation is automatically performed for any of the other
1346: operations.
1347: .
1.63 lukem 1348: .It Sy cleandir
1349: Perform
1350: .Dq make cleandir .
1351: .
1.9 lukem 1352: .It Sy obj
1353: Perform
1354: .Dq make obj .
1.11 lukem 1355: .
1.9 lukem 1356: .It Sy tools
1357: Build and install the host tools from
1358: .Pa src/tools .
1.57 dholland 1359: This command will first run
1360: .Dq make obj
1361: and
1362: .Dq make cleandir
1363: in the
1364: .Pa tools
1365: subdirectory unless the
1366: .Fl o
1367: or
1368: .Fl u
1369: options (respectively) are given.
1.22 lukem 1370: .
1371: .It Sy install Ns = Ns Ar idir
1372: Install the contents of
1373: .Sy DESTDIR
1374: to
1375: .Ar idir ,
1376: using
1377: .Dq make installworld .
1.48 apb 1378: Note that files that are part of the
1379: .Dq etc
1380: or
1381: .Dq xetc
1.83 apb 1382: sets will not be installed, unless overridden by
1383: the INSTALLSETS environment variable.
1.22 lukem 1384: .
1.9 lukem 1385: .It Sy kernel Ns = Ns Ar kconf
1386: Build a new kernel.
1387: The
1388: .Ar kconf
1389: argument is the name of a configuration file suitable
1390: for use by
1.39 peter 1391: .Xr config 1 .
1.9 lukem 1392: If
1393: .Ar kconf
1394: does not contain any
1395: .Sq /
1396: characters, the configuration file is expected to be found in the
1397: .Sy KERNCONFDIR
1398: directory, which is typically
1399: .Sy sys/arch/MACHINE/conf .
1400: The new kernel will be built in a subdirectory of
1401: .Sy KERNOBJDIR ,
1402: which is typically
1403: .Sy sys/arch/MACHINE/compile
1404: or an associated object directory.
1.57 dholland 1405: .Pp
1406: This command does
1407: .Em not
1408: imply the
1409: .Sy tools
1410: command; run the
1.9 lukem 1411: .Sy tools
1.57 dholland 1412: command first unless it is
1413: .Em certain
1414: that the tools already exist and are up to date.
1415: .Pp
1416: This command will run
1417: .Dq make cleandir
1418: on the kernel in question first unless the
1419: .Fl u
1420: option is given.
1.9 lukem 1421: .
1.75 apb 1422: .It Sy modules
1423: This command will build kernel modules and install them into
1424: .Sy DESTDIR .
1425: .
1.22 lukem 1426: .It Sy releasekernel Ns = Ns Ar kconf
1427: Install a
1428: .Xr gzip 1 Ns ed
1.57 dholland 1429: copy of the kernel previously built by
1.22 lukem 1430: .Sy kernel Ns = Ns Ar kconf
1431: into
1.56 lukem 1432: .Sy RELEASEDIR/RELEASEMACHINEDIR Ns Pa /binary/kernel ,
1.22 lukem 1433: usually as
1434: .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
1435: although the
1436: .Dq Pa netbsd
1437: prefix is determined from the
1438: .Dq Sy config
1439: directives in
1440: .Ar kconf .
1.9 lukem 1441: .
1.11 lukem 1442: .It Sy sets
1443: Perform
1444: .Dq make sets .
1.18 lukem 1445: .
1446: .It Sy sourcesets
1447: Perform
1448: .Dq make sourcesets .
1449: .
1.40 apb 1450: .It Sy syspkgs
1451: Perform
1452: .Dq make syspkgs .
1453: .
1.42 apb 1454: .It Sy iso-image
1455: Perform
1456: .Dq make iso-image .
1457: .
1.52 jnemeth 1458: .It Sy iso-image-source
1459: Perform
1460: .Dq make iso-image-source .
1461: .
1.86 apb 1462: .It Sy install-image
1463: Perform
1464: .Dq make install-image .
1465: .
1466: .It Sy live-image
1467: Perform
1468: .Dq make live-image .
1469: .
1.9 lukem 1470: .El
1471: .
1472: .Pp
1473: The following command line options alter the behaviour of the
1474: .Sy build.sh
1475: operations described above:
1476: .
1.1 lukem 1477: .Bl -tag -width "-T tools"
1478: .
1.4 lukem 1479: .It Fl a Ar arch
1.1 lukem 1480: Set the value of
1481: .Sy MACHINE_ARCH
1482: to
1.4 lukem 1483: .Ar arch .
1.1 lukem 1484: .
1.4 lukem 1485: .It Fl B Ar buildid
1.1 lukem 1486: Set the value of
1487: .Sy BUILDID
1488: to
1.4 lukem 1489: .Ar buildid .
1.54 sborrill 1490: This will also append the build identifier to the name of the
1.1 lukem 1491: .Dq make
1492: wrapper script so that the resulting name is of the form
1.13 lukem 1493: .Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1.1 lukem 1494: .
1.54 sborrill 1495: .It Fl C Ar cdextras
1.76 apb 1496: Append
1497: .Ar cdextras
1498: to the
1.53 jnemeth 1499: .Sy CDEXTRA
1.76 apb 1500: variable,
1501: which is a space-separated list of files or directories that will be
1502: added to the CD-ROM image that may be create by the
1.53 jnemeth 1503: .Dq iso-image
1504: or
1.76 apb 1505: .Dq iso-image-source
1506: operations.
1.54 sborrill 1507: Files will be added to the root of the CD-ROM image, whereas directories
1508: will be copied recursively.
1509: If relative paths are specified, they will be converted to
1510: absolute paths before being used.
1.76 apb 1511: Multiple paths may be specified via multiple
1512: .Fl C
1513: options, or via a single option whose argument contains multiple
1514: space-separated paths.
1.53 jnemeth 1515: .
1.4 lukem 1516: .It Fl D Ar dest
1517: Set the value of
1518: .Sy DESTDIR
1519: to
1520: .Ar dest .
1.46 apb 1521: If a relative path is specified, it will be converted to an
1522: absolute path before being used.
1.4 lukem 1523: .
1.5 lukem 1524: .It Fl E
1525: Set
1526: .Sq expert
1.10 lukem 1527: mode.
1528: This overrides various sanity checks, and allows:
1.5 lukem 1529: .Sy DESTDIR
1.10 lukem 1530: does not have to be set to a non-root path for builds,
1531: and
1.25 lukem 1532: .Sy MKUNPRIVED=yes
1.10 lukem 1533: does not have to be set when building as a non-root user.
1534: .Pp
1535: .Em Note :
1536: It is highly recommended that you know what you are doing when
1537: you use this option.
1.7 lukem 1538: .
1.36 wiz 1539: .It Fl h
1540: Print a help message.
1541: .
1.4 lukem 1542: .It Fl j Ar njob
1.57 dholland 1543: Run up to
1544: .Ar njob
1545: .Xr make 1
1546: subjobs in parallel;
1547: passed through to
1.1 lukem 1548: .Xr make 1 .
1.62 apb 1549: If you see failures for reasons other than running out of memory
1550: while using
1551: .Sy build.sh
1552: with
1553: .Fl j ,
1554: please save complete build logs
1.1 lukem 1555: so the failures can be analyzed.
1.62 apb 1556: .Pp
1557: To achieve the fastest builds,
1558: .Fl j
1559: values between (1 + the number of CPUs) and (2 * the number of CPUs)
1560: are recommended.
1561: Use lower values on machines with limited memory or I/O bandwidth.
1.1 lukem 1562: .
1.4 lukem 1563: .It Fl M Ar obj
1564: Set
1565: .Sy MAKEOBJDIRPREFIX
1566: to
1567: .Ar obj .
1.77 apb 1568: Unsets
1569: .Sy MAKEOBJDIR .
1570: See
1571: .Dq Fl O obj
1572: for more information.
1573: .Pp
1.61 apb 1574: For instance, if the source directory is
1575: .Pa /usr/src ,
1576: a setting of
1577: .Dq Fl M Pa /usr/obj
1578: will place build-time files under
1579: .Pa /usr/obj/usr/src/bin ,
1580: .Pa /usr/obj/usr/src/lib ,
1581: .Pa /usr/obj/usr/src/usr.bin ,
1582: and so forth.
1.77 apb 1583: .Pp
1.46 apb 1584: If a relative path is specified, it will be converted to an
1585: absolute path before being used.
1.77 apb 1586: .Sy build.sh
1587: imposes the restriction that the argument to the
1588: .Fl M
1589: option must not begin with a
1590: .Dq \&$
1591: (dollar sign)
1592: character; otherwise it would be too difficult
1593: to determine whether the value is an absolute or a relative path.
1594: If the directory does not already exist,
1595: .Sy build.sh
1596: will create it.
1.4 lukem 1597: .
1598: .It Fl m Ar mach
1.1 lukem 1599: Set the value of
1600: .Sy MACHINE
1601: to
1.47 apb 1602: .Ar mach ,
1603: except in some special cases listed below.
1.1 lukem 1604: This will also override any value of
1605: .Sy MACHINE_ARCH
1606: in the process environment with a value deduced from
1.4 lukem 1607: .Ar mach ,
1.1 lukem 1608: unless
1.4 lukem 1609: .Fl a
1.47 apb 1610: is specified.
1.6 wiz 1611: All cross builds require
1.4 lukem 1612: .Fl m ,
1.1 lukem 1613: but if unset on a NetBSD host, the host's value of MACHINE will be
1614: detected and used automatically.
1.20 lukem 1615: .Pp
1616: Some machines support multiple values for
1617: .Sy MACHINE_ARCH .
1.47 apb 1618: The following special cases for the
1619: .Ar mach
1620: argument are defined to set the listed values of
1.20 lukem 1621: .Sy MACHINE
1622: and
1.47 apb 1623: .Sy MACHINE_ARCH :
1.20 lukem 1624: .Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
1.24 lukem 1625: .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
1.47 apb 1626: .It evbarm Ta evbarm Ta (not set)
1627: .It evbarm-eb Ta evbarm Ta armeb
1628: .It evbarm-el Ta evbarm Ta arm
1.20 lukem 1629: .It evbmips Ta evbmips Ta (not set)
1630: .It evbmips-eb Ta evbmips Ta mipseb
1631: .It evbmips-el Ta evbmips Ta mipsel
1632: .It evbsh3 Ta evbsh3 Ta (not set)
1633: .It evbsh3-eb Ta evbsh3 Ta sh3eb
1634: .It evbsh3-el Ta evbsh3 Ta sh3el
1635: .It sbmips Ta sbmips Ta (not set)
1636: .It sbmips-eb Ta sbmips Ta mipseb
1637: .It sbmips-el Ta sbmips Ta mipsel
1.30 lukem 1638: .El
1639: .
1640: .It Fl N Ar noiselevel
1641: Set the
1642: .Dq noisyness
1.31 lukem 1643: level of the build, by setting
1644: .Sy MAKEVERBOSE
1645: to
1646: .Ar noiselevel .
1.1 lukem 1647: .
1.4 lukem 1648: .It Fl n
1.1 lukem 1649: Show the commands that would be executed by
1650: .Sy build.sh ,
1.6 wiz 1651: but do not make any changes.
1652: This is similar in concept to
1.1 lukem 1653: .Dq make -n .
1654: .
1.4 lukem 1655: .It Fl O Ar obj
1.1 lukem 1656: Create an appropriate transform macro for
1657: .Sy MAKEOBJDIR
1658: that will place the built object files under
1.4 lukem 1659: .Ar obj .
1.77 apb 1660: Unsets
1661: .Sy MAKEOBJDIRPREFIX .
1662: .Pp
1.1 lukem 1663: For instance, a setting of
1.61 apb 1664: .Dq Fl O Pa /usr/obj
1.1 lukem 1665: will place build-time files under
1.61 apb 1666: .Pa /usr/obj/bin ,
1667: .Pa /usr/obj/lib ,
1668: .Pa /usr/obj/usr.bin ,
1.1 lukem 1669: and so forth.
1.77 apb 1670: .Pp
1.61 apb 1671: If a relative path is specified, it will be converted to an
1672: absolute path before being used.
1.77 apb 1673: .Sy build.sh
1674: imposes the restriction that the argument to the
1675: .Fl O
1676: option must not contain a
1677: .Dq \&$
1678: (dollar sign)
1679: character.
1680: If the directory does not already exist,
1681: .Sy build.sh
1682: will create it.
1.61 apb 1683: .Pp
1684: In normal use, exactly one of the
1685: .Fl M
1686: or
1687: .Fl O
1688: options should be specified.
1.67 apb 1689: If neither
1.61 apb 1690: .Fl M
1691: nor
1692: .Fl O
1693: is specified, then a default object directory will be chosen
1694: according to rules in
1.67 apb 1695: .Aq bsd.obj.mk .
1696: Relying on this default is not recommended because
1697: it is determined by complex rules that are influenced
1698: by the values of several variables and
1699: by the location of the source directory.
1.4 lukem 1700: .It Fl o
1701: Set the value of
1702: .Sy MKOBJDIRS
1703: to
1704: .Dq no .
1.21 lukem 1705: Otherwise, it will be automatically set to
1.57 dholland 1706: .Dq yes .
1707: This default is opposite to the behaviour when not using
1708: .Sy build.sh .
1.4 lukem 1709: .
1710: .It Fl R Ar rel
1.1 lukem 1711: Set the value of
1712: .Sy RELEASEDIR
1713: to
1.4 lukem 1714: .Ar rel .
1.46 apb 1715: If a relative path is specified, it will be converted to an
1716: absolute path before being used.
1.1 lukem 1717: .
1.4 lukem 1718: .It Fl r
1719: Remove the contents of
1720: .Sy DESTDIR
1721: and
1722: .Sy TOOLDIR
1.6 wiz 1723: before building (provides a clean starting point).
1724: This will skip deleting
1.4 lukem 1725: .Sy DESTDIR
1726: if building on a native system to the root directory.
1727: .
1.60 perry 1728: .It Fl S Ar seed
1729: Change the value of
1730: .Sy BUILDSEED
1731: to
1732: .Ar seed .
1733: This should rarely be necessary.
1734: .
1.4 lukem 1735: .It Fl T Ar tools
1.1 lukem 1736: Set the value of
1737: .Sy TOOLDIR
1738: to
1.4 lukem 1739: .Ar tools .
1.46 apb 1740: If a relative path is specified, it will be converted to an
1741: absolute path before being used.
1.1 lukem 1742: If set, the bootstrap
1743: .Dq make
1.57 dholland 1744: will only be rebuilt if the source files for
1.1 lukem 1745: .Xr make 1
1.57 dholland 1746: have changed.
1.1 lukem 1747: .
1.4 lukem 1748: .It Fl U
1.25 lukem 1749: Set
1750: .Sy MKUNPRIVED=yes .
1.1 lukem 1751: .
1.4 lukem 1752: .It Fl u
1.25 lukem 1753: Set
1754: .Sy MKUPDATE=yes .
1.8 lukem 1755: .
1756: .It Xo
1757: .Fl V
1758: .Sm off
1759: .Ar var
1760: .Li =
1761: .Op Ar value
1762: .Sm on
1763: .Xc
1.27 lukem 1764: Set the environment variable
1.8 lukem 1765: .Ar var
1.27 lukem 1766: to an optional
1767: .Ar value .
1768: This is propagated to the
1769: .Sy \*[toolprefix]make
1770: wrapper.
1.4 lukem 1771: .
1772: .It Fl w Ar wrapper
1.27 lukem 1773: Create the
1774: .Sy \*[toolprefix]make
1775: wrapper script (see below) in a custom location,
1.4 lukem 1776: specified by
1777: .Ar wrapper .
1778: This allows, for instance, to place the wrapper in
1779: .Sy PATH
1.6 wiz 1780: automatically.
1781: Note that
1.4 lukem 1782: .Ar wrapper
1783: is the full name of the file, not just a directory name.
1.46 apb 1784: If a relative path is specified, it will be converted to an
1785: absolute path before being used.
1.4 lukem 1786: .
1.34 lukem 1787: .It Fl X Ar x11src
1788: Set the value of
1789: .Sy X11SRCDIR
1790: to
1791: .Ar x11src .
1.46 apb 1792: If a relative path is specified, it will be converted to an
1793: absolute path before being used.
1.34 lukem 1794: .
1795: .It Fl x
1796: Set
1797: .Sy MKX11=yes .
1798: .
1.27 lukem 1799: .It Fl Z Ar var
1800: Unset ("zap") the environment variable
1801: .Ar var .
1802: This is propagated to the
1803: .Sy \*[toolprefix]make
1804: wrapper.
1805: .
1.1 lukem 1806: .El
1807: .
1.13 lukem 1808: .Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
1.1 lukem 1809: .
1810: If using the
1811: .Sy build.sh
1812: script to build
1813: .Nx ,
1814: a
1.13 lukem 1815: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1816: script will be created in
1817: .Sy TOOLDIR/bin
1818: upon the first build to assist in building subtrees on a cross-compile
1819: host.
1820: .Pp
1.13 lukem 1821: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1822: can be invoked in lieu of
1823: .Xr make 1 ,
1824: and will instead call the up-to-date version of
1.13 lukem 1825: .Dq \*[toolprefix]make
1.1 lukem 1826: installed into
1827: .Sy TOOLDIR/bin
1828: with several key variables pre-set, including
1829: .Sy MACHINE , MACHINE_ARCH ,
1830: and
1831: .Sy TOOLDIR .
1.57 dholland 1832: .Sy \*[toolprefix]make-MACHINE
1.27 lukem 1833: will also set variables specified with
1834: .Fl V ,
1835: and unset variables specified with
1836: .Fl Z .
1837: .Pp
1.1 lukem 1838: This script can be symlinked into a directory listed in
1839: .Sy PATH ,
1840: or called with an absolute path.
1.2 lukem 1841: .
1842: .Sh EXAMPLES
1.10 lukem 1843: .
1.15 lukem 1844: .Bl -enum
1.9 lukem 1845: .
1.15 lukem 1846: .It
1.67 apb 1847: .Li "% ./build.sh [options] tools kernel=GENERIC"
1.15 lukem 1848: .Pp
1.2 lukem 1849: Build a new toolchain, and use the new toolchain to
1850: configure and build a new GENERIC kernel.
1.9 lukem 1851: .
1.15 lukem 1852: .It
1.67 apb 1853: .Li "% ./build.sh [options] -U distribution"
1.15 lukem 1854: .Pp
1.2 lukem 1855: Using unprivileged mode,
1.17 lukem 1856: build a complete distribution to a
1857: .Sy DESTDIR
1858: directory that
1859: .Sy build.sh
1860: selects (and will display).
1.9 lukem 1861: .
1.15 lukem 1862: .It
1.67 apb 1863: .Li "# ./build.sh [options] -U install=/"
1.15 lukem 1864: .Pp
1.16 lukem 1865: As root, install to
1866: .Pa /
1867: the distribution that was built
1868: by example 2.
1.15 lukem 1869: Even though this is run as root,
1.9 lukem 1870: .Fl U
1871: is required so that the permissions stored in
1.17 lukem 1872: .Sy DESTDIR Ns Pa /METALOG
1.9 lukem 1873: are correctly applied to the files as they're copied to
1.15 lukem 1874: .Pa / .
1.9 lukem 1875: .
1.15 lukem 1876: .It
1.67 apb 1877: .Li "% ./build.sh [options] -U -u release"
1.15 lukem 1878: .Pp
1.2 lukem 1879: Using unprivileged mode,
1.17 lukem 1880: build a complete release to
1881: .Sy DESTDIR
1882: and
1883: .Sy RELEASEDIR
1884: directories that
1885: .Sy build.sh
1886: selects (and will display).
1.25 lukem 1887: .Sy MKUPDATE=yes
1.15 lukem 1888: .Pq Fl u
1889: is set to prevent the
1890: .Dq make cleandir ,
1891: so that if this is run after example 2, it doesn't need to redo that
1892: portion of the release build.
1.2 lukem 1893: .El
1.1 lukem 1894: .
1895: .Sh OBSOLETE VARIABLES
1896: .
1897: .Bl -tag -width "NBUILDJOBS"
1898: .
1899: .It Sy NBUILDJOBS
1900: Use the
1901: .Xr make 1
1902: option
1.57 dholland 1903: .Fl j
1.1 lukem 1904: instead.
1905: .
1906: .It Sy USE_NEW_TOOLCHAIN
1907: The new toolchain is now the default.
1908: To disable, use
1909: .Sy TOOLCHAIN_MISSING=yes .
1910: .El
1911: .Sh SEE ALSO
1912: .Xr make 1 ,
1913: .Xr hier 7 ,
1.42 apb 1914: .Xr release 7 ,
1.48 apb 1915: .Xr etcupdate 8 ,
1916: .Xr postinstall 8 ,
1.49 apb 1917: .Xr sysinst 8 ,
1.43 apb 1918: .Pa pkgsrc/sysutils/cdrtools
1.1 lukem 1919: .
1920: .Sh HISTORY
1921: .
1922: The
1923: .Nm build.sh
1924: based build scheme was introduced for
1925: .Nx 1.6
1926: as
1927: .Sy USE_NEW_TOOLCHAIN ,
1928: and re-worked to
1929: .Sy TOOLCHAIN_MISSING
1930: 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