Annotation of src/doc/BUILDING.mdoc, Revision 1.4
1.4 ! lukem 1: .\" $NetBSD: BUILDING.mdoc,v 1.3 2002/11/25 19:18:45 wiz Exp $
1.1 lukem 2: .\"
3: .\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Todd Vierling.
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: .\" 3. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the NetBSD
20: .\" Foundation, Inc. and its contributors.
21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22: .\" contributors may be used to endorse or promote products derived
23: .\" from this software without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35: .\" POSSIBILITY OF SUCH DAMAGE.
36: .\"
37: .\" =====
38: .\" NOTE: After changing this file, run "make build-docs" to generate the
39: .\" proper plaintext versions, and check in all BUILDING.* files!
40: .\"
1.4 ! lukem 41: .Dd December 8, 2002
1.1 lukem 42: .Dt BUILDING 8
43: .Os NetBSD
44: .
45: .Sh NAME
46: .
47: .Nm BUILDING
48: .Nd Procedure for building
49: .Nx
50: from source code.
51: .
52: .Sh STATUS
53: .
54: This document is a work-in-progress. As such, the information described
55: here may not match the reality of the build system as of this writing.
56: Once this document is completely in sync with reality, this paragraph
57: will be removed.
58: .Pp
59: Discrepancies between this documentation and the current reality of
60: implementation are noted specially, as with the note below:
61: .Pp
62: .Em Note :
63: This document applies only to platforms which use the new toolchain as
64: indicated by the default setting of
65: .Sy TOOLCHAIN_MISSING
66: in
67: .Aq bsd.own.mk .
68: Platforms which have not yet been switched to the new toolchain should
69: continue building traditionally, using the notes specified in the file
70: .Sy UPDATING .
71: .
72: .Sh REQUIREMENTS
73: .
74: .Nx
75: is designed to be buildable on most POSIX-compliant host systems.
76: The basic build procedure is the same whether compiling
77: .Em natively
78: (on the same
79: .Nx
80: architecture) or
81: .Em cross compiling
82: (on another architecture or OS).
83: .Pp
84: This source tree contains a special subtree,
85: .Dq tools ,
86: which uses the host system to create a build toolchain for the target
87: architecture. The host system must have at least C and C++
88: compilers in order to create the toolchain
89: .Nm ( make
90: is not required); all other tools are created as part of the
91: .Nx
92: build process.
93: .Pp
94: .Bd -ragged -offset indent
95: .Em Note :
96: A couple host toolchain components are not yet available in the tools
97: directory. Also, some tools use non-POSIX, non-ANSI C extensions
98: and need to be standardized. As a result, cross-compiling from
99: systems other than
100: .Nx
101: is not currently supported.
102: .Ed
103: .
104: .Sh FILES
105: .
106: .Ss Source tree layout
107: .
108: .Bl -tag -width "BUILDING.mdoc"
1.3 wiz 109: .It Sy doc/BUILDING.mdoc
1.1 lukem 110: This document (in -mdoc troff format; the original copy).
111: .It Sy BUILDING
112: This document (in plaintext).
113: .It Sy Makefile
114: The main Makefile for
115: .Nx ;
116: should only be run for native builds with an appropriately up-to-date
117: version of
118: .Nx
119: .Xr make 1 .
120: (For building from out-of-date systems or on a non-native host, see the
121: .Nm build.sh
122: shell script.)
123: .It Sy UPDATING
124: Special notes for updating from an earlier revision of
125: .Nx .
126: It is important to read this file before every build of an updated
127: source tree.
128: .It Sy build.sh
129: Bourne-compatible shell script used for building the host build tools
130: and the
131: .Nx
132: system from scratch. Can be used for both native and cross builds, and
133: should be used instead of
134: .Xr make 1
135: for any source tree that is updated and recompiled regularly.
136: .It Sy crypto/dist/ , dist/ , gnu/dist/
137: Sources imported verbatim from third parties, without mangling the
138: existing build structure. Other source trees in
139: .Sy bin
140: through
141: .Sy usr.sbin
142: use the
143: .Nx
144: .Xr make 1
145: .Dq reachover
146: Makefile semantics when building these programs for a native host.
147: .It Sy distrib/ , etc/
148: Sources for items used when making a full release snapshot, such as
149: files installed in
150: .Sy /etc
151: on the destination system, boot media, and release notes.
152: .It Sy regress/
153: Regression test harness. Can be cross-compiled, but only run natively.
154: .It Sy sys/
155: .Nx
156: kernel sources.
157: .It Sy tools/
158: .Dq Reachover
159: build structure for the host build tools. This has a special method of
160: determining out-of-date status.
161: .It Sy bin/ ... usr.sbin/
162: Sources to the
163: .Nx
164: userland (non-kernel) programs. If any of these directories are
165: missing, they will be skipped during the build.
166: .El
167: .
168: .Ss Build tree layout
169: .
170: The
171: .Nx
172: build tree is described in
173: .Xr hier 7 ,
174: and the release layout is described in
175: .Xr release 7 .
176: .Pp
177: .
178: .Sh CONFIGURATION
179: .
180: .Ss Environment variables
181: ..
182: Several environment variables control the behaviour of
183: .Nx
184: builds.
185: .
186: .Bl -tag -width "MAKEOBJDIRPREFIX"
187: .
188: .It Sy MACHINE
189: Machine type.
190: .
191: .It Sy MACHINE_ARCH
192: Machine architecture.
193: .
194: .It Sy MAKE
195: Path name to invoke
196: .Xr make 1
197: as.
198: .
199: .It Sy MAKEFLAGS
200: Flags to invoke
201: .Xr make 1
202: with.
203: .
204: .It Sy MAKEOBJDIR
205: Directory to use as the
206: .Sy .OBJDIR
207: for the current directory.
208: Used only if
209: .Sy MAKEOBJDIRPREFIX
210: is not defined.
211: .Sy MAKEOBJDIR
212: can only be provided in the environment.
213: .
214: .It Sy MAKEOBJDIRPREFIX
215: Top level directory of the object directory tree.
216: If this is defined,
217: ${MAKEOBJDIRPREFIX}/${.CURDIR}
218: is used as the
219: .Sy .OBJDIR
220: for the current directory.
221: The current directory may be read only.
222: .Sy MAKEOBJDIRPREFIX
223: can only be provided in the environment.
224: .
225: .El
226: .
227: .Ss \*qmake\*q variables
228: .
229: .de YorN
230: Can be set to
231: .Dq yes
232: or
233: .Dq no .
234: ..
235: .de DFLT
236: .Pp
237: .Em Default :
238: ..
239: .de DFLTu
240: .DFLT
241: Unset.
242: ..
243: .de DFLTy
244: .DFLT
245: .Dq yes
246: ..
247: .de DFLTn
248: .DFLT
249: .Dq no
250: ..
251: Several variables control the behavior of
252: .Nx
253: builds. Unless otherwise specified, these variables may be set in
254: either the process environment or the
255: .Xr make 1
256: configuration file specified by
257: .Sy MAKECONF .
258: .
259: .Bl -tag -width "MKCATPAGES"
260: .
261: .It Sy BUILDID
262: Identifier for the build. The identifier will be appended to
263: object directory names, and can be consulted in the
264: .Xr make 1
265: configuration file in order to set additional build parameters,
266: such as compiler flags.
267: .
268: .It Sy DESTDIR
269: Directory to contain the built
270: .Nx
271: system. If set, special options are passed to the compilation tools to
272: prevent their default use of the host system's
273: .Sy /usr/include , /usr/lib ,
274: and so forth. This pathname should
275: .Em not
276: end with a slash
277: .Pq /
278: character (for installation into the system's root directory, set
279: .Sy DESTDIR
280: to an empty string).
281: The directory must reside on a file system which supports long file
282: names and hard links.
283: .DFLT
284: Empty string if
285: .Sy USETOOLS
286: is
287: .Dq yes ;
288: unset otherwise.
289: .
290: .It Sy MAKECONF
291: The name of the
292: .Xr make 1
293: configuration file.
294: .Em Only settable in the process environment.
295: .DFLT
296: .Dq /etc/mk.conf
297: .
298: .It Sy MKCATPAGES
299: .YorN
300: Indicates whether preformatted plaintext manual pages will be created
301: during a build.
302: .DFLTy
303: .
304: .It Sy MKCRYPTO
305: .YorN
306: Indicates whether cryptographic code will be included in a build;
307: provided for the benefit of countries that do not allow strong
308: cryptography. Will not affect use of the standard low-security password
309: encryption system,
310: .Xr crypt 3 .
311: .DFLTy
312: .
313: .It Sy MKDOC
314: .YorN
315: Indicates whether system documentation destined for
316: .Sy /usr/share/doc
317: will be installed during a build.
318: .DFLTy
319: .
320: .It Sy MKHOSTOBJ
321: .YorN
322: If set to
323: .Dq yes ,
324: then for programs intended to be run on the compile host,
325: the name, release, and architecture of the host operating system
326: will be suffixed to the name of the object directory created by
327: .Dq make obj .
328: (This allows multiple host systems to compile NetBSD for a single target.)
329: If set to
330: .Dq no ,
331: then programs built to be run on the compile host will use the same
332: object directory names as programs built to be run on the target.
333: .DFLTn
334: .
335: .It Sy MKINFO
336: .YorN
337: Indicates whether GNU Info files, used for the documentation for
338: most of the compilation tools, will be created and installed during a
339: build.
340: .DFLTy
341: .
342: .It Sy MKLINT
343: .YorN
344: Indicates whether
345: .Xr lint 1
346: will be run against portions of the
347: .Nx
348: source code during the build, and whether lint libraries will be
349: installed into
350: .Sy /usr/libdata/lint .
351: .DFLTy
352: .
353: .It Sy MKMAN
354: .YorN
355: Indicates whether manual pages will be installed during a build.
356: .DFLTy
357: .
358: .It Sy MKNLS
359: .YorN
360: Indicates whether Native Language System locale zone files will be
361: compiled and installed during a build.
362: .DFLTy
363: .
364: .It Sy MKOBJ
365: .YorN
366: Indicates whether object directories will be created when running
367: .Dq make obj .
368: If set to
369: .Dq no ,
370: then all built files will be located inside the regular source tree.
371: .DFLTy
372: .
373: .It Sy MKPIC
374: .YorN
375: Indicates whether shared objects and libraries will be created and
376: installed during a build. If set to
377: .Dq no ,
378: the entire built system will be statically linked.
379: .DFLT
380: Platform dependent. As of this writing, all platforms except
381: .Sy sh3
382: default to
383: .Dq yes .
384: .
385: .It Sy MKPICINSTALL
386: .YorN
387: Indicates whether the
388: .Xr ar 1
389: format libraries
390: .Sy ( lib*_pic.a ) ,
391: used to generate shared libraries, are installed during a build.
392: .DFLTy
393: .
394: .It Sy MKPROFILE
395: .YorN
396: Indicates whether profiled libraries
397: .Sy ( lib*_p.a )
398: will be built and installed during a build.
399: .DFLT
400: .Dq yes ;
401: however, some platforms turn off
402: .Sy MKPROFILE
403: by default at times due to toolchain problems with profiled code.
404: .
405: .It Sy MKSHARE
406: .YorN
407: Indicates whether files destined to reside in
408: .Sy /usr/share
409: will be built and installed during a build. If set to
410: .Dq no ,
411: then all of
412: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
413: and
414: .Sy MKNLS
415: will be set to
416: .Dq no
417: unconditionally.
418: .DFLTy
419: .
420: .It Sy TOOLDIR
421: Directory to hold the host tools, once built. This directory should be
422: unique to a given host system and
423: .Nx
424: source tree. (However, multiple targets may share the same
425: .Sy TOOLDIR ;
426: the target-dependent files have unique names.) If unset, a default based
427: on the
428: .Xr uname 1
429: information of the host platform will be created in the
430: .Sy .OBJDIR
431: of
432: .Sy src/tools .
433: .DFLTu
434: .
435: .It Sy UNPRIVED
436: If set, then an unprivileged install will occur.
437: The user, group, permissions, and file flags, will not be set on
438: the installed item; instead the information will be appended to
439: a file called
440: .Pa METALOG
441: in
442: .Sy DESTDIR .
443: The contents of
444: .Pa METALOG
445: is used during the generation of the distribution tar files to ensure
446: that the appropriate file ownership is stored.
447: .DFLTu
448: .
449: .It Sy UPDATE
450: If set, then all install operations intended to write to
451: .Sy DESTDIR
452: will compare file timestamps before installing, and skip the install
453: phase if the destination files are up-to-date. This also has
454: implications on full builds (see next subsection).
455: .DFLTu
456: .
457: .It Sy USETOOLS
458: Indicates whether the tools specified by
459: .Sy TOOLDIR
460: should be used as part of a build in progress. Must be set to
461: .Dq yes
462: if cross-compiling.
463: .Bl -tag -width "never"
464: .It Sy yes
465: Use the tools from
466: .Sy TOOLDIR .
467: .It Sy no
468: Do not use the tools from
469: .Sy TOOLDIR ,
470: but refuse to build native compilation tool components that are
471: version-specific for that tool.
472: .It Sy never
473: Do not use the tools from
474: .Sy TOOLDIR ,
475: even when building native tool components. This is similar to the
476: traditional
477: .Nx
478: build method, but does
479: .Em not
480: verify that the compilation tools in use are up-to-date enough in order
481: to build the tree successfully. This may cause build or runtime
482: problems when building the whole
483: .Nx
484: source tree.
485: .El
486: .DFLT
487: .Dq yes
488: if building all or part of a whole
489: .Nx
490: source tree (detected automatically);
491: .Dq no
492: otherwise (to preserve traditional semantics of the
493: .Aq bsd.*.mk
494: .Xr make 1
495: include files).
496: .
497: .El
498: .
499: .Ss \*qmake\*q variables for full builds
500: These variables only affect the top level
501: .Dq Makefile
502: and do not affect manually building subtrees of the
503: .Nx
504: source code.
505: .
506: .Bl -tag -width "NODISTRIBDIRS"
507: .
508: .It Sy MKOBJDIRS
509: .YorN
510: Indicates whether object directories will be created automatically
511: (via a
512: .Dq make obj
513: pass) at the start of a build.
514: .DFLTy
515: .
516: .It Sy NBUILDJOBS
517: Now obsolete. Use the
518: .Xr make 1
519: option
1.4 ! lukem 520: .Fl j ,
1.1 lukem 521: instead (see below)
522: .DFLTu
523: .
524: .It Sy NOCLEANDIR
525: If set, avoids the
526: .Dq make cleandir
527: phase of a full build. This has the effect of allowing only changed
528: files in a source tree to be recompiled. This can speed up builds when
529: updating only a few files in the tree.
530: .DFLTu
531: .
532: .It Sy NODISTRIBDIRS
533: If set, avoids the
534: .Dq make distrib-dirs
535: phase of a full build. This skips running
536: .Xr mtree 8
537: on
538: .Sy DESTDIR ,
539: useful on systems where building as an unprivileged user, or where it is
540: known that the system-wide mtree files have not changed.
541: .DFLTu
542: .
543: .It Sy NOINCLUDES
544: If set, avoids the
545: .Dq make includes
546: phase of a full build. This has the effect of preventing
547: .Xr make 1
548: from thinking that some programs are out-of-date simply because the
549: system include files have changed. However, this option should not be
550: used when updating the entire
551: .Nx
552: source tree arbitrarily; it is suggested to use
553: .Sy UPDATE
554: in that case.
555: .DFLTu
556: .
557: .It Sy RELEASEDIR
558: If set, specifies the directory to which a
559: .Xr release 7
560: layout will be written at the end of a
561: .Dq make release .
562: .DFLTu
563: .
564: .It Sy UPDATE
565: If set, then in addition to the effects described for UPDATE above, this
566: implies the effects of
567: .Sy NOCLEANDIR .
568: .
569: .El
570: .
571: .Sh BUILDING
572: .
573: .Ss \*qmake\*q command line options
574: This is only a summary of options available to
575: .Xr make 1 ;
576: only the options used most frequently with
577: .Nx
578: builds are listed here.
579: .
580: .Bl -tag -width "var=value"
581: .
1.4 ! lukem 582: .It Fl j Ar njob
1.1 lukem 583: Run up to
1.4 ! lukem 584: .Ar njob
1.1 lukem 585: .Xr make 1
586: subjobs in parallel.
587: Makefiles should use .WAIT or have explicit dependancies
588: as necessary to enforce build ordering.
589: If you see build failures with -j, please save complete build logs
590: so the failures can be analyzed.
591: .
1.4 ! lukem 592: .It Fl m Ar dir
1.1 lukem 593: Specify the default directory for searching for system Makefile
594: segments, mainly the
595: .Aq bsd.*.mk
596: files. When building any full
597: .Nx
598: source tree, this should be set to the
599: .Dq share/mk
600: directory in the source tree. (This is set automatically when building
601: from the top level.)
602: .
1.4 ! lukem 603: .It Fl n
1.1 lukem 604: Display the commands that would have been executed, but do not
605: actually execute them. This will still cause recursion to take place.
606: .
1.4 ! lukem 607: .It Fl v Ar var
1.1 lukem 608: Print
609: .Xr make 1 Ns 's
610: idea of the value of
1.4 ! lukem 611: .Ar var .
1.1 lukem 612: Does not build any targets.
613: .
614: .It Em var=value
615: Set the variable
616: .Em var
617: to
618: .Em value ,
619: overriding any setting specified by the process environment, the
620: .Sy MAKECONF
621: configuration file, or the system Makefile segments.
622: .
623: .El
624: .
625: .Ss \*qmake\*q targets
626: .
627: These default targets may be built by running
628: .Xr make 1
629: in any subtree of the
630: .Nx
631: source code. It is recommended that none of these be used from the top
632: level Makefile; as a specific exception,
633: .Dq make obj
634: and
635: .Dq make cleandir
636: are useful in that context.
637: .
638: .Bl -tag -width "dependall"
639: .
640: .It Sy all
641: Build programs, libraries, and preformatted documentation.
642: .
643: .It Sy clean
644: Remove program and library object code files.
645: .
646: .It Sy cleandir
647: Same as
648: .Sy clean ,
649: but also remove preformatted documentation, dependency files generated
650: by
651: .Dq make depend ,
652: and any other files known to be created at build time.
653: .Dq make distclean
654: may be used as a synonym, for familiarity with a similar well-known
655: convention.
656: .
657: .It Sy depend
658: Create dependency files
659: .Sy ( .depend )
660: containing more detailed information about the dependencies of source
661: code on header files. Allows programs to be recompiled automatically
662: when a dependency changes.
663: .
664: .It Sy dependall
665: Does a
666: .Dq make depend
667: immediately followed by a
668: .Dq make all .
669: This improves cache locality of the build since both passes read the source
670: files in their entirety.
671: .
672: .It Sy includes
673: Build and install system header files. Typically needed before any
674: system libraries or programs can be built.
675: .
676: .It Sy install
677: Install programs, libraries, and documentation into
678: .Sy DESTDIR .
679: Few files will be installed to
680: .Pa /dev ,
681: .Pa /etc ,
682: .Pa /root
683: or
684: .Pa /var
685: in order to prevent user supplied configuration data from being overwritten.
686: .It Sy lint
687: Run
688: .Xr lint 1
689: against the C source code, where appropriate, and generate
690: system-installed lint libraries.
691: .
692: .It Sy obj
693: Create object directories to be used for built files, instead of
694: building directly in the source tree.
695: .
696: .It Sy tags
697: Create
698: .Xr ctags 1
699: searchable function lists usable by the
700: .Xr ex 1
701: and
702: .Xr vi 1
703: text editors.
704: .
705: .El
706: .
707: .Ss \*qmake\*q targets for the top level
708: .
709: Additional
710: .Xr make 1
711: targets are usable specifically from the top source level to facilitate
712: building the entire
713: .Nx
714: source tree.
715: .
716: .Bl -tag -width "dependall"
717: .
718: .It Sy build
719: Build the entire
720: .Nx
721: system. This orders portions of the source tree such that prerequisites
722: will be built in the proper order.
723: .
724: .It Sy release
725: Do a
726: .Dq make build ,
727: then package the system into a standard release layout as described by
728: .Xr release 7 .
729: This requires that
730: .Sy RELEASEDIR
731: be set (see above).
732: .
733: .It Sy regression-tests
734: Can only be run after building the regression tests in the directory
735: .Dq regress .
736: Runs the compiled regression tests on the local host.
737: .
738: .El
739: .
740: .Ss The \*qbuild.sh\*q script
741: .
742: This script file is a Bourne shell script designed to build the
743: entire
744: .Nx
745: system on any host with a Bourne shell in
746: .Sy /bin/sh ,
747: including many that are not POSIX compliant. Note that if a host
748: system's
749: .Sy /bin/sh
750: is unusually old and broken, the Korn Shell
751: .Sy ( /bin/ksh ) ,
752: if available, may be a usable alternative.
753: .Pp
754: All cross-compile builds, and most native builds, of the entire system
755: should make use of
756: .Sy build.sh
757: rather than just running
758: .Dq make .
759: This way, the
760: .Xr make 1
761: program will be bootstrapped properly, in case the host system has an
762: older or incompatible
763: .Dq make
764: program.
765: .Pp
766: When compiling the entire system via
767: .Sy build.sh ,
768: many
769: .Xr make 1
770: variables are set for you in order to help encapsulate the build
771: process. In the list of options below, variables that are automatically
772: set by
773: .Sy build.sh
774: are noted where applicable.
775: .Pp
776: The following are available command line options that may be supplied to
777: .Sy build.sh :
778: .
779: .Bl -tag -width "-T tools"
780: .
1.4 ! lukem 781: .It Fl a Ar arch
1.1 lukem 782: Set the value of
783: .Sy MACHINE_ARCH
784: to
1.4 ! lukem 785: .Ar arch .
1.1 lukem 786: .
1.4 ! lukem 787: .It Fl B Ar buildid
1.1 lukem 788: Set the value of
789: .Sy BUILDID
790: to
1.4 ! lukem 791: .Ar buildid .
1.1 lukem 792: This will also append the build idenfitier to the name of the
793: .Dq make
794: wrapper script so that the resulting name is of the form
795: .Dq Sy nbmake-MACHINE-BUILDID .
796: .
1.4 ! lukem 797: .It Fl b
1.1 lukem 798: Bootstrap
799: .Dq make
800: and create a
801: .Sy nbmake-MACHINE
802: script (see below).
803: .
1.4 ! lukem 804: .It Fl D Ar dest
! 805: Set the value of
! 806: .Sy DESTDIR
! 807: to
! 808: .Ar dest .
! 809: .
! 810: .It Fl d
1.1 lukem 811: Build a full distribution.
812: This differs from a default build in that files will also be installed to
813: .Pa /dev ,
814: .Pa /etc ,
815: .Pa /root
816: and
817: .Pa /var .
818: Note this does not build a
819: .Dq release ;
820: no release sets are placed in ${RELEASEDIR}.
1.4 ! lukem 821: .Fl d
1.1 lukem 822: is implied by
1.4 ! lukem 823: .Fl R .
1.1 lukem 824: .
1.4 ! lukem 825: .It Fl j Ar njob
1.1 lukem 826: Passed through to
827: .Xr make 1 .
828: Makefiles should use .WAIT or have explicit dependancies
829: as necessary to enforce build ordering.
830: If you see build failures with -j, please save complete build logs
831: so the failures can be analyzed.
832: .
1.4 ! lukem 833: .It Fl k Em kernel
1.2 lukem 834: Build a new kernel.
835: The
1.4 ! lukem 836: .Ar kernel
1.2 lukem 837: argument is the name of a configuration file suitable
838: for use by
839: .Xr config 8 .
840: If
1.4 ! lukem 841: .Ar kernel
1.2 lukem 842: does not contain any
843: .Sq /
844: characters, the configuration file is expected to be found in the
845: .Sy KERNCONFDIR
846: directory, which is typically
847: .Sy sys/arch/MACHINE/conf .
848: The new kernel will be built in a subdirectory of
849: .Sy KERNOBJDIR ,
850: which is typically
851: .Sy sys/arch/MACHINE/compile
852: or an associated object directory.
853: In order to ensure that the kernel is built using up-to-date tools,
854: it is strongly recommended that the tools be rebuilt (using the
1.4 ! lukem 855: .Fl t
1.2 lukem 856: option) in a separate invocation of
857: .Nm build.sh
858: prior to using the
1.4 ! lukem 859: .Fl k
1.2 lukem 860: option, or that the
1.4 ! lukem 861: .Fl t
1.2 lukem 862: and
1.4 ! lukem 863: .Fl k
1.2 lukem 864: options be used together in a single invocation of
865: .Nm build.sh .
866: .
1.4 ! lukem 867: .It Fl M Ar obj
! 868: Set
! 869: .Sy MAKEOBJDIRPREFIX
! 870: to
! 871: .Ar obj .
! 872: .
! 873: .It Fl m Ar mach
1.1 lukem 874: Set the value of
875: .Sy MACHINE
876: to
1.4 ! lukem 877: .Ar mach .
1.1 lukem 878: This will also override any value of
879: .Sy MACHINE_ARCH
880: in the process environment with a value deduced from
1.4 ! lukem 881: .Ar mach ,
1.1 lukem 882: unless
1.4 ! lukem 883: .Fl a
1.1 lukem 884: is specified. All cross builds require
1.4 ! lukem 885: .Fl m ,
1.1 lukem 886: but if unset on a NetBSD host, the host's value of MACHINE will be
887: detected and used automatically.
888: .
1.4 ! lukem 889: .It Fl n
1.1 lukem 890: Show the commands that would be executed by
891: .Sy build.sh ,
892: but do not make any changes. This is similar in concept to
893: .Dq make -n .
894: .
1.4 ! lukem 895: .It Fl O Ar obj
1.1 lukem 896: Create an appropriate transform macro for
897: .Sy MAKEOBJDIR
898: that will place the built object files under
1.4 ! lukem 899: .Ar obj .
1.1 lukem 900: For instance, a setting of
901: .Sy /usr/obj
902: will place build-time files under
903: .Sy /usr/obj/bin , /usr/obj/lib ,
904: and so forth.
905: .
1.4 ! lukem 906: .It Fl o
! 907: Set the value of
! 908: .Sy MKOBJDIRS
! 909: to
! 910: .Dq no .
! 911: .
! 912: .It Fl R Ar rel
1.1 lukem 913: Set the value of
914: .Sy RELEASEDIR
915: to
1.4 ! lukem 916: .Ar rel .
1.1 lukem 917: Setting this option will cause
918: .Sy build.sh
919: to run
920: .Dq make release
921: instead of
922: .Dq make build .
923: .
1.4 ! lukem 924: .It Fl r
! 925: Remove the contents of
! 926: .Sy DESTDIR
! 927: and
! 928: .Sy TOOLDIR
! 929: before building (provides a clean starting point). This will skip deleting
! 930: .Sy DESTDIR
! 931: if building on a native system to the root directory.
! 932: .
! 933: .It Fl T Ar tools
1.1 lukem 934: Set the value of
935: .Sy TOOLDIR
936: to
1.4 ! lukem 937: .Ar tools .
1.1 lukem 938: If set, the bootstrap
939: .Dq make
940: will only be rebuilt as needed (when the source files for
941: .Xr make 1
942: change).
943: .
1.4 ! lukem 944: .It Fl t
! 945: Build and install the host tools from
! 946: .Sy src/tools
! 947: only. This option implies
! 948: .Fl b .
! 949: .
! 950: .It Fl U
1.1 lukem 951: Set the
952: .Sy UNPRIVED
953: variable.
954: .
1.4 ! lukem 955: .It Fl u
! 956: Set the
! 957: .Sy UPDATE
! 958: variable.
! 959: .
! 960: .It Fl w Ar wrapper
! 961: Create the nbmake wrapper script (see below) in a custom location,
! 962: specified by
! 963: .Ar wrapper .
! 964: This allows, for instance, to place the wrapper in
! 965: .Sy PATH
! 966: automatically. Note that
! 967: .Ar wrapper
! 968: is the full name of the file, not just a directory name.
! 969: .
1.1 lukem 970: .El
971: .
972: .Ss The \*qnbmake-MACHINE\*q wrapper script
973: .
974: If using the
975: .Sy build.sh
976: script to build
977: .Nx ,
978: a
979: .Sy nbmake-MACHINE
980: script will be created in
981: .Sy TOOLDIR/bin
982: upon the first build to assist in building subtrees on a cross-compile
983: host.
984: .Pp
985: .Sy nbmake-MACHINE
986: can be invoked in lieu of
987: .Xr make 1 ,
988: and will instead call the up-to-date version of
989: .Dq nbmake
990: installed into
991: .Sy TOOLDIR/bin
992: with several key variables pre-set, including
993: .Sy MACHINE , MACHINE_ARCH ,
994: and
995: .Sy TOOLDIR .
996: This script can be symlinked into a directory listed in
997: .Sy PATH ,
998: or called with an absolute path.
1.2 lukem 999: .
1000: .Sh EXAMPLES
1001: .Bl -tag -width "build.sh"
1002: .It Li "./build.sh -t"
1003: Build a new toolchain.
1004: .It Li "cd ${KERNCONFDIR} ; ${TOOLDIR}/bin/nbconfig GENERIC"
1005: Use the new version of
1006: .Xr config 8
1007: to prepare to build a new GENERIC kernel.
1008: .It Li "cd ${KERNOBJDIR}/GENERIC ; ${TOOLDIR}/bin/nbmake-${MACHINE} dependall"
1009: Use the new toolchain to build a new GENERIC kernel.
1010: .It Li "./build.sh -t -k GENERIC"
1011: Build a new toolchain, and use the new toolchain to
1012: configure and build a new GENERIC kernel.
1013: .It Li "./build.sh -U -d"
1014: Using unprivileged mode,
1015: build a complete distribution in
1016: .Sy DESTDIR .
1017: .It Li "./build.sh -U -R /some/dir/RELEASE"
1018: Using unprivileged mode,
1019: build a complete release in the specified release directory.
1020: .El
1.1 lukem 1021: .
1022: .Sh OBSOLETE VARIABLES
1023: .
1024: .Bl -tag -width "NBUILDJOBS"
1025: .
1026: .It Sy NBUILDJOBS
1027: Use the
1028: .Xr make 1
1029: option
1.4 ! lukem 1030: .Fl j ,
1.1 lukem 1031: instead.
1032: .
1033: .It Sy USE_NEW_TOOLCHAIN
1034: The new toolchain is now the default.
1035: To disable, use
1036: .Sy TOOLCHAIN_MISSING=yes .
1037: .El
1038: .Sh SEE ALSO
1039: .Xr make 1 ,
1040: .Xr hier 7 ,
1041: .Xr release 7
1042: .
1043: .Sh HISTORY
1044: .
1045: The
1046: .Nm build.sh
1047: based build scheme was introduced for
1048: .Nx 1.6
1049: as
1050: .Sy USE_NEW_TOOLCHAIN ,
1051: and re-worked to
1052: .Sy TOOLCHAIN_MISSING
1053: after that.
1054: .
1055: .Sh BUGS
1056: .
1057: A few platforms are not yet using this build system.
CVSweb <webmaster@jp.NetBSD.org>