Annotation of src/doc/BUILDING.mdoc, Revision 1.41
1.41 ! wiz 1: .\" $NetBSD: BUILDING.mdoc,v 1.40 2006/01/04 15:35:20 apb Exp $
1.1 lukem 2: .\"
1.34 lukem 3: .\" Copyright (c) 2001-2004 The NetBSD Foundation, Inc.
1.1 lukem 4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
1.9 lukem 7: .\" by Todd Vierling and Luke Mewburn.
1.1 lukem 8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\" 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: .\" NOTE: After changing this file, run "make build-docs" to generate the
38: .\" proper plaintext versions, and check in all BUILDING.* files!
39: .\"
1.13 lukem 40: .\" Toolchain prefix for commands
41: .ds toolprefix nb
42: .
1.41 ! wiz 43: .Dd January 4, 2006
1.1 lukem 44: .Dt BUILDING 8
45: .Os NetBSD
46: .
47: .Sh NAME
48: .
49: .Nm BUILDING
50: .Nd Procedure for building
51: .Nx
52: from source code.
53: .
54: .Sh STATUS
55: .
1.6 wiz 56: This document is a work-in-progress.
57: As such, the information described
1.1 lukem 58: here may not match the reality of the build system as of this writing.
59: Once this document is completely in sync with reality, this paragraph
60: will be removed.
61: .Pp
62: Discrepancies between this documentation and the current reality of
63: implementation are noted specially, as with the note below:
64: .Pp
65: .Em Note :
66: This document applies only to platforms which use the new toolchain as
67: indicated by the default setting of
68: .Sy TOOLCHAIN_MISSING
69: in
70: .Aq bsd.own.mk .
71: Platforms which have not yet been switched to the new toolchain should
72: continue building traditionally, using the notes specified in the file
73: .Sy UPDATING .
74: .
75: .Sh REQUIREMENTS
76: .
77: .Nx
78: is designed to be buildable on most POSIX-compliant host systems.
79: The basic build procedure is the same whether compiling
80: .Em natively
81: (on the same
82: .Nx
83: architecture) or
84: .Em cross compiling
85: (on another architecture or OS).
86: .Pp
87: This source tree contains a special subtree,
88: .Dq tools ,
89: which uses the host system to create a build toolchain for the target
1.6 wiz 90: architecture.
91: The host system must have at least C and C++
1.1 lukem 92: compilers in order to create the toolchain
93: .Nm ( make
94: is not required); all other tools are created as part of the
95: .Nx
96: build process.
1.38 reed 97: (See the environment variables section below if you need
98: to override or manually select your compilers.)
1.1 lukem 99: .
100: .Sh FILES
101: .
102: .Ss Source tree layout
103: .
104: .Bl -tag -width "BUILDING.mdoc"
1.3 wiz 105: .It Sy doc/BUILDING.mdoc
1.1 lukem 106: This document (in -mdoc troff format; the original copy).
107: .It Sy BUILDING
108: This document (in plaintext).
1.33 jmc 109: .It Sy tools/compat/README
110: Special notes for cross-hosting a NetBSD build on non-NetBSD platforms.
1.1 lukem 111: .It Sy Makefile
112: The main Makefile for
113: .Nx ;
114: should only be run for native builds with an appropriately up-to-date
115: version of
116: .Nx
117: .Xr make 1 .
118: (For building from out-of-date systems or on a non-native host, see the
119: .Nm build.sh
120: shell script.)
121: .It Sy UPDATING
122: Special notes for updating from an earlier revision of
123: .Nx .
124: It is important to read this file before every build of an updated
125: source tree.
126: .It Sy build.sh
127: Bourne-compatible shell script used for building the host build tools
128: and the
129: .Nx
1.6 wiz 130: system from scratch.
131: Can be used for both native and cross builds, and should be used instead of
1.1 lukem 132: .Xr make 1
133: for any source tree that is updated and recompiled regularly.
134: .It Sy crypto/dist/ , dist/ , gnu/dist/
135: Sources imported verbatim from third parties, without mangling the
1.6 wiz 136: existing build structure.
137: Other source trees in
1.1 lukem 138: .Sy bin
139: through
140: .Sy usr.sbin
141: use the
142: .Nx
143: .Xr make 1
144: .Dq reachover
145: Makefile semantics when building these programs for a native host.
146: .It Sy distrib/ , etc/
147: Sources for items used when making a full release snapshot, such as
148: files installed in
1.14 lukem 149: .Sy DESTDIR Ns Pa /etc
1.1 lukem 150: on the destination system, boot media, and release notes.
151: .It Sy regress/
1.6 wiz 152: Regression test harness.
153: Can be cross-compiled, but only run natively.
1.1 lukem 154: .It Sy sys/
155: .Nx
156: kernel sources.
157: .It Sy tools/
158: .Dq Reachover
1.6 wiz 159: build structure for the host build tools.
160: This has a special method of determining out-of-date status.
1.1 lukem 161: .It Sy bin/ ... usr.sbin/
162: Sources to the
163: .Nx
1.6 wiz 164: userland (non-kernel) programs.
165: If any of these directories are missing, they will be skipped during the build.
1.34 lukem 166: .It Sy x11/
167: .Dq Reachover
168: build structure for X11R6; the source is in
169: .Sy X11SRCDIR .
1.1 lukem 170: .El
171: .
172: .Ss Build tree layout
173: .
174: The
175: .Nx
176: build tree is described in
177: .Xr hier 7 ,
178: and the release layout is described in
179: .Xr release 7 .
180: .Pp
181: .
182: .Sh CONFIGURATION
183: .
184: .Ss Environment variables
185: ..
186: Several environment variables control the behaviour of
187: .Nx
188: builds.
189: .
190: .Bl -tag -width "MAKEOBJDIRPREFIX"
191: .
1.38 reed 192: .
193: .It Sy HOST_CC
194: Path name to C compiler used to create the toolchain.
195: .
196: .It Sy HOST_CXX
197: Path name to C++ compiler used to create the toolchain.
198: .
1.1 lukem 199: .It Sy MACHINE
200: Machine type.
201: .
202: .It Sy MACHINE_ARCH
203: Machine architecture.
204: .
205: .It Sy MAKE
206: Path name to invoke
207: .Xr make 1
208: as.
209: .
210: .It Sy MAKEFLAGS
211: Flags to invoke
212: .Xr make 1
213: with.
214: .
215: .It Sy MAKEOBJDIR
216: Directory to use as the
217: .Sy .OBJDIR
218: for the current directory.
219: Used only if
220: .Sy MAKEOBJDIRPREFIX
221: is not defined.
222: .Sy MAKEOBJDIR
1.23 lukem 223: can only be provided in the environment or via the
1.28 lukem 224: .Fl O
1.23 lukem 225: flag of
226: .Nm build.sh .
1.1 lukem 227: .
228: .It Sy MAKEOBJDIRPREFIX
229: Top level directory of the object directory tree.
230: If this is defined,
231: ${MAKEOBJDIRPREFIX}/${.CURDIR}
232: is used as the
233: .Sy .OBJDIR
234: for the current directory.
235: The current directory may be read only.
236: .Sy MAKEOBJDIRPREFIX
1.23 lukem 237: can only be provided in the environment or via the
238: .Fl M
239: flag of
240: .Nm build.sh .
1.1 lukem 241: .
242: .El
243: .
244: .Ss \*qmake\*q variables
245: .
246: .de YorN
247: Can be set to
248: .Dq yes
249: or
250: .Dq no .
251: ..
252: .de DFLT
253: .Pp
254: .Em Default :
255: ..
256: .de DFLTu
257: .DFLT
258: Unset.
259: ..
260: .de DFLTy
261: .DFLT
262: .Dq yes
263: ..
264: .de DFLTn
265: .DFLT
266: .Dq no
267: ..
268: Several variables control the behavior of
269: .Nx
1.6 wiz 270: builds.
271: Unless otherwise specified, these variables may be set in
1.1 lukem 272: either the process environment or the
273: .Xr make 1
274: configuration file specified by
275: .Sy MAKECONF .
276: .
277: .Bl -tag -width "MKCATPAGES"
278: .
279: .It Sy BUILDID
1.6 wiz 280: Identifier for the build.
281: The identifier will be appended to
1.1 lukem 282: object directory names, and can be consulted in the
283: .Xr make 1
284: configuration file in order to set additional build parameters,
285: such as compiler flags.
286: .
287: .It Sy DESTDIR
288: Directory to contain the built
289: .Nx
1.6 wiz 290: system.
291: If set, special options are passed to the compilation tools to
1.1 lukem 292: prevent their default use of the host system's
293: .Sy /usr/include , /usr/lib ,
1.6 wiz 294: and so forth.
295: This pathname should
1.1 lukem 296: .Em not
297: end with a slash
298: .Pq /
299: character (for installation into the system's root directory, set
300: .Sy DESTDIR
301: to an empty string).
302: The directory must reside on a file system which supports long file
303: names and hard links.
304: .DFLT
305: Empty string if
306: .Sy USETOOLS
307: is
308: .Dq yes ;
309: unset otherwise.
1.17 lukem 310: .Pp
311: .Em Note :
312: .Sy build.sh
313: will provide a default of
314: .Pa destdir. Ns Sy MACHINE
315: (in the top-level
316: .Sy .OBJDIR )
317: unless run in
318: .Sq expert
319: mode
1.1 lukem 320: .
321: .It Sy MAKECONF
322: The name of the
323: .Xr make 1
324: configuration file.
325: .Em Only settable in the process environment.
326: .DFLT
327: .Dq /etc/mk.conf
328: .
1.30 lukem 329: .It Sy MAKEVERBOSE
330: Level of verbosity of status messages.
331: Supported values:
332: .Bl -tag -width xxx
333: .It 0
334: No descriptive messages are shown.
335: .It 1
336: Descriptive messages are shown.
337: .It 2
338: Descriptive messages (prefixed with a
339: .Sq # )
340: and command output is not suppressed.
341: .El
342: .DFLT
343: 2
344: .
1.1 lukem 345: .It Sy MKCATPAGES
346: .YorN
347: Indicates whether preformatted plaintext manual pages will be created
348: during a build.
349: .DFLTy
350: .
351: .It Sy MKCRYPTO
352: .YorN
353: Indicates whether cryptographic code will be included in a build;
354: provided for the benefit of countries that do not allow strong
1.6 wiz 355: cryptography.
356: Will not affect use of the standard low-security password encryption system,
1.1 lukem 357: .Xr crypt 3 .
358: .DFLTy
359: .
360: .It Sy MKDOC
361: .YorN
362: Indicates whether system documentation destined for
1.14 lukem 363: .Sy DESTDIR Ns Pa /usr/share/doc
1.1 lukem 364: will be installed during a build.
365: .DFLTy
366: .
367: .It Sy MKHOSTOBJ
368: .YorN
369: If set to
370: .Dq yes ,
371: then for programs intended to be run on the compile host,
372: the name, release, and architecture of the host operating system
373: will be suffixed to the name of the object directory created by
374: .Dq make obj .
375: (This allows multiple host systems to compile NetBSD for a single target.)
376: If set to
377: .Dq no ,
378: then programs built to be run on the compile host will use the same
379: object directory names as programs built to be run on the target.
380: .DFLTn
381: .
382: .It Sy MKINFO
383: .YorN
384: Indicates whether GNU Info files, used for the documentation for
385: most of the compilation tools, will be created and installed during a
386: build.
387: .DFLTy
388: .
389: .It Sy MKLINT
390: .YorN
391: Indicates whether
392: .Xr lint 1
393: will be run against portions of the
394: .Nx
395: source code during the build, and whether lint libraries will be
396: installed into
1.14 lukem 397: .Sy DESTDIR Ns Pa /usr/libdata/lint .
1.1 lukem 398: .DFLTy
399: .
400: .It Sy MKMAN
401: .YorN
402: Indicates whether manual pages will be installed during a build.
403: .DFLTy
404: .
405: .It Sy MKNLS
406: .YorN
407: Indicates whether Native Language System locale zone files will be
408: compiled and installed during a build.
409: .DFLTy
410: .
411: .It Sy MKOBJ
412: .YorN
413: Indicates whether object directories will be created when running
414: .Dq make obj .
415: If set to
416: .Dq no ,
417: then all built files will be located inside the regular source tree.
418: .DFLTy
419: .
420: .It Sy MKPIC
421: .YorN
422: Indicates whether shared objects and libraries will be created and
1.6 wiz 423: installed during a build.
424: If set to
1.1 lukem 425: .Dq no ,
426: the entire built system will be statically linked.
427: .DFLT
1.6 wiz 428: Platform dependent.
429: As of this writing, all platforms except
1.1 lukem 430: .Sy sh3
431: default to
432: .Dq yes .
433: .
434: .It Sy MKPICINSTALL
435: .YorN
436: Indicates whether the
437: .Xr ar 1
438: format libraries
439: .Sy ( lib*_pic.a ) ,
440: used to generate shared libraries, are installed during a build.
441: .DFLTy
442: .
443: .It Sy MKPROFILE
444: .YorN
445: Indicates whether profiled libraries
446: .Sy ( lib*_p.a )
447: will be built and installed during a build.
448: .DFLT
449: .Dq yes ;
450: however, some platforms turn off
451: .Sy MKPROFILE
452: by default at times due to toolchain problems with profiled code.
453: .
454: .It Sy MKSHARE
455: .YorN
456: Indicates whether files destined to reside in
1.14 lukem 457: .Sy DESTDIR Ns Pa /usr/share
1.6 wiz 458: will be built and installed during a build.
459: If set to
1.1 lukem 460: .Dq no ,
461: then all of
462: .Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
463: and
464: .Sy MKNLS
465: will be set to
466: .Dq no
467: unconditionally.
468: .DFLTy
469: .
1.35 wiz 470: .It Sy MKTTINTERP
471: .YorN
472: For X builds, decides if the TrueType bytecode interpreter
473: is turned on.
474: See
475: .Pa http://www.freetype.org/patents.html
476: for details.
477: .DFLTn
478: .
1.25 lukem 479: .It Sy MKUNPRIVED
480: .YorN
481: Indicates whether an unprivileged install will occur.
1.1 lukem 482: The user, group, permissions, and file flags, will not be set on
1.37 jmc 483: the installed items; instead the information will be appended to
1.1 lukem 484: a file called
485: .Pa METALOG
486: in
487: .Sy DESTDIR .
488: The contents of
489: .Pa METALOG
1.37 jmc 490: are used during the generation of the distribution tar files to ensure
1.1 lukem 491: that the appropriate file ownership is stored.
1.25 lukem 492: .DFLTn
1.1 lukem 493: .
1.25 lukem 494: .It Sy MKUPDATE
495: .YorN
496: Indicates whether all install operations intended to write to
1.1 lukem 497: .Sy DESTDIR
498: will compare file timestamps before installing, and skip the install
1.6 wiz 499: phase if the destination files are up-to-date.
500: This also has implications on full builds (see next subsection).
1.25 lukem 501: .DFLTn
502: .
1.34 lukem 503: .It Sy MKX11
504: .YorN
505: Indicates whether X11R6 is built from
506: .Sy X11SRCDIR .
507: .DFLTn
508: .
1.25 lukem 509: .It Sy TOOLDIR
510: Directory to hold the host tools, once built.
511: This directory should be unique to a given host system and
512: .Nx
513: source tree.
514: (However, multiple targets may share the same
515: .Sy TOOLDIR ;
516: the target-dependent files have unique names.) If unset, a default based
517: on the
518: .Xr uname 1
519: information of the host platform will be created in the
520: .Sy .OBJDIR
521: of
1.26 lukem 522: .Pa src .
1.1 lukem 523: .DFLTu
524: .
525: .It Sy USETOOLS
526: Indicates whether the tools specified by
527: .Sy TOOLDIR
1.6 wiz 528: should be used as part of a build in progress.
529: Must be set to
1.1 lukem 530: .Dq yes
531: if cross-compiling.
532: .Bl -tag -width "never"
533: .It Sy yes
534: Use the tools from
535: .Sy TOOLDIR .
536: .It Sy no
537: Do not use the tools from
538: .Sy TOOLDIR ,
539: but refuse to build native compilation tool components that are
540: version-specific for that tool.
541: .It Sy never
542: Do not use the tools from
543: .Sy TOOLDIR ,
1.6 wiz 544: even when building native tool components.
545: This is similar to the traditional
1.1 lukem 546: .Nx
547: build method, but does
548: .Em not
549: verify that the compilation tools in use are up-to-date enough in order
1.6 wiz 550: to build the tree successfully.
551: This may cause build or runtime problems when building the whole
1.1 lukem 552: .Nx
553: source tree.
554: .El
555: .DFLT
556: .Dq yes
557: if building all or part of a whole
558: .Nx
559: source tree (detected automatically);
560: .Dq no
561: otherwise (to preserve traditional semantics of the
562: .Aq bsd.*.mk
563: .Xr make 1
564: include files).
565: .
1.34 lukem 566: .It Sy X11SRCDIR
567: Directory containing the X11R6 source.
568: The main X11R6 source is found in
569: .Sy X11SRCDIR Ns Pa /xfree/xc .
570: .DFLT
571: .Dq /usr/xsrc
572: .
1.1 lukem 573: .El
574: .
575: .Ss \*qmake\*q variables for full builds
576: These variables only affect the top level
577: .Dq Makefile
578: and do not affect manually building subtrees of the
579: .Nx
580: source code.
581: .
1.7 lukem 582: .Bl -tag -width "INSTALLWORLDDIR"
583: .
584: .It Sy INSTALLWORLDDIR
585: Location for the
586: .Dq make installworld
587: target to install to.
588: .DFLT
589: .Dq /
1.1 lukem 590: .
591: .It Sy MKOBJDIRS
592: .YorN
593: Indicates whether object directories will be created automatically
594: (via a
595: .Dq make obj
596: pass) at the start of a build.
1.21 lukem 597: .DFLTn
1.1 lukem 598: .
1.25 lukem 599: .It Sy MKUPDATE
600: .YorN
601: If set, then in addition to the effects described for
602: .Sy MKUPDATE=yes
603: above, this implies the effects of
604: .Sy NOCLEANDIR
605: (i.e.,
606: .Dq make cleandir
607: is avoided).
608: .DFLTn
609: .
1.1 lukem 610: .It Sy NBUILDJOBS
1.6 wiz 611: Now obsolete.
612: Use the
1.1 lukem 613: .Xr make 1
614: option
1.4 lukem 615: .Fl j ,
1.1 lukem 616: instead (see below)
617: .DFLTu
618: .
619: .It Sy NOCLEANDIR
620: If set, avoids the
621: .Dq make cleandir
1.6 wiz 622: phase of a full build.
623: This has the effect of allowing only changed
624: files in a source tree to be recompiled.
625: This can speed up builds when updating only a few files in the tree.
1.1 lukem 626: .DFLTu
627: .
628: .It Sy NODISTRIBDIRS
629: If set, avoids the
630: .Dq make distrib-dirs
1.6 wiz 631: phase of a full build.
632: This skips running
1.1 lukem 633: .Xr mtree 8
634: on
635: .Sy DESTDIR ,
636: useful on systems where building as an unprivileged user, or where it is
637: known that the system-wide mtree files have not changed.
638: .DFLTu
639: .
640: .It Sy NOINCLUDES
641: If set, avoids the
642: .Dq make includes
1.6 wiz 643: phase of a full build.
644: This has the effect of preventing
1.1 lukem 645: .Xr make 1
646: from thinking that some programs are out-of-date simply because the
1.6 wiz 647: system include files have changed.
648: However, this option should not be used when updating the entire
1.1 lukem 649: .Nx
650: source tree arbitrarily; it is suggested to use
1.25 lukem 651: .Sy MKUPDATE=yes
1.1 lukem 652: in that case.
653: .DFLTu
654: .
655: .It Sy RELEASEDIR
656: If set, specifies the directory to which a
657: .Xr release 7
658: layout will be written at the end of a
659: .Dq make release .
660: .DFLTu
1.17 lukem 661: .Pp
662: .Em Note :
663: .Sy build.sh
664: will provide a default of
665: .Pa releasedir
666: (in the top-level
667: .Sy .OBJDIR )
668: unless run in
669: .Sq expert
670: mode
1.1 lukem 671: .
672: .El
673: .
674: .Sh BUILDING
675: .
676: .Ss \*qmake\*q command line options
1.37 jmc 677: This is not a summary of all the options available to
1.1 lukem 678: .Xr make 1 ;
679: only the options used most frequently with
680: .Nx
681: builds are listed here.
682: .
683: .Bl -tag -width "var=value"
684: .
1.4 lukem 685: .It Fl j Ar njob
1.1 lukem 686: Run up to
1.4 lukem 687: .Ar njob
1.1 lukem 688: .Xr make 1
689: subjobs in parallel.
1.37 jmc 690: Makefiles should use .WAIT or have explicit dependencies
1.1 lukem 691: as necessary to enforce build ordering.
692: If you see build failures with -j, please save complete build logs
693: so the failures can be analyzed.
694: .
1.4 lukem 695: .It Fl m Ar dir
1.1 lukem 696: Specify the default directory for searching for system Makefile
697: segments, mainly the
698: .Aq bsd.*.mk
1.6 wiz 699: files.
700: When building any full
1.1 lukem 701: .Nx
702: source tree, this should be set to the
703: .Dq share/mk
1.6 wiz 704: directory in the source tree.
705: (This is set automatically when building from the top level.)
1.1 lukem 706: .
1.4 lukem 707: .It Fl n
1.1 lukem 708: Display the commands that would have been executed, but do not
1.6 wiz 709: actually execute them.
710: This will still cause recursion to take place.
1.1 lukem 711: .
1.32 zuntum 712: .It Fl V Ar var
1.1 lukem 713: Print
714: .Xr make 1 Ns 's
715: idea of the value of
1.4 lukem 716: .Ar var .
1.1 lukem 717: Does not build any targets.
718: .
719: .It Em var=value
720: Set the variable
721: .Em var
722: to
723: .Em value ,
724: overriding any setting specified by the process environment, the
725: .Sy MAKECONF
726: configuration file, or the system Makefile segments.
727: .
728: .El
729: .
730: .Ss \*qmake\*q targets
731: .
732: These default targets may be built by running
733: .Xr make 1
734: in any subtree of the
735: .Nx
1.6 wiz 736: source code.
737: It is recommended that none of these be used from the top
1.1 lukem 738: level Makefile; as a specific exception,
739: .Dq make obj
740: and
741: .Dq make cleandir
742: are useful in that context.
743: .
744: .Bl -tag -width "dependall"
745: .
746: .It Sy all
747: Build programs, libraries, and preformatted documentation.
748: .
749: .It Sy clean
750: Remove program and library object code files.
751: .
752: .It Sy cleandir
753: Same as
754: .Sy clean ,
755: but also remove preformatted documentation, dependency files generated
756: by
757: .Dq make depend ,
758: and any other files known to be created at build time.
759: .
760: .It Sy depend
761: Create dependency files
762: .Sy ( .depend )
763: containing more detailed information about the dependencies of source
1.6 wiz 764: code on header files.
765: Allows programs to be recompiled automatically when a dependency changes.
1.1 lukem 766: .
767: .It Sy dependall
768: Does a
769: .Dq make depend
770: immediately followed by a
771: .Dq make all .
772: This improves cache locality of the build since both passes read the source
773: files in their entirety.
774: .
1.34 lukem 775: .It Sy distclean
776: Synonym for
777: .Sy cleandir .
778: .
1.1 lukem 779: .It Sy includes
1.6 wiz 780: Build and install system header files.
781: Typically needed before any system libraries or programs can be built.
1.1 lukem 782: .
783: .It Sy install
784: Install programs, libraries, and documentation into
785: .Sy DESTDIR .
786: Few files will be installed to
1.14 lukem 787: .Sy DESTDIR Ns Pa /dev ,
788: .Sy DESTDIR Ns Pa /etc ,
789: .Sy DESTDIR Ns Pa /root
1.1 lukem 790: or
1.14 lukem 791: .Sy DESTDIR Ns Pa /var
1.1 lukem 792: in order to prevent user supplied configuration data from being overwritten.
793: .It Sy lint
794: Run
795: .Xr lint 1
796: against the C source code, where appropriate, and generate
797: system-installed lint libraries.
798: .
799: .It Sy obj
800: Create object directories to be used for built files, instead of
801: building directly in the source tree.
802: .
803: .It Sy tags
804: Create
805: .Xr ctags 1
806: searchable function lists usable by the
807: .Xr ex 1
808: and
809: .Xr vi 1
810: text editors.
811: .
812: .El
813: .
814: .Ss \*qmake\*q targets for the top level
815: .
816: Additional
817: .Xr make 1
818: targets are usable specifically from the top source level to facilitate
819: building the entire
820: .Nx
821: source tree.
822: .
1.7 lukem 823: .Bl -tag -width "distribution"
1.1 lukem 824: .
825: .It Sy build
826: Build the entire
827: .Nx
1.6 wiz 828: system.
829: This orders portions of the source tree such that prerequisites
1.1 lukem 830: will be built in the proper order.
831: .
1.7 lukem 832: .It Sy distribution
833: Do a
834: .Dq make build ,
835: and then install a full distribution into
1.9 lukem 836: .Sy DESTDIR ,
837: including files in
1.14 lukem 838: .Sy DESTDIR Ns Pa /dev ,
839: .Sy DESTDIR Ns Pa /etc ,
840: .Sy DESTDIR Ns Pa /root
1.9 lukem 841: and
1.14 lukem 842: .Sy DESTDIR Ns Pa /var .
1.7 lukem 843: .
844: .It Sy buildworld
845: As per
846: .Dq make distribution ,
847: except that it ensures that
848: .Sy DESTDIR
849: is not the root directory.
850: .
851: .It Sy installworld
852: Install the distribution from
853: .Sy DESTDIR
854: to
855: .Sy INSTALLWORLDDIR
856: (which defaults to the root directory).
857: Ensures that
858: .Sy INSTALLWORLDDIR
1.37 jmc 859: is not the root directory if cross compiling.
1.7 lukem 860: .Pp
861: .Em Note :
862: It is highly recommended that you upgrade your kernel and reboot
863: before performing this operation.
864: .
1.12 lukem 865: .It Sy sets
866: Create distribution sets from
867: .Sy DESTDIR
868: into
1.14 lukem 869: .Sy RELEASEDIR/MACHINE Ns Pa /binary/sets .
1.12 lukem 870: Should be run after
871: .Dq make distribution
872: (as
873: .Dq make build
874: does not install all of the required files).
875: .
1.18 lukem 876: .It Sy sourcesets
877: Create source sets of the source tree into
878: .Sy RELEASEDIR Ns Pa /source/sets .
879: .
1.40 apb 880: .It Sy syspkgs
881: Create syspkgs from
882: .Sy DESTDIR
883: into
884: .Sy RELEASEDIR/MACHINE Ns Pa /binary/syspkgs .
885: Should be run after
886: .Dq make distribution
887: (as
888: .Dq make build
889: does not install all of the required files).
890: .
1.1 lukem 891: .It Sy release
892: Do a
1.9 lukem 893: .Dq make distribution ,
1.12 lukem 894: build kernels, distribution media, and install sets
895: (this as per
896: .Dq make sets ) ,
897: and
1.1 lukem 898: then package the system into a standard release layout as described by
899: .Xr release 7 .
900: This requires that
901: .Sy RELEASEDIR
902: be set (see above).
903: .
904: .It Sy regression-tests
905: Can only be run after building the regression tests in the directory
906: .Dq regress .
907: Runs the compiled regression tests on the local host.
908: .
909: .El
910: .
911: .Ss The \*qbuild.sh\*q script
912: .
913: This script file is a Bourne shell script designed to build the
914: entire
915: .Nx
916: system on any host with a Bourne shell in
917: .Sy /bin/sh ,
1.6 wiz 918: including many that are not POSIX compliant.
919: Note that if a host system's
1.1 lukem 920: .Sy /bin/sh
921: is unusually old and broken, the Korn Shell
922: .Sy ( /bin/ksh ) ,
923: if available, may be a usable alternative.
924: .Pp
925: All cross-compile builds, and most native builds, of the entire system
926: should make use of
927: .Sy build.sh
928: rather than just running
929: .Dq make .
930: This way, the
931: .Xr make 1
932: program will be bootstrapped properly, in case the host system has an
933: older or incompatible
934: .Dq make
935: program.
936: .Pp
937: When compiling the entire system via
938: .Sy build.sh ,
939: many
940: .Xr make 1
941: variables are set for you in order to help encapsulate the build
1.6 wiz 942: process.
943: In the list of options below, variables that are automatically set by
1.1 lukem 944: .Sy build.sh
945: are noted where applicable.
1.9 lukem 946: .
1.1 lukem 947: .Pp
1.9 lukem 948: The following operations are supported by
1.1 lukem 949: .Sy build.sh :
950: .
1.9 lukem 951: .Bl -tag -width "distribution"
952: .
953: .It Sy build
954: Build the system as per
955: .Dq make build .
956: This option implies the
957: .Sy obj
958: and
959: .Sy tools
960: operations.
961: .
962: .It Sy distribution
963: Build a full distribution as per
964: .Dq make distribution .
965: This option implies the
966: .Sy build
967: operation.
968: .
969: .It Sy release
970: Build a full release as per
971: .Dq make release .
972: This option implies the
973: .Sy distribution
974: operation.
975: .
1.10 lukem 976: .It Sy makewrapper
977: Create the
1.13 lukem 978: .Sy \*[toolprefix]make-MACHINE
1.10 lukem 979: wrapper.
980: This operation is automatically performed for any of the other
981: operations.
982: .
1.9 lukem 983: .It Sy obj
984: Perform
985: .Dq make obj .
1.11 lukem 986: .
1.9 lukem 987: .It Sy tools
988: Build and install the host tools from
989: .Pa src/tools .
1.22 lukem 990: .
991: .It Sy install Ns = Ns Ar idir
992: Install the contents of
993: .Sy DESTDIR
994: to
995: .Ar idir ,
996: using
997: .Dq make installworld .
998: .
1.9 lukem 999: .It Sy kernel Ns = Ns Ar kconf
1000: Build a new kernel.
1001: The
1002: .Ar kconf
1003: argument is the name of a configuration file suitable
1004: for use by
1.39 peter 1005: .Xr config 1 .
1.9 lukem 1006: If
1007: .Ar kconf
1008: does not contain any
1009: .Sq /
1010: characters, the configuration file is expected to be found in the
1011: .Sy KERNCONFDIR
1012: directory, which is typically
1013: .Sy sys/arch/MACHINE/conf .
1014: The new kernel will be built in a subdirectory of
1015: .Sy KERNOBJDIR ,
1016: which is typically
1017: .Sy sys/arch/MACHINE/compile
1018: or an associated object directory.
1019: In order to ensure that the kernel is built using up-to-date tools,
1020: it is strongly recommended that the tools be rebuilt (using the
1021: .Sy tools
1022: operation).
1023: .
1.22 lukem 1024: .It Sy releasekernel Ns = Ns Ar kconf
1025: Install a
1026: .Xr gzip 1 Ns ed
1027: copy of the kernel built by
1028: .Sy kernel Ns = Ns Ar kconf
1029: into
1030: .Sy RELEASEDIR/MACHINE Ns Pa /binary/kernel ,
1031: usually as
1032: .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
1033: although the
1034: .Dq Pa netbsd
1035: prefix is determined from the
1036: .Dq Sy config
1037: directives in
1038: .Ar kconf .
1.9 lukem 1039: .
1.11 lukem 1040: .It Sy sets
1041: Perform
1042: .Dq make sets .
1.18 lukem 1043: .
1044: .It Sy sourcesets
1045: Perform
1046: .Dq make sourcesets .
1047: .
1.40 apb 1048: .It Sy syspkgs
1049: Perform
1050: .Dq make syspkgs .
1051: .
1.9 lukem 1052: .El
1053: .
1054: .Pp
1055: The following command line options alter the behaviour of the
1056: .Sy build.sh
1057: operations described above:
1058: .
1.1 lukem 1059: .Bl -tag -width "-T tools"
1060: .
1.4 lukem 1061: .It Fl a Ar arch
1.1 lukem 1062: Set the value of
1063: .Sy MACHINE_ARCH
1064: to
1.4 lukem 1065: .Ar arch .
1.1 lukem 1066: .
1.4 lukem 1067: .It Fl B Ar buildid
1.1 lukem 1068: Set the value of
1069: .Sy BUILDID
1070: to
1.4 lukem 1071: .Ar buildid .
1.1 lukem 1072: This will also append the build idenfitier to the name of the
1073: .Dq make
1074: wrapper script so that the resulting name is of the form
1.13 lukem 1075: .Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1.1 lukem 1076: .
1.4 lukem 1077: .It Fl D Ar dest
1078: Set the value of
1079: .Sy DESTDIR
1080: to
1081: .Ar dest .
1082: .
1.5 lukem 1083: .It Fl E
1084: Set
1085: .Sq expert
1.10 lukem 1086: mode.
1087: This overrides various sanity checks, and allows:
1.5 lukem 1088: .Sy DESTDIR
1.10 lukem 1089: does not have to be set to a non-root path for builds,
1090: and
1.25 lukem 1091: .Sy MKUNPRIVED=yes
1.10 lukem 1092: does not have to be set when building as a non-root user.
1093: .Pp
1094: .Em Note :
1095: It is highly recommended that you know what you are doing when
1096: you use this option.
1.7 lukem 1097: .
1.36 wiz 1098: .It Fl h
1099: Print a help message.
1100: .
1.4 lukem 1101: .It Fl j Ar njob
1.1 lukem 1102: Passed through to
1103: .Xr make 1 .
1104: Makefiles should use .WAIT or have explicit dependancies
1105: as necessary to enforce build ordering.
1106: If you see build failures with -j, please save complete build logs
1107: so the failures can be analyzed.
1108: .
1.4 lukem 1109: .It Fl M Ar obj
1110: Set
1111: .Sy MAKEOBJDIRPREFIX
1112: to
1113: .Ar obj .
1.27 lukem 1114: Unsets
1115: .Sy MAKEOBJDIR .
1.4 lukem 1116: .
1117: .It Fl m Ar mach
1.1 lukem 1118: Set the value of
1119: .Sy MACHINE
1120: to
1.4 lukem 1121: .Ar mach .
1.1 lukem 1122: This will also override any value of
1123: .Sy MACHINE_ARCH
1124: in the process environment with a value deduced from
1.4 lukem 1125: .Ar mach ,
1.1 lukem 1126: unless
1.4 lukem 1127: .Fl a
1.20 lukem 1128: is specified, or
1129: .Ar mach
1130: is a special case listed below.
1.6 wiz 1131: All cross builds require
1.4 lukem 1132: .Fl m ,
1.1 lukem 1133: but if unset on a NetBSD host, the host's value of MACHINE will be
1134: detected and used automatically.
1.20 lukem 1135: .Pp
1136: Some machines support multiple values for
1137: .Sy MACHINE_ARCH .
1138: For a given value of
1139: .Ar mach ,
1140: the following
1141: .Sy MACHINE
1142: and
1143: .Sy MACHINE_ARCH
1144: values will result:
1145: .Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
1.24 lukem 1146: .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
1.20 lukem 1147: .It evbmips Ta evbmips Ta (not set)
1148: .It evbmips-eb Ta evbmips Ta mipseb
1149: .It evbmips-el Ta evbmips Ta mipsel
1150: .It evbsh3 Ta evbsh3 Ta (not set)
1151: .It evbsh3-eb Ta evbsh3 Ta sh3eb
1152: .It evbsh3-el Ta evbsh3 Ta sh3el
1153: .It sbmips Ta sbmips Ta (not set)
1154: .It sbmips-eb Ta sbmips Ta mipseb
1155: .It sbmips-el Ta sbmips Ta mipsel
1.30 lukem 1156: .El
1157: .
1158: .It Fl N Ar noiselevel
1159: Set the
1160: .Dq noisyness
1.31 lukem 1161: level of the build, by setting
1162: .Sy MAKEVERBOSE
1163: to
1164: .Ar noiselevel .
1.1 lukem 1165: .
1.4 lukem 1166: .It Fl n
1.1 lukem 1167: Show the commands that would be executed by
1168: .Sy build.sh ,
1.6 wiz 1169: but do not make any changes.
1170: This is similar in concept to
1.1 lukem 1171: .Dq make -n .
1172: .
1.4 lukem 1173: .It Fl O Ar obj
1.1 lukem 1174: Create an appropriate transform macro for
1175: .Sy MAKEOBJDIR
1176: that will place the built object files under
1.4 lukem 1177: .Ar obj .
1.1 lukem 1178: For instance, a setting of
1179: .Sy /usr/obj
1180: will place build-time files under
1.27 lukem 1181: .Sy /usr/obj/bin ,
1182: .Sy /usr/obj/lib ,
1183: .Sy /usr/obj/usr.bin ,
1.1 lukem 1184: and so forth.
1.27 lukem 1185: Unsets
1186: .Sy MAKEOBJDIRPREFIX .
1.1 lukem 1187: .
1.4 lukem 1188: .It Fl o
1189: Set the value of
1190: .Sy MKOBJDIRS
1191: to
1192: .Dq no .
1.21 lukem 1193: Otherwise, it will be automatically set to
1194: .Dq yes
1195: (which is opposite to the default behaviour).
1.4 lukem 1196: .
1197: .It Fl R Ar rel
1.1 lukem 1198: Set the value of
1199: .Sy RELEASEDIR
1200: to
1.4 lukem 1201: .Ar rel .
1.1 lukem 1202: .
1.4 lukem 1203: .It Fl r
1204: Remove the contents of
1205: .Sy DESTDIR
1206: and
1207: .Sy TOOLDIR
1.6 wiz 1208: before building (provides a clean starting point).
1209: This will skip deleting
1.4 lukem 1210: .Sy DESTDIR
1211: if building on a native system to the root directory.
1212: .
1213: .It Fl T Ar tools
1.1 lukem 1214: Set the value of
1215: .Sy TOOLDIR
1216: to
1.4 lukem 1217: .Ar tools .
1.1 lukem 1218: If set, the bootstrap
1219: .Dq make
1220: will only be rebuilt as needed (when the source files for
1221: .Xr make 1
1222: change).
1223: .
1.4 lukem 1224: .It Fl U
1.25 lukem 1225: Set
1226: .Sy MKUNPRIVED=yes .
1.1 lukem 1227: .
1.4 lukem 1228: .It Fl u
1.25 lukem 1229: Set
1230: .Sy MKUPDATE=yes .
1.8 lukem 1231: .
1232: .It Xo
1233: .Fl V
1234: .Sm off
1235: .Ar var
1236: .Li =
1237: .Op Ar value
1238: .Sm on
1239: .Xc
1.27 lukem 1240: Set the environment variable
1.8 lukem 1241: .Ar var
1.27 lukem 1242: to an optional
1243: .Ar value .
1244: This is propagated to the
1245: .Sy \*[toolprefix]make
1246: wrapper.
1.4 lukem 1247: .
1248: .It Fl w Ar wrapper
1.27 lukem 1249: Create the
1250: .Sy \*[toolprefix]make
1251: wrapper script (see below) in a custom location,
1.4 lukem 1252: specified by
1253: .Ar wrapper .
1254: This allows, for instance, to place the wrapper in
1255: .Sy PATH
1.6 wiz 1256: automatically.
1257: Note that
1.4 lukem 1258: .Ar wrapper
1259: is the full name of the file, not just a directory name.
1260: .
1.34 lukem 1261: .It Fl X Ar x11src
1262: Set the value of
1263: .Sy X11SRCDIR
1264: to
1265: .Ar x11src .
1266: .
1267: .It Fl x
1268: Set
1269: .Sy MKX11=yes .
1270: .
1.27 lukem 1271: .It Fl Z Ar var
1272: Unset ("zap") the environment variable
1273: .Ar var .
1274: This is propagated to the
1275: .Sy \*[toolprefix]make
1276: wrapper.
1277: .
1.1 lukem 1278: .El
1279: .
1.13 lukem 1280: .Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
1.1 lukem 1281: .
1282: If using the
1283: .Sy build.sh
1284: script to build
1285: .Nx ,
1286: a
1.13 lukem 1287: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1288: script will be created in
1289: .Sy TOOLDIR/bin
1290: upon the first build to assist in building subtrees on a cross-compile
1291: host.
1292: .Pp
1.13 lukem 1293: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1294: can be invoked in lieu of
1295: .Xr make 1 ,
1296: and will instead call the up-to-date version of
1.13 lukem 1297: .Dq \*[toolprefix]make
1.1 lukem 1298: installed into
1299: .Sy TOOLDIR/bin
1300: with several key variables pre-set, including
1301: .Sy MACHINE , MACHINE_ARCH ,
1302: and
1303: .Sy TOOLDIR .
1.27 lukem 1304: .Sy build.sh
1305: will also set variables specified with
1306: .Fl V ,
1307: and unset variables specified with
1308: .Fl Z .
1309: .Pp
1.1 lukem 1310: This script can be symlinked into a directory listed in
1311: .Sy PATH ,
1312: or called with an absolute path.
1.2 lukem 1313: .
1314: .Sh EXAMPLES
1.10 lukem 1315: .
1.15 lukem 1316: .Bl -enum
1.9 lukem 1317: .
1.15 lukem 1318: .It
1.29 lukem 1319: .Li "% ./build.sh tools kernel=GENERIC"
1.15 lukem 1320: .Pp
1.2 lukem 1321: Build a new toolchain, and use the new toolchain to
1322: configure and build a new GENERIC kernel.
1.9 lukem 1323: .
1.15 lukem 1324: .It
1.29 lukem 1325: .Li "% ./build.sh -U distribution"
1.15 lukem 1326: .Pp
1.2 lukem 1327: Using unprivileged mode,
1.17 lukem 1328: build a complete distribution to a
1329: .Sy DESTDIR
1330: directory that
1331: .Sy build.sh
1332: selects (and will display).
1.9 lukem 1333: .
1.15 lukem 1334: .It
1.17 lukem 1335: .Li "# ./build.sh -U install=/"
1.15 lukem 1336: .Pp
1.16 lukem 1337: As root, install to
1338: .Pa /
1339: the distribution that was built
1340: by example 2.
1.15 lukem 1341: Even though this is run as root,
1.9 lukem 1342: .Fl U
1343: is required so that the permissions stored in
1.17 lukem 1344: .Sy DESTDIR Ns Pa /METALOG
1.9 lukem 1345: are correctly applied to the files as they're copied to
1.15 lukem 1346: .Pa / .
1.9 lukem 1347: .
1.15 lukem 1348: .It
1.29 lukem 1349: .Li "% ./build.sh -U -u release"
1.15 lukem 1350: .Pp
1.2 lukem 1351: Using unprivileged mode,
1.17 lukem 1352: build a complete release to
1353: .Sy DESTDIR
1354: and
1355: .Sy RELEASEDIR
1356: directories that
1357: .Sy build.sh
1358: selects (and will display).
1.25 lukem 1359: .Sy MKUPDATE=yes
1.15 lukem 1360: .Pq Fl u
1361: is set to prevent the
1362: .Dq make cleandir ,
1363: so that if this is run after example 2, it doesn't need to redo that
1364: portion of the release build.
1.2 lukem 1365: .El
1.1 lukem 1366: .
1367: .Sh OBSOLETE VARIABLES
1368: .
1369: .Bl -tag -width "NBUILDJOBS"
1370: .
1371: .It Sy NBUILDJOBS
1372: Use the
1373: .Xr make 1
1374: option
1.4 lukem 1375: .Fl j ,
1.1 lukem 1376: instead.
1377: .
1378: .It Sy USE_NEW_TOOLCHAIN
1379: The new toolchain is now the default.
1380: To disable, use
1381: .Sy TOOLCHAIN_MISSING=yes .
1382: .El
1383: .Sh SEE ALSO
1384: .Xr make 1 ,
1385: .Xr hier 7 ,
1386: .Xr release 7
1387: .
1388: .Sh HISTORY
1389: .
1390: The
1391: .Nm build.sh
1392: based build scheme was introduced for
1393: .Nx 1.6
1394: as
1395: .Sy USE_NEW_TOOLCHAIN ,
1396: and re-worked to
1397: .Sy TOOLCHAIN_MISSING
1398: after that.
1399: .
1400: .Sh BUGS
1401: .
1402: A few platforms are not yet using this build system.
CVSweb <webmaster@jp.NetBSD.org>