Annotation of src/BUILDING.mdoc, Revision 1.18.2.2
1.18.2.2! jmc 1: .\" $NetBSD: BUILDING.mdoc,v 1.18.2.1 2003/12/18 08:24:52 tron Exp $
1.1 tv 2: .\"
3: .\" Copyright (c) 2001 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: .\"
1.2 tv 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.18.2.2! jmc 41: .Dd Dec 23, 2003
1.1 tv 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 :
1.4 wiz 63: This document applies only to platforms which use the new toolchain as
1.11 tv 64: indicated by the default setting of
1.1 tv 65: .Sy USE_NEW_TOOLCHAIN
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
1.4 wiz 75: is designed to be buildable on most POSIX-compliant host systems.
1.1 tv 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
1.4 wiz 95: .Em Note :
1.1 tv 96: A couple host toolchain components are not yet available in the tools
1.4 wiz 97: directory. Also, some tools use non-POSIX, non-ANSI C extensions
1.1 tv 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"
109: .It Sy BUILDING.mdoc
1.2 tv 110: This document (in -mdoc troff format; the original copy).
1.8 wiz 111: .It Sy BUILDING
1.2 tv 112: This document (in plaintext).
1.1 tv 113: .It Sy Makefile
114: The main Makefile for
115: .Nx ;
1.4 wiz 116: should only be run for native builds with an appropriately up-to-date
1.1 tv 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
1.4 wiz 164: userland (non-kernel) programs. If any of these directories are
1.1 tv 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
1.14 lukem 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
1.1 tv 226: .
1.3 tv 227: .Ss \*qmake\*q variables
1.1 tv 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
1.4 wiz 253: builds. Unless otherwise specified, these variables may be set in
1.1 tv 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: .
1.15 thorpej 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: .
1.1 tv 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).
1.13 lukem 281: The directory must reside on a file system which supports long file
282: names and hard links.
1.1 tv 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
1.4 wiz 300: Indicates whether preformatted plaintext manual pages will be created
1.1 tv 301: during a build.
302: .DFLTy
303: .
304: .It Sy MKCRYPTO
305: .YorN
1.4 wiz 306: Indicates whether cryptographic code will be included in a build;
307: provided for the benefit of countries that do not allow strong
1.1 tv 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
1.10 tv 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
1.1 tv 334: .
335: .It Sy MKINFO
336: .YorN
337: Indicates whether GNU Info files, used for the documentation for
1.4 wiz 338: most of the compilation tools, will be created and installed during a
1.1 tv 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
1.4 wiz 348: source code during the build, and whether lint libraries will be
1.1 tv 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
1.4 wiz 421: Directory to hold the host tools, once built. This directory should be
1.1 tv 422: unique to a given host system and
423: .Nx
424: source tree. (However, multiple targets may share the same
425: .Sy TOOLDIR ;
1.5 tv 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 .
1.1 tv 433: .DFLTu
434: .
1.13 lukem 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
1.17 lukem 441: in
442: .Sy DESTDIR .
1.13 lukem 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: .
1.1 tv 449: .It Sy UPDATE
450: If set, then all install operations intended to write to
451: .Sy DESTDIR
1.4 wiz 452: will compare file timestamps before installing, and skip the install
453: phase if the destination files are up-to-date. This also has
1.1 tv 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 ,
1.4 wiz 475: even when building native tool components. This is similar to the
1.1 tv 476: traditional
477: .Nx
478: build method, but does
479: .Em not
1.4 wiz 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
1.1 tv 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: .
1.3 tv 499: .Ss \*qmake\*q variables for full builds
1.1 tv 500: These variables only affect the top level
501: .Dq Makefile
1.13 lukem 502: and do not affect manually building subtrees of the
1.1 tv 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.
1.5 tv 514: .DFLTy
1.1 tv 515: .
516: .It Sy NBUILDJOBS
1.16 sommerfe 517: Now obsolete. Use the
1.1 tv 518: .Xr make 1
519: option
520: .Sy -j ,
1.16 sommerfe 521: instead (see below)
1.1 tv 522: .DFLTu
523: .
524: .It Sy NOCLEANDIR
525: If set, avoids the
526: .Dq make cleandir
1.4 wiz 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
1.1 tv 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
1.4 wiz 536: .Xr mtree 8
1.1 tv 537: on
538: .Sy DESTDIR ,
1.4 wiz 539: useful on systems where building as an unprivileged user, or where it is
1.1 tv 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
1.4 wiz 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
1.1 tv 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: .
1.3 tv 573: .Ss \*qmake\*q command line options
1.1 tv 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.16 sommerfe 582: .It Sy -j Em njob
583: Run up to
584: .Em njob
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.1 tv 592: .It Sy -m Em dir
1.4 wiz 593: Specify the default directory for searching for system Makefile
1.1 tv 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: .
603: .It Sy -n
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.18.2.2! jmc 607: .It Sy -V Em var
1.1 tv 608: Print
1.4 wiz 609: .Xr make 1 Ns 's
1.1 tv 610: idea of the value of
611: .Em var .
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: .
1.3 tv 625: .Ss \*qmake\*q targets
1.1 tv 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 ,
1.4 wiz 649: but also remove preformatted documentation, dependency files generated
1.1 tv 650: by
651: .Dq make depend ,
1.4 wiz 652: and any other files known to be created at build time.
1.1 tv 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 )
1.4 wiz 660: containing more detailed information about the dependencies of source
1.1 tv 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 .
1.16 sommerfe 669: This improves cache locality of the build since both passes read the source
670: files in their entirety.
1.1 tv 671: .
672: .It Sy includes
1.4 wiz 673: Build and install system header files. Typically needed before any
1.1 tv 674: system libraries or programs can be built.
675: .
676: .It Sy install
677: Install programs, libraries, and documentation into
678: .Sy DESTDIR .
679: .
680: .It Sy lint
681: Run
682: .Xr lint 1
1.4 wiz 683: against the C source code, where appropriate, and generate
1.1 tv 684: system-installed lint libraries.
685: .
686: .It Sy obj
1.4 wiz 687: Create object directories to be used for built files, instead of
1.1 tv 688: building directly in the source tree.
689: .
690: .It Sy tags
691: Create
692: .Xr ctags 1
693: searchable function lists usable by the
694: .Xr ex 1
695: and
696: .Xr vi 1
697: text editors.
698: .
699: .El
700: .
1.3 tv 701: .Ss \*qmake\*q targets for the top level
1.1 tv 702: .
703: Additional
704: .Xr make 1
705: targets are usable specifically from the top source level to facilitate
706: building the entire
707: .Nx
708: source tree.
709: .
710: .Bl -tag -width "dependall"
711: .
712: .It Sy build
713: Build the entire
714: .Nx
715: system. This orders portions of the source tree such that prerequisites
716: will be built in the proper order.
717: .
718: .It Sy release
719: Do a
720: .Dq make build ,
721: then package the system into a standard release layout as described by
722: .Xr release 7 .
723: This requires that
724: .Sy RELEASEDIR
725: be set (see above).
726: .
727: .It Sy regression-tests
728: Can only be run after building the regression tests in the directory
729: .Dq regress .
730: Runs the compiled regression tests on the local host.
731: .
732: .El
733: .
1.3 tv 734: .Ss The \*qbuild.sh\*q script
1.1 tv 735: .
1.4 wiz 736: This script file is a Bourne shell script designed to build the
1.1 tv 737: entire
738: .Nx
739: system on any host with a Bourne shell in
740: .Sy /bin/sh ,
1.4 wiz 741: including many that are not POSIX compliant. Note that if a host
1.1 tv 742: system's
743: .Sy /bin/sh
744: is unusually old and broken, the Korn Shell
745: .Sy ( /bin/ksh ) ,
746: if available, may be a usable alternative.
747: .Pp
1.4 wiz 748: All cross-compile builds, and most native builds, of the entire system
1.1 tv 749: should make use of
750: .Sy build.sh
751: rather than just running
752: .Dq make .
753: This way, the
754: .Xr make 1
1.4 wiz 755: program will be bootstrapped properly, in case the host system has an
1.1 tv 756: older or incompatible
757: .Dq make
758: program.
759: .Pp
760: When compiling the entire system via
761: .Sy build.sh ,
762: many
763: .Xr make 1
1.4 wiz 764: variables are set for you in order to help encapsulate the build
1.5 tv 765: process. In the list of options below, variables that are automatically
766: set by
1.1 tv 767: .Sy build.sh
1.5 tv 768: are noted where applicable.
1.1 tv 769: .Pp
770: The following are available command line options that may be supplied to
771: .Sy build.sh :
772: .
773: .Bl -tag -width "-T tools"
774: .
775: .It Sy -a Em arch
776: Set the value of
777: .Sy MACHINE_ARCH
778: to
779: .Em arch .
1.15 thorpej 780: .
781: .It Sy -B Em buildid
782: Set the value of
783: .Sy BUILDID
784: to
785: .Em buildid .
786: This will also append the build idenfitier to the name of the
787: .Dq make
788: wrapper script so that the resulting name is of the form
789: .Dq Sy nbmake-MACHINE-BUILDID .
1.1 tv 790: .
1.5 tv 791: .It Sy -b
792: Bootstrap
793: .Dq make
794: and create a
795: .Sy nbmake-MACHINE
796: script (see below).
1.12 thorpej 797: .
798: .It Sy -d
799: Build a full distribution. This differs from a normal build in that
800: etc files will also be installed. Note this does not build a
801: .Dq release ;
802: no release sets are placed in ${RELEASEDIR}.
1.1 tv 803: .
804: .It Sy -j Em njob
1.16 sommerfe 805: Passed through to
806: .Xr make 1 .
807: Makefiles should use .WAIT or have explicit dependancies
808: as necessary to enforce build ordering.
809: If you see build failures with -j, please save complete build logs
810: so the failures can be analyzed.
1.1 tv 811: .
812: .It Sy -m Em mach
813: Set the value of
814: .Sy MACHINE
815: to
816: .Em mach .
817: This will also override any value of
818: .Sy MACHINE_ARCH
819: in the process environment with a value deduced from
820: .Em mach ,
821: unless
822: .Sy -a
1.5 tv 823: is specified. All cross builds require
824: .Sy -m ,
825: but if unset on a NetBSD host, the host's value of MACHINE will be
826: detected and used automatically.
827: .
828: .It Sy -n
829: Show the commands that would be executed by
830: .Sy build.sh ,
831: but do not make any changes. This is similar in concept to
832: .Dq make -n .
833: .
834: .It Sy -o
835: Set the value of
836: .Sy MKOBJDIRS
837: to
838: .Dq no .
839: .
840: .It Sy -r
841: Remove the contents of
842: .Sy DESTDIR
843: and
844: .Sy TOOLDIR
845: before building (provides a clean starting point). This will skip deleting
846: .Sy DESTDIR
847: if building on a native system to the root directory.
848: .
1.6 thorpej 849: .It Sy -t
1.7 tv 850: Build and install the host tools from
851: .Sy src/tools
852: only. This option implies
1.6 thorpej 853: .Sy -b .
1.7 tv 854: .
1.5 tv 855: .It Sy -u
856: Set the
857: .Sy UPDATE
858: variable.
859: .
860: .It Sy -w Em wrapper
861: Create the nbmake wrapper script (see below) in a custom location,
862: specified by
863: .Em wrapper .
864: This allows, for instance, to place the wrapper in
865: .Sy PATH
866: automatically. Note that
867: .Em wrapper
868: is the full name of the file, not just a directory name.
869: .
870: .It Sy -D Em dest
871: Set the value of
872: .Sy DESTDIR
873: to
874: .Em dest .
1.18 lukem 875: .
876: .It Sy -M Em obj
877: Set
878: .Sy MAKEOBJDIRPREFIX
879: to
880: .Em obj .
1.5 tv 881: .
882: .It Sy -O Em obj
883: Create an appropriate transform macro for
884: .Sy MAKEOBJDIR
885: that will place the built object files under
886: .Em obj .
887: For instance, a setting of
888: .Sy /usr/obj
889: will place build-time files files under
890: .Sy /usr/obj/bin , /usr/obj/lib ,
891: and so forth.
1.1 tv 892: .
893: .It Sy -R Em rel
894: Set the value of
895: .Sy RELEASEDIR
896: to
897: .Em rel .
1.5 tv 898: Setting this option will cause
1.1 tv 899: .Sy build.sh
1.5 tv 900: to run
1.1 tv 901: .Dq make release
902: instead of
903: .Dq make build .
904: .
905: .It Sy -T Em tools
906: Set the value of
907: .Sy TOOLDIR
908: to
909: .Em tools .
1.5 tv 910: If set, the bootstrap
911: .Dq make
912: will only be rebuilt as needed (when the source files for
913: .Xr make 1
914: change).
1.13 lukem 915: .
916: .It Sy -U
917: Set the
918: .Sy UNPRIVED
919: variable.
1.1 tv 920: .
921: .El
922: .
1.3 tv 923: .Ss The \*qnbmake-MACHINE\*q wrapper script
1.1 tv 924: .
925: If using the
926: .Sy build.sh
927: script to build
928: .Nx ,
929: a
930: .Sy nbmake-MACHINE
931: script will be created in
932: .Sy TOOLDIR/bin
1.4 wiz 933: upon the first build to assist in building subtrees on a cross-compile
1.1 tv 934: host.
935: .Pp
936: .Sy nbmake-MACHINE
937: can be invoked in lieu of
938: .Xr make 1 ,
939: and will instead call the up-to-date version of
940: .Dq nbmake
941: installed into
942: .Sy TOOLDIR/bin
943: with several key variables pre-set, including
944: .Sy MACHINE , MACHINE_ARCH ,
945: and
946: .Sy TOOLDIR .
947: This script can be symlinked into a directory listed in
948: .Sy PATH ,
949: or called with an absolute path.
950: .
1.18.2.1 tron 951: .Sh EXAMPLES
952: .
953: .Bl -enum
954: .
955: .It
956: .Li "% ./build.sh -U"
957: .Pp
958: Using unprivileged mode,
959: build a complete distribution to a
960: .Sy DESTDIR
961: directory that
962: .Sy build.sh
963: selects (and will display).
964: .
965: .It
966: .Li "# ./build.sh -U -d -D /"
967: .Pp
968: As root, install to
969: .Pa /
970: a complete distribution.
971: Even though this is run as root,
972: .Fl U
973: is required so that the permissions stored in
974: .Sy DESTDIR Ns Pa /METALOG
975: are correctly applied to the files as they're copied to
976: .Pa / .
977: .
978: .It
979: .Li "% ./build.sh -U -u -R <dir>"
980: .Pp
981: Using unprivileged mode,
982: build a complete release to a
983: .Sy DESTDIR
984: directory that
985: .Sy build.sh
986: selects (and will display), and to a user specified
987: .Sy RELEASEDIR .
988: .Sy MKUPDATE=yes
989: .Pq Fl u
990: is set to prevent the
991: .Dq make cleandir ,
992: so that if this is run after example 1, it doesn't need to redo that
993: portion of the release build.
994: .
995: .It
996: .Li "% ./build.sh -t"
997: .Pp
998: Perform a build that builds and installs the cross tools only. These are
999: installed into a
1000: .Sy TOOLDIR
1001: directory that
1002: .Sy build.sh
1003: selects (and will display).
1004: .El
1005: .
1.16 sommerfe 1006: .Sh OBSOLETE VARIABLES
1007: .
1008: .Bl -tag -width "NBUILDJOBS"
1009: .
1010: .It Sy NBUILDJOBS
1011: Now obsolete. Use the
1012: .Xr make 1
1013: option
1014: .Sy -j ,
1015: instead.
1016: .El
1.1 tv 1017: .Sh SEE ALSO
1018: .Xr make 1 ,
1019: .Xr hier 7 ,
1020: .Xr release 7
1021: .
1022: .Sh HISTORY
1023: .
1024: The
1025: .Sy USE_NEW_TOOLCHAIN
1026: based build scheme was introduced in the
1.4 wiz 1027: .Dq Nx Ns -current
1.1 tv 1028: development sources between
1029: .Nx 1.5
1030: and
1.4 wiz 1031: .Nx 1.6 .
1032: .
1033: .Sh BUGS
1034: .
1.16 sommerfe 1035: A few platforms are not yet using the
1.4 wiz 1036: .Sy USE_NEW_TOOLCHAIN
1037: system.
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