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