Annotation of src/BUILDING.txt, Revision 1.3
1.1 tv 1: BUILDING(8) NetBSD System Manager's Manual BUILDING(8)
2:
3: NAME
4: BUILDING - Procedure for building NetBSD from source code.
5:
6: STATUS
7: This document is a work-in-progress. As such, the information described
8: here may not match the reality of the build system as of this writing.
9: Once this document is completely in sync with reality, this paragraph
10: will be removed.
11:
12: Discrepancies between this documentation and the current reality of im-
13: plementation are noted specially, as with the note below:
14:
15: Note: This document applies only to platforms which use the new toolchain
16: as indicated by the setting of USE_NEW_TOOLCHAIN in /etc/mk.conf or
17: <bsd.own.mk>. Platforms which have not yet been switched to the new
18: toolchain should continue building traditionally, using the notes speci-
19: fied in the file UPDATING.
20:
21: REQUIREMENTS
22: NetBSD is designed to be buildable on most POSIX-compliant host systems.
23: The basic build procedure is the same whether compiling natively (on the
24: same NetBSD architecture) or cross compiling (on another architecture or
25: OS).
26:
27: This source tree contains a special subtree, ``tools'', which uses the
28: host system to create a build toolchain for the target architecture. The
29: host system must have at least C and C++ compilers in order to create the
30: toolchain (make is not required); all other tools are created as part of
31: the NetBSD build process.
32:
33: Note: A couple host toolchain components are not yet available in
34: the tools directory. Also, some tools use non-POSIX, non-ANSI C
35: extensions and need to be standardized. As a result, cross-compil-
36: ing from systems other than NetBSD is not currently supported.
37:
38: FILES
39: Source tree layout
40:
1.2 tv 41: BUILDING.mdoc This document (in -mdoc troff format; the original copy).
1.1 tv 42:
1.2 tv 43: BUILDING.html This document (in formatted HTML).
44:
45: BUILDING.txt This document (in plaintext).
1.1 tv 46:
47: Makefile The main Makefile for NetBSD; should only be run for na-
48: tive builds with an appropriately up-to-date version of
49: NetBSD make(1). (For building from out-of-date systems or
50: on a non-native host, see the build.sh shell script.)
51:
52: UPDATING Special notes for updating from an earlier revision of
53: NetBSD. It is important to read this file before every
54: build of an updated source tree.
55:
56: build.sh Bourne-compatible shell script used for building the host
57: build tools and the NetBSD system from scratch. Can be
58: used for both native and cross builds, and should be used
59: instead of make(1) for any source tree that is updated and
60: recompiled regularly.
61:
62: crypto/dist/, dist/, gnu/dist/
63: Sources imported verbatim from third parties, without man-
64: gling the existing build structure. Other source trees in
65: bin through usr.sbin use the NetBSD make(1) ``reachover''
66: Makefile semantics when building these programs for a na-
67: tive host.
68:
69: distrib/, etc/
70: Sources for items used when making a full release snap-
71: shot, such as files installed in /etc on the destination
72: system, boot media, and release notes.
73:
74: regress/ Regression test harness. Can be cross-compiled, but only
75: run natively.
76:
77: sys/ NetBSD kernel sources.
78:
79: tools/ ``Reachover'' build structure for the host build tools.
80: This has a special method of determining out-of-date sta-
81: tus.
82:
83: bin/ ... usr.sbin/
84: Sources to the NetBSD userland (non-kernel) programs. If
85: any of these directories are missing, they will be skipped
86: during the build.
87:
88: Build tree layout
89: The NetBSD build tree is described in hier(7), and the release layout is
90: described in release(7).
91:
92: CONFIGURATION
1.3 ! tv 93: "make" variables
1.1 tv 94: Several variables control the behavior of NetBSD builds. Unless other-
95: wise specified, these variables may be set in either the process environ-
96: ment or the make(1) configuration file specified by MAKECONF.
97:
98: DESTDIR Directory to contain the built NetBSD system. If set, spe-
99: cial options are passed to the compilation tools to prevent
100: their default use of the host system's /usr/include,
101: /usr/lib, and so forth. This pathname should not end with a
102: slash (/) character (for installation into the system's root
103: directory, set DESTDIR to an empty string).
104:
105: Default: Empty string if USETOOLS is ``yes''; unset other-
106: wise.
107:
108: MAKECONF The name of the make(1) configuration file. Only settable in
109: the process environment.
110:
111: Default: ``/etc/mk.conf''
112:
113: MKCATPAGES Can be set to ``yes'' or ``no''. Indicates whether prefor-
114: matted plaintext manual pages will be created during a build.
115:
116: Default: ``yes''
117:
118: MKCRYPTO Can be set to ``yes'' or ``no''. Indicates whether crypto-
119: graphic code will be included in a build; provided for the
120: benefit of countries that do not allow strong cryptography.
121: Will not affect use of the standard low-security password en-
122: cryption system, crypt(3).
123:
124: Default: ``yes''
125:
126: MKDOC Can be set to ``yes'' or ``no''. Indicates whether system
127: documentation destined for /usr/share/doc will be installed
128: during a build.
129:
130: Default: ``yes''
131:
132: MKINFO Can be set to ``yes'' or ``no''. Indicates whether GNU Info
133: files, used for the documentation for most of the compilation
134: tools, will be created and installed during a build.
135:
136: Default: ``yes''
137:
138: MKLINT Can be set to ``yes'' or ``no''. Indicates whether lint(1)
139: will be run against portions of the NetBSD source code during
140: the build, and whether lint libraries will be installed into
141: /usr/libdata/lint.
142:
143: Default: ``yes''
144:
145: MKMAN Can be set to ``yes'' or ``no''. Indicates whether manual
146: pages will be installed during a build.
147:
148: Default: ``yes''
149:
150: MKNLS Can be set to ``yes'' or ``no''. Indicates whether Native
151: Language System locale zone files will be compiled and in-
152: stalled during a build.
153:
154: Default: ``yes''
155:
156: MKOBJ Can be set to ``yes'' or ``no''. Indicates whether object
157: directories will be created when running ``make obj''. If
158: set to ``no'', then all built files will be located inside
159: the regular source tree.
160:
161: Default: ``yes''
162:
163: MKPIC Can be set to ``yes'' or ``no''. Indicates whether shared
164: objects and libraries will be created and installed during a
165: build. If set to ``no'', the entire built system will be
166: statically linked.
167:
168: Default: Platform dependent. As of this writing, all plat-
169: forms except sh3 default to ``yes''.
170:
171: MKPICINSTALL
172: Can be set to ``yes'' or ``no''. Indicates whether the ar(1)
173: format libraries (lib*_pic.a), used to generate shared li-
174: braries, are installed during a build.
175:
176: Default: ``yes''
177:
178: MKPROFILE Can be set to ``yes'' or ``no''. Indicates whether profiled
179: libraries (lib*_p.a) will be built and installed during a
180: build.
181:
182: Default: ``yes''; however, some platforms turn off MKPROFILE
183: by default at times due to toolchain problems with profiled
184: code.
185:
186: MKSHARE Can be set to ``yes'' or ``no''. Indicates whether files
187: destined to reside in /usr/share will be built and installed
188: during a build. If set to ``no'', then all of MKCATPAGES,
189: MKDOC, MKINFO, MKMAN, and MKNLS will be set to ``no'' uncon-
190: ditionally.
191:
192: Default: ``yes''
193:
194: TOOLDIR Directory to hold the host tools, once built. This directory
195: should be unique to a given host system and NetBSD source
196: tree. (However, multiple targets may share the same TOOLDIR;
197: the target-dependent files have unique names.) Must be set
198: if USETOOLS is ``yes''.
199:
200: Default: Unset.
201:
202: UPDATE If set, then all install operations intended to write to
203: DESTDIR will compare file timestamps before installing, and
204: skip the install phase if the destination files are up-to-
205: date. This also has implications on full builds (see next
206: subsection).
207:
208: Default: Unset.
209:
210: USETOOLS Indicates whether the tools specified by TOOLDIR should be
211: used as part of a build in progress. Must be set to ``yes''
212: if cross-compiling.
213:
214: yes Use the tools from TOOLDIR.
215:
216: no Do not use the tools from TOOLDIR, but refuse to build
217: native compilation tool components that are version-
218: specific for that tool.
219:
220: never Do not use the tools from TOOLDIR, even when building
221: native tool components. This is similar to the tradi-
222: tional NetBSD build method, but does not verify that
223: the compilation tools in use are up-to-date enough in
224: order to build the tree successfully. This may cause
225: build or runtime problems when building the whole
226: NetBSD source tree.
227:
228: Default: ``yes'' if building all or part of a whole NetBSD
229: source tree (detected automatically); ``no'' otherwise (to
230: preserve traditional semantics of the <bsd.*.mk> make(1) in-
231: clude files).
232:
233: Note: Currently, the ``no'' option functions similarly to the
234: ``never'' option. Proper checks will be added in the near
235: future to add the described functionality for version-specif-
236: ic tool components.
237:
1.3 ! tv 238: "make" variables for full builds
1.1 tv 239: These variables only affect the top level ``Makefile'' and do not manual-
240: ly building subtrees of the NetBSD source code.
241:
242: MKOBJDIRS Can be set to ``yes'' or ``no''. Indicates whether object
243: directories will be created automatically (via a ``make
244: obj'' pass) at the start of a build.
245:
246: Default: ``yes''
247:
248: MKTOOLS Indicates whether the host tools will be built and in-
249: stalled automatically if they are out-of-date.
250:
251: yes Build tools as needed into TOOLDIR, but only if the
252: tools in question are out-of-date.
253:
254: no Do not update the tools in TOOLDIR; halt the build
255: as a safety precaution if tools are out-of-date.
256:
257: always
258: Always rebuild the tools in TOOLDIR from scratch
259: during a build. This is similar to the standard
260: NetBSD source tree build method, but is not typi-
261: cally required for host tools.
262:
263: Default: ``no''
264:
265: NBUILDJOBS If set, specifies the number of parallel make(1) processes
266: that should be run simultaneously. This can speed up
267: builds on SMP machines, or machines with much more CPU
268: power than I/O availability. This should be used instead
269: of the make(1) option -j, in order to ensure proper order-
270: ing of build components.
271:
272: Default: Unset.
273:
274: NOCLEANDIR If set, avoids the ``make cleandir'' phase of a full
275: build. This has the effect of allowing only changed files
276: in a source tree to be recompiled. This can speed up
277: builds when updating only a few files in the tree.
278:
279: Default: Unset.
280:
281: NODISTRIBDIRS If set, avoids the ``make distrib-dirs'' phase of a full
282: build. This skips running mtree(1) on DESTDIR, useful on
283: systems where building as an unprivileged user, or where
284: it is known that the system-wide mtree files have not
285: changed.
286:
287: Default: Unset.
288:
289: NOINCLUDES If set, avoids the ``make includes'' phase of a full
290: build. This has the effect of preventing make(1) from
291: thinking that some programs are out-of-date simply because
292: the system include files have changed. However, this op-
293: tion should not be used when updating the entire NetBSD
294: source tree arbitrarily; it is suggested to use UPDATE in
295: that case.
296:
297: Default: Unset.
298:
299: RELEASEDIR If set, specifies the directory to which a release(7) lay-
300: out will be written at the end of a ``make release''.
301:
302: Default: Unset.
303:
304: UPDATE If set, then in addition to the effects described for UP-
305: DATE above, this implies the effects of NOCLEANDIR.
306:
307: BUILDING
1.3 ! tv 308: "make" command line options
1.1 tv 309: This is only a summary of options available to make(1); only the options
310: used most frequently with NetBSD builds are listed here.
311:
312: -m dir Specify the default directory for searching for system Make-
313: file segments, mainly the <bsd.*.mk> files. When building any
314: full NetBSD source tree, this should be set to the
315: ``share/mk'' directory in the source tree. (This is set auto-
316: matically when building from the top level.)
317:
318: -n Display the commands that would have been executed, but do not
319: actually execute them. This will still cause recursion to
320: take place.
321:
322: -v var Print make(1)'s idea of the value of var. Does not build any
323: targets.
324:
325: var=value Set the variable var to value, overriding any setting speci-
326: fied by the process environment, the MAKECONF configuration
327: file, or the system Makefile segments.
328:
1.3 ! tv 329: "make" targets
1.1 tv 330: These default targets may be built by running make(1) in any subtree of
331: the NetBSD source code. It is recommended that none of these be used
332: from the top level Makefile; as a specific exception, ``make obj'' and
333: ``make cleandir'' are useful in that context.
334:
335: all Build programs, libraries, and preformatted documentation.
336:
337: clean Remove program and library object code files.
338:
339: cleandir Same as clean, but also remove preformatted documentation, de-
340: pendency files generated by ``make depend'', and any other
341: files known to be created at build time. ``make distclean''
342: may be used as a synonym, for familiarity with a similar well-
343: known convention.
344:
345: depend Create dependency files (.depend) containing more detailed in-
346: formation about the dependencies of source code on header
347: files. Allows programs to be recompiled automatically when a
348: dependency changes.
349:
350: dependall Does a ``make depend'' immediately followed by a ``make all''.
351: This combined target recurses as an atomic unit, so that the
352: ``make depend'' phase can participate in make -j parallelism.
353:
354: includes Build and install system header files. Typically needed be-
355: fore any system libraries or programs can be built.
356:
357: install Install programs, libraries, and documentation into DESTDIR.
358:
359: lint Run lint(1) against the C source code, where appropriate, and
360: generate system-installed lint libraries.
361:
362: obj Create object directories to be used for built files, instead
363: of building directly in the source tree.
364:
365: tags Create ctags(1) searchable function lists usable by the ex(1)
366: and vi(1) text editors.
367:
1.3 ! tv 368: "make" targets for the top level
1.1 tv 369: Additional make(1) targets are usable specifically from the top source
370: level to facilitate building the entire NetBSD source tree.
371:
372: build Build the entire NetBSD system. This orders portions of the
373: source tree such that prerequisites will be built in the prop-
374: er order.
375:
376: release Do a ``make build'', then package the system into a standard
377: release layout as described by release(7). This requires that
378: RELEASEDIR be set (see above).
379:
380: regression-tests
381: Can only be run after building the regression tests in the di-
382: rectory ``regress''. Runs the compiled regression tests on
383: the local host.
384:
1.3 ! tv 385: The "build.sh" script
1.1 tv 386: This script file is a Bourne shell script designed to build the entire
387: NetBSD system on any host with a Bourne shell in /bin/sh, including many
388: that are not POSIX compliant. Note that if a host system's /bin/sh is
389: unusually old and broken, the Korn Shell (/bin/ksh), if available, may be
390: a usable alternative.
391:
392: All cross-compile builds, and most native builds, of the entire system
393: should make use of build.sh rather than just running ``make''. This way,
394: the make(1) program will be bootstrapped properly, in case the host sys-
395: tem has an older or incompatible ``make'' program.
396:
397: When compiling the entire system via build.sh, many make(1) variables are
398: set for you in order to help encapsulate the build process. In particu-
399: lar, both USETOOLS and MKTOOLS are set to ``yes'', and MACHINE_ARCH (if
400: unset) is deduced from the value of MACHINE.
401:
402: The variables DESTDIR, MACHINE, MACHINE_ARCH, and TOOLDIR are required in
403: order for build.sh to function, and thus they cannot be set in the con-
404: figuration file specified by MAKECONF. They may be set either in the
405: process environment, or via command line options to build.sh.
406:
407: The following are available command line options that may be supplied to
408: build.sh:
409:
410: -a arch Set the value of MACHINE_ARCH to arch.
411:
412: -D dest Set the value of DESTDIR to dest.
413:
414: -j njob Set the value of NBUILDJOBS to njob. This provides similar
415: functionality to the familiar ``make -j'', but preserves the
416: ordering of the top level ``make build''.
417:
418: -m mach Set the value of MACHINE to mach. This will also override any
419: value of MACHINE_ARCH in the process environment with a value
420: deduced from mach, unless -a is specified.
421:
422: -R rel Set the value of RELEASEDIR to rel. Setting this option will
423: make build.sh run ``make release'' instead of ``make build''.
424:
425: -r Remove the contents of DESTDIR and TOOLDIR before building
426: (provides a clean starting point).
427:
428: -T tools Set the value of TOOLDIR to tools.
429:
1.3 ! tv 430: The "nbmake-MACHINE" wrapper script
1.1 tv 431: If using the build.sh script to build NetBSD, a nbmake-MACHINE script
432: will be created in TOOLDIR/bin upon the first build to assist in building
433: subtrees on a cross-compile host.
434:
435: nbmake-MACHINE can be invoked in lieu of make(1), and will instead call
436: the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with sev-
437: eral key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR.
438: This script can be symlinked into a directory listed in PATH, or called
439: with an absolute path.
440:
441: SEE ALSO
442: make(1), hier(7), release(7)
443:
444: BUGS
445: Many platforms are not yet using the USE_NEW_TOOLCHAIN system.
446:
447: HISTORY
448: The USE_NEW_TOOLCHAIN based build scheme was introduced in the ``NetBSD-
449: current'' development sources between NetBSD 1.5 and NetBSD 1.6.
450:
451: NetBSD October 29, 2001 7
CVSweb <webmaster@jp.NetBSD.org>