Annotation of src/doc/BUILDING.mdoc, Revision 1.42
1.42 ! apb 1: .\" $NetBSD: BUILDING.mdoc,v 1.41 2006/01/12 21:22:30 wiz 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: .
1.42 ! apb 904: .It iso-image
! 905: Create a CD-ROM image in
! 906: .Sy RELEASEDIR/MACHINE Ns Pa /installation/cdrom .
! 907: RELEASEDIR must already have been populated by
! 908: .Dq make release
! 909: or equivalent.
! 910: This requires the
! 911: .Xr mkisofs 1
! 912: utility, which is not part of
! 913: .Nx ,
! 914: but which can be installed from
! 915: .Pa pkgsrc/sysutils/cdrecord .
! 916: .
1.1 lukem 917: .It Sy regression-tests
918: Can only be run after building the regression tests in the directory
919: .Dq regress .
920: Runs the compiled regression tests on the local host.
921: .
922: .El
923: .
924: .Ss The \*qbuild.sh\*q script
925: .
926: This script file is a Bourne shell script designed to build the
927: entire
928: .Nx
929: system on any host with a Bourne shell in
930: .Sy /bin/sh ,
1.6 wiz 931: including many that are not POSIX compliant.
932: Note that if a host system's
1.1 lukem 933: .Sy /bin/sh
934: is unusually old and broken, the Korn Shell
935: .Sy ( /bin/ksh ) ,
936: if available, may be a usable alternative.
937: .Pp
938: All cross-compile builds, and most native builds, of the entire system
939: should make use of
940: .Sy build.sh
941: rather than just running
942: .Dq make .
943: This way, the
944: .Xr make 1
945: program will be bootstrapped properly, in case the host system has an
946: older or incompatible
947: .Dq make
948: program.
949: .Pp
950: When compiling the entire system via
951: .Sy build.sh ,
952: many
953: .Xr make 1
954: variables are set for you in order to help encapsulate the build
1.6 wiz 955: process.
956: In the list of options below, variables that are automatically set by
1.1 lukem 957: .Sy build.sh
958: are noted where applicable.
1.9 lukem 959: .
1.1 lukem 960: .Pp
1.9 lukem 961: The following operations are supported by
1.1 lukem 962: .Sy build.sh :
963: .
1.9 lukem 964: .Bl -tag -width "distribution"
965: .
966: .It Sy build
967: Build the system as per
968: .Dq make build .
969: This option implies the
970: .Sy obj
971: and
972: .Sy tools
973: operations.
974: .
975: .It Sy distribution
976: Build a full distribution as per
977: .Dq make distribution .
978: This option implies the
979: .Sy build
980: operation.
981: .
982: .It Sy release
983: Build a full release as per
984: .Dq make release .
985: This option implies the
986: .Sy distribution
987: operation.
988: .
1.10 lukem 989: .It Sy makewrapper
990: Create the
1.13 lukem 991: .Sy \*[toolprefix]make-MACHINE
1.10 lukem 992: wrapper.
993: This operation is automatically performed for any of the other
994: operations.
995: .
1.9 lukem 996: .It Sy obj
997: Perform
998: .Dq make obj .
1.11 lukem 999: .
1.9 lukem 1000: .It Sy tools
1001: Build and install the host tools from
1002: .Pa src/tools .
1.22 lukem 1003: .
1004: .It Sy install Ns = Ns Ar idir
1005: Install the contents of
1006: .Sy DESTDIR
1007: to
1008: .Ar idir ,
1009: using
1010: .Dq make installworld .
1011: .
1.9 lukem 1012: .It Sy kernel Ns = Ns Ar kconf
1013: Build a new kernel.
1014: The
1015: .Ar kconf
1016: argument is the name of a configuration file suitable
1017: for use by
1.39 peter 1018: .Xr config 1 .
1.9 lukem 1019: If
1020: .Ar kconf
1021: does not contain any
1022: .Sq /
1023: characters, the configuration file is expected to be found in the
1024: .Sy KERNCONFDIR
1025: directory, which is typically
1026: .Sy sys/arch/MACHINE/conf .
1027: The new kernel will be built in a subdirectory of
1028: .Sy KERNOBJDIR ,
1029: which is typically
1030: .Sy sys/arch/MACHINE/compile
1031: or an associated object directory.
1032: In order to ensure that the kernel is built using up-to-date tools,
1033: it is strongly recommended that the tools be rebuilt (using the
1034: .Sy tools
1035: operation).
1036: .
1.22 lukem 1037: .It Sy releasekernel Ns = Ns Ar kconf
1038: Install a
1039: .Xr gzip 1 Ns ed
1040: copy of the kernel built by
1041: .Sy kernel Ns = Ns Ar kconf
1042: into
1043: .Sy RELEASEDIR/MACHINE Ns Pa /binary/kernel ,
1044: usually as
1045: .Pa netbsd- Ns Ar kconf Ns Pa .gz ,
1046: although the
1047: .Dq Pa netbsd
1048: prefix is determined from the
1049: .Dq Sy config
1050: directives in
1051: .Ar kconf .
1.9 lukem 1052: .
1.11 lukem 1053: .It Sy sets
1054: Perform
1055: .Dq make sets .
1.18 lukem 1056: .
1057: .It Sy sourcesets
1058: Perform
1059: .Dq make sourcesets .
1060: .
1.40 apb 1061: .It Sy syspkgs
1062: Perform
1063: .Dq make syspkgs .
1064: .
1.42 ! apb 1065: .It Sy iso-image
! 1066: Perform
! 1067: .Dq make iso-image .
! 1068: .
1.9 lukem 1069: .El
1070: .
1071: .Pp
1072: The following command line options alter the behaviour of the
1073: .Sy build.sh
1074: operations described above:
1075: .
1.1 lukem 1076: .Bl -tag -width "-T tools"
1077: .
1.4 lukem 1078: .It Fl a Ar arch
1.1 lukem 1079: Set the value of
1080: .Sy MACHINE_ARCH
1081: to
1.4 lukem 1082: .Ar arch .
1.1 lukem 1083: .
1.4 lukem 1084: .It Fl B Ar buildid
1.1 lukem 1085: Set the value of
1086: .Sy BUILDID
1087: to
1.4 lukem 1088: .Ar buildid .
1.1 lukem 1089: This will also append the build idenfitier to the name of the
1090: .Dq make
1091: wrapper script so that the resulting name is of the form
1.13 lukem 1092: .Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
1.1 lukem 1093: .
1.4 lukem 1094: .It Fl D Ar dest
1095: Set the value of
1096: .Sy DESTDIR
1097: to
1098: .Ar dest .
1099: .
1.5 lukem 1100: .It Fl E
1101: Set
1102: .Sq expert
1.10 lukem 1103: mode.
1104: This overrides various sanity checks, and allows:
1.5 lukem 1105: .Sy DESTDIR
1.10 lukem 1106: does not have to be set to a non-root path for builds,
1107: and
1.25 lukem 1108: .Sy MKUNPRIVED=yes
1.10 lukem 1109: does not have to be set when building as a non-root user.
1110: .Pp
1111: .Em Note :
1112: It is highly recommended that you know what you are doing when
1113: you use this option.
1.7 lukem 1114: .
1.36 wiz 1115: .It Fl h
1116: Print a help message.
1117: .
1.4 lukem 1118: .It Fl j Ar njob
1.1 lukem 1119: Passed through to
1120: .Xr make 1 .
1121: Makefiles should use .WAIT or have explicit dependancies
1122: as necessary to enforce build ordering.
1123: If you see build failures with -j, please save complete build logs
1124: so the failures can be analyzed.
1125: .
1.4 lukem 1126: .It Fl M Ar obj
1127: Set
1128: .Sy MAKEOBJDIRPREFIX
1129: to
1130: .Ar obj .
1.27 lukem 1131: Unsets
1132: .Sy MAKEOBJDIR .
1.4 lukem 1133: .
1134: .It Fl m Ar mach
1.1 lukem 1135: Set the value of
1136: .Sy MACHINE
1137: to
1.4 lukem 1138: .Ar mach .
1.1 lukem 1139: This will also override any value of
1140: .Sy MACHINE_ARCH
1141: in the process environment with a value deduced from
1.4 lukem 1142: .Ar mach ,
1.1 lukem 1143: unless
1.4 lukem 1144: .Fl a
1.20 lukem 1145: is specified, or
1146: .Ar mach
1147: is a special case listed below.
1.6 wiz 1148: All cross builds require
1.4 lukem 1149: .Fl m ,
1.1 lukem 1150: but if unset on a NetBSD host, the host's value of MACHINE will be
1151: detected and used automatically.
1.20 lukem 1152: .Pp
1153: Some machines support multiple values for
1154: .Sy MACHINE_ARCH .
1155: For a given value of
1156: .Ar mach ,
1157: the following
1158: .Sy MACHINE
1159: and
1160: .Sy MACHINE_ARCH
1161: values will result:
1162: .Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
1.24 lukem 1163: .It Sy mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
1.20 lukem 1164: .It evbmips Ta evbmips Ta (not set)
1165: .It evbmips-eb Ta evbmips Ta mipseb
1166: .It evbmips-el Ta evbmips Ta mipsel
1167: .It evbsh3 Ta evbsh3 Ta (not set)
1168: .It evbsh3-eb Ta evbsh3 Ta sh3eb
1169: .It evbsh3-el Ta evbsh3 Ta sh3el
1170: .It sbmips Ta sbmips Ta (not set)
1171: .It sbmips-eb Ta sbmips Ta mipseb
1172: .It sbmips-el Ta sbmips Ta mipsel
1.30 lukem 1173: .El
1174: .
1175: .It Fl N Ar noiselevel
1176: Set the
1177: .Dq noisyness
1.31 lukem 1178: level of the build, by setting
1179: .Sy MAKEVERBOSE
1180: to
1181: .Ar noiselevel .
1.1 lukem 1182: .
1.4 lukem 1183: .It Fl n
1.1 lukem 1184: Show the commands that would be executed by
1185: .Sy build.sh ,
1.6 wiz 1186: but do not make any changes.
1187: This is similar in concept to
1.1 lukem 1188: .Dq make -n .
1189: .
1.4 lukem 1190: .It Fl O Ar obj
1.1 lukem 1191: Create an appropriate transform macro for
1192: .Sy MAKEOBJDIR
1193: that will place the built object files under
1.4 lukem 1194: .Ar obj .
1.1 lukem 1195: For instance, a setting of
1196: .Sy /usr/obj
1197: will place build-time files under
1.27 lukem 1198: .Sy /usr/obj/bin ,
1199: .Sy /usr/obj/lib ,
1200: .Sy /usr/obj/usr.bin ,
1.1 lukem 1201: and so forth.
1.27 lukem 1202: Unsets
1203: .Sy MAKEOBJDIRPREFIX .
1.1 lukem 1204: .
1.4 lukem 1205: .It Fl o
1206: Set the value of
1207: .Sy MKOBJDIRS
1208: to
1209: .Dq no .
1.21 lukem 1210: Otherwise, it will be automatically set to
1211: .Dq yes
1212: (which is opposite to the default behaviour).
1.4 lukem 1213: .
1214: .It Fl R Ar rel
1.1 lukem 1215: Set the value of
1216: .Sy RELEASEDIR
1217: to
1.4 lukem 1218: .Ar rel .
1.1 lukem 1219: .
1.4 lukem 1220: .It Fl r
1221: Remove the contents of
1222: .Sy DESTDIR
1223: and
1224: .Sy TOOLDIR
1.6 wiz 1225: before building (provides a clean starting point).
1226: This will skip deleting
1.4 lukem 1227: .Sy DESTDIR
1228: if building on a native system to the root directory.
1229: .
1230: .It Fl T Ar tools
1.1 lukem 1231: Set the value of
1232: .Sy TOOLDIR
1233: to
1.4 lukem 1234: .Ar tools .
1.1 lukem 1235: If set, the bootstrap
1236: .Dq make
1237: will only be rebuilt as needed (when the source files for
1238: .Xr make 1
1239: change).
1240: .
1.4 lukem 1241: .It Fl U
1.25 lukem 1242: Set
1243: .Sy MKUNPRIVED=yes .
1.1 lukem 1244: .
1.4 lukem 1245: .It Fl u
1.25 lukem 1246: Set
1247: .Sy MKUPDATE=yes .
1.8 lukem 1248: .
1249: .It Xo
1250: .Fl V
1251: .Sm off
1252: .Ar var
1253: .Li =
1254: .Op Ar value
1255: .Sm on
1256: .Xc
1.27 lukem 1257: Set the environment variable
1.8 lukem 1258: .Ar var
1.27 lukem 1259: to an optional
1260: .Ar value .
1261: This is propagated to the
1262: .Sy \*[toolprefix]make
1263: wrapper.
1.4 lukem 1264: .
1265: .It Fl w Ar wrapper
1.27 lukem 1266: Create the
1267: .Sy \*[toolprefix]make
1268: wrapper script (see below) in a custom location,
1.4 lukem 1269: specified by
1270: .Ar wrapper .
1271: This allows, for instance, to place the wrapper in
1272: .Sy PATH
1.6 wiz 1273: automatically.
1274: Note that
1.4 lukem 1275: .Ar wrapper
1276: is the full name of the file, not just a directory name.
1277: .
1.34 lukem 1278: .It Fl X Ar x11src
1279: Set the value of
1280: .Sy X11SRCDIR
1281: to
1282: .Ar x11src .
1283: .
1284: .It Fl x
1285: Set
1286: .Sy MKX11=yes .
1287: .
1.27 lukem 1288: .It Fl Z Ar var
1289: Unset ("zap") the environment variable
1290: .Ar var .
1291: This is propagated to the
1292: .Sy \*[toolprefix]make
1293: wrapper.
1294: .
1.1 lukem 1295: .El
1296: .
1.13 lukem 1297: .Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
1.1 lukem 1298: .
1299: If using the
1300: .Sy build.sh
1301: script to build
1302: .Nx ,
1303: a
1.13 lukem 1304: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1305: script will be created in
1306: .Sy TOOLDIR/bin
1307: upon the first build to assist in building subtrees on a cross-compile
1308: host.
1309: .Pp
1.13 lukem 1310: .Sy \*[toolprefix]make-MACHINE
1.1 lukem 1311: can be invoked in lieu of
1312: .Xr make 1 ,
1313: and will instead call the up-to-date version of
1.13 lukem 1314: .Dq \*[toolprefix]make
1.1 lukem 1315: installed into
1316: .Sy TOOLDIR/bin
1317: with several key variables pre-set, including
1318: .Sy MACHINE , MACHINE_ARCH ,
1319: and
1320: .Sy TOOLDIR .
1.27 lukem 1321: .Sy build.sh
1322: will also set variables specified with
1323: .Fl V ,
1324: and unset variables specified with
1325: .Fl Z .
1326: .Pp
1.1 lukem 1327: This script can be symlinked into a directory listed in
1328: .Sy PATH ,
1329: or called with an absolute path.
1.2 lukem 1330: .
1331: .Sh EXAMPLES
1.10 lukem 1332: .
1.15 lukem 1333: .Bl -enum
1.9 lukem 1334: .
1.15 lukem 1335: .It
1.29 lukem 1336: .Li "% ./build.sh tools kernel=GENERIC"
1.15 lukem 1337: .Pp
1.2 lukem 1338: Build a new toolchain, and use the new toolchain to
1339: configure and build a new GENERIC kernel.
1.9 lukem 1340: .
1.15 lukem 1341: .It
1.29 lukem 1342: .Li "% ./build.sh -U distribution"
1.15 lukem 1343: .Pp
1.2 lukem 1344: Using unprivileged mode,
1.17 lukem 1345: build a complete distribution to a
1346: .Sy DESTDIR
1347: directory that
1348: .Sy build.sh
1349: selects (and will display).
1.9 lukem 1350: .
1.15 lukem 1351: .It
1.17 lukem 1352: .Li "# ./build.sh -U install=/"
1.15 lukem 1353: .Pp
1.16 lukem 1354: As root, install to
1355: .Pa /
1356: the distribution that was built
1357: by example 2.
1.15 lukem 1358: Even though this is run as root,
1.9 lukem 1359: .Fl U
1360: is required so that the permissions stored in
1.17 lukem 1361: .Sy DESTDIR Ns Pa /METALOG
1.9 lukem 1362: are correctly applied to the files as they're copied to
1.15 lukem 1363: .Pa / .
1.9 lukem 1364: .
1.15 lukem 1365: .It
1.29 lukem 1366: .Li "% ./build.sh -U -u release"
1.15 lukem 1367: .Pp
1.2 lukem 1368: Using unprivileged mode,
1.17 lukem 1369: build a complete release to
1370: .Sy DESTDIR
1371: and
1372: .Sy RELEASEDIR
1373: directories that
1374: .Sy build.sh
1375: selects (and will display).
1.25 lukem 1376: .Sy MKUPDATE=yes
1.15 lukem 1377: .Pq Fl u
1378: is set to prevent the
1379: .Dq make cleandir ,
1380: so that if this is run after example 2, it doesn't need to redo that
1381: portion of the release build.
1.2 lukem 1382: .El
1.1 lukem 1383: .
1384: .Sh OBSOLETE VARIABLES
1385: .
1386: .Bl -tag -width "NBUILDJOBS"
1387: .
1388: .It Sy NBUILDJOBS
1389: Use the
1390: .Xr make 1
1391: option
1.4 lukem 1392: .Fl j ,
1.1 lukem 1393: instead.
1394: .
1395: .It Sy USE_NEW_TOOLCHAIN
1396: The new toolchain is now the default.
1397: To disable, use
1398: .Sy TOOLCHAIN_MISSING=yes .
1399: .El
1400: .Sh SEE ALSO
1401: .Xr make 1 ,
1402: .Xr hier 7 ,
1.42 ! apb 1403: .Xr release 7 ,
! 1404: .Pa pkgsrc/sysutils/cdrecord
1.1 lukem 1405: .
1406: .Sh HISTORY
1407: .
1408: The
1409: .Nm build.sh
1410: based build scheme was introduced for
1411: .Nx 1.6
1412: as
1413: .Sy USE_NEW_TOOLCHAIN ,
1414: and re-worked to
1415: .Sy TOOLCHAIN_MISSING
1416: after that.
1417: .
1418: .Sh BUGS
1419: .
1420: A few platforms are not yet using this build system.
CVSweb <webmaster@jp.NetBSD.org>