head 1.7; access; symbols phil-wifi-20200421:1.7 phil-wifi-20200411:1.7 phil-wifi-20200406:1.7 pgoyette-compat-merge-20190127:1.7 pgoyette-compat-20190127:1.7 pgoyette-compat-20190118:1.7 pgoyette-compat-1226:1.7 pgoyette-compat-1126:1.7 pgoyette-compat-1020:1.7 pgoyette-compat-0930:1.7 pgoyette-compat-0906:1.7 pgoyette-compat-0728:1.7 pgoyette-compat-0625:1.7 pgoyette-compat-0521:1.7 pgoyette-compat-0502:1.7 pgoyette-compat-0422:1.7 pgoyette-compat-0415:1.7 pgoyette-compat-0407:1.7 pgoyette-compat-0330:1.7 pgoyette-compat-0322:1.7 pgoyette-compat-0315:1.7 pgoyette-compat:1.7.0.36 pgoyette-compat-base:1.7 prg-localcount2-base3:1.7 prg-localcount2-base2:1.7 prg-localcount2-base1:1.7 prg-localcount2:1.7.0.34 prg-localcount2-base:1.7 pgoyette-localcount-20170426:1.7 bouyer-socketcan-base1:1.7 pgoyette-localcount-20170320:1.7 bouyer-socketcan:1.7.0.32 bouyer-socketcan-base:1.7 pgoyette-localcount-20170107:1.7 pgoyette-localcount-20161104:1.7 localcount-20160914:1.7 pgoyette-localcount-20160806:1.7 pgoyette-localcount-20160726:1.7 pgoyette-localcount:1.7.0.30 pgoyette-localcount-base:1.7 netbsd-5-2-3-RELEASE:1.7 netbsd-5-1-5-RELEASE:1.7 yamt-pagecache-base9:1.7 yamt-pagecache-tag8:1.7 tls-earlyentropy:1.7.0.26 tls-earlyentropy-base:1.7 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.7 riastradh-drm2-base3:1.7 netbsd-5-2-2-RELEASE:1.7 netbsd-5-1-4-RELEASE:1.7 netbsd-5-2-1-RELEASE:1.7 netbsd-5-1-3-RELEASE:1.7 agc-symver:1.7.0.28 agc-symver-base:1.7 tls-maxphys-base:1.7 yamt-pagecache-base8:1.7 netbsd-5-2:1.7.0.24 yamt-pagecache-base7:1.7 netbsd-5-2-RELEASE:1.7 netbsd-5-2-RC1:1.7 yamt-pagecache-base6:1.7 yamt-pagecache-base5:1.7 yamt-pagecache-base4:1.7 netbsd-5-1-2-RELEASE:1.7 netbsd-5-1-1-RELEASE:1.7 yamt-pagecache-base3:1.7 yamt-pagecache-base2:1.7 yamt-pagecache:1.7.0.22 yamt-pagecache-base:1.7 bouyer-quota2-nbase:1.7 bouyer-quota2:1.7.0.20 bouyer-quota2-base:1.7 matt-nb5-pq3:1.7.0.18 matt-nb5-pq3-base:1.7 netbsd-5-1:1.7.0.16 netbsd-5-1-RELEASE:1.7 netbsd-5-1-RC4:1.7 netbsd-5-1-RC3:1.7 netbsd-5-1-RC2:1.7 netbsd-5-1-RC1:1.7 netbsd-5-0-2-RELEASE:1.7 netbsd-5-0-1-RELEASE:1.7 jym-xensuspend-nbase:1.7 netbsd-5-0:1.7.0.14 netbsd-5-0-RELEASE:1.7 netbsd-5-0-RC4:1.7 netbsd-5-0-RC3:1.7 netbsd-5-0-RC2:1.7 jym-xensuspend:1.7.0.12 jym-xensuspend-base:1.7 netbsd-5-0-RC1:1.7 netbsd-5:1.7.0.10 netbsd-5-base:1.7 yamt-pf42-base4:1.7 yamt-pf42-base3:1.7 hpcarm-cleanup-nbase:1.7 yamt-pf42-base2:1.7 yamt-pf42:1.7.0.8 yamt-pf42-base:1.7 keiichi-mipv6:1.7.0.6 keiichi-mipv6-base:1.7 cube-autoconf:1.7.0.4 cube-autoconf-base:1.7 hpcarm-cleanup:1.7.0.2 hpcarm-cleanup-base:1.7; locks; strict; comment @# @; 1.7 date 2001.11.01.16.34.21; author tv; state dead; branches; next 1.6; 1.6 date 2001.11.01.00.15.47; author thorpej; state Exp; branches; next 1.5; 1.5 date 2001.10.31.23.20.34; author tv; state Exp; branches; next 1.4; 1.4 date 2001.10.30.16.22.40; author wiz; state Exp; branches; next 1.3; 1.3 date 2001.10.30.14.40.24; author tv; state Exp; branches; next 1.2; 1.2 date 2001.10.29.20.02.01; author tv; state Exp; branches; next 1.1; 1.1 date 2001.10.29.19.49.13; author tv; state Exp; branches; next ; desc @@ 1.7 log @By popular demand, one preformatted version of BUILDING, plaintext, no CRs. @ text @ October 29, 2001 BUILDING 8 NetBSD

NAME

BUILDING - Procedure for building NetBSD from source code.

STATUS

This document is a work-in-progress. As such, the information described here may not match the reality of the build system as of this writing. Once this document is completely in sync with reality, this paragraph will be removed.

Discrepancies between this documentation and the current reality of implementation are noted specially, as with the note below:

Note: This document applies only to platforms which use the new toolchain as indicated by the setting of USE_NEW_TOOLCHAIN in /etc/mk.conf or <bsd.own.mk>. Platforms which have not yet been switched to the new toolchain should continue building traditionally, using the notes specified in the file UPDATING.

REQUIREMENTS

NetBSD is designed to be buildable on most POSIX-compliant host systems. The basic build procedure is the same whether compiling natively (on the same NetBSD architecture) or cross compiling (on another architecture or OS).

This source tree contains a special subtree, ``tools'', which uses the host system to create a build toolchain for the target architecture. The host system must have at least C and C++ compilers in order to create the toolchain (make is not required); all other tools are created as part of the NetBSD build process.

Note:
A couple host toolchain components are not yet available in the tools
directory.  Also, some tools use non-POSIX, non-ANSI C extensions
and need to be standardized.  As a result, cross-compiling from
systems other than
NetBSD
is not currently supported.

FILES

Source tree layout

BUILDING.mdoc
This document (in -mdoc troff format; the original copy).

BUILDING.html
This document (in formatted HTML).

BUILDING.txt
This document (in plaintext).

Makefile
The main Makefile for NetBSD; should only be run for native builds with an appropriately up-to-date version of NetBSD make(1). (For building from out-of-date systems or on a non-native host, see the build.sh shell script.)

UPDATING
Special notes for updating from an earlier revision of NetBSD. It is important to read this file before every build of an updated source tree.

build.sh
Bourne-compatible shell script used for building the host build tools and the NetBSD system from scratch. Can be used for both native and cross builds, and should be used instead of make(1) for any source tree that is updated and recompiled regularly.

crypto/dist/, dist/, gnu/dist/
Sources imported verbatim from third parties, without mangling the existing build structure. Other source trees in bin through usr.sbin use the NetBSD make(1) ``reachover'' Makefile semantics when building these programs for a native host.

distrib/, etc/
Sources for items used when making a full release snapshot, such as files installed in /etc on the destination system, boot media, and release notes.

regress/
Regression test harness. Can be cross-compiled, but only run natively.

sys/
NetBSD kernel sources.

tools/
``Reachover'' build structure for the host build tools. This has a special method of determining out-of-date status.

bin/ ... usr.sbin/
Sources to the NetBSD userland (non-kernel) programs. If any of these directories are missing, they will be skipped during the build.

Build tree layout

The NetBSD build tree is described in hier(7), and the release layout is described in release(7).

CONFIGURATION

"make" variables

Several variables control the behavior of NetBSD builds. Unless otherwise specified, these variables may be set in either the process environment or the make(1) configuration file specified by MAKECONF.

DESTDIR
Directory to contain the built NetBSD system. If set, special options are passed to the compilation tools to prevent their default use of the host system's /usr/include, /usr/lib, and so forth. This pathname should not end with a slash (/) character (for installation into the system's root directory, set DESTDIR to an empty string).

Default: Empty string if USETOOLS is ``yes''; unset otherwise.

MAKECONF
The name of the make(1) configuration file. Only settable in the process environment.

Default: ``/etc/mk.conf''

MKCATPAGES
Can be set to ``yes'' or ``no''. Indicates whether preformatted plaintext manual pages will be created during a build.

Default: ``yes''

MKCRYPTO
Can be set to ``yes'' or ``no''. Indicates whether cryptographic code will be included in a build; provided for the benefit of countries that do not allow strong cryptography. Will not affect use of the standard low-security password encryption system, crypt(3).

Default: ``yes''

MKDOC
Can be set to ``yes'' or ``no''. Indicates whether system documentation destined for /usr/share/doc will be installed during a build.

Default: ``yes''

MKINFO
Can be set to ``yes'' or ``no''. Indicates whether GNU Info files, used for the documentation for most of the compilation tools, will be created and installed during a build.

Default: ``yes''

MKLINT
Can be set to ``yes'' or ``no''. Indicates whether lint(1) will be run against portions of the NetBSD source code during the build, and whether lint libraries will be installed into /usr/libdata/lint.

Default: ``yes''

MKMAN
Can be set to ``yes'' or ``no''. Indicates whether manual pages will be installed during a build.

Default: ``yes''

MKNLS
Can be set to ``yes'' or ``no''. Indicates whether Native Language System locale zone files will be compiled and installed during a build.

Default: ``yes''

MKOBJ
Can be set to ``yes'' or ``no''. Indicates whether object directories will be created when running ``make obj''. If set to ``no'', then all built files will be located inside the regular source tree.

Default: ``yes''

MKPIC
Can be set to ``yes'' or ``no''. Indicates whether shared objects and libraries will be created and installed during a build. If set to ``no'', the entire built system will be statically linked.

Default: Platform dependent. As of this writing, all platforms except sh3 default to ``yes''.

MKPICINSTALL
Can be set to ``yes'' or ``no''. Indicates whether the ar(1) format libraries (lib*_pic.a), used to generate shared libraries, are installed during a build.

Default: ``yes''

MKPROFILE
Can be set to ``yes'' or ``no''. Indicates whether profiled libraries (lib*_p.a) will be built and installed during a build.

Default: ``yes''; however, some platforms turn off MKPROFILE by default at times due to toolchain problems with profiled code.

MKSHARE
Can be set to ``yes'' or ``no''. Indicates whether files destined to reside in /usr/share will be built and installed during a build. If set to ``no'', then all of MKCATPAGES, MKDOC, MKINFO, MKMAN, and MKNLS will be set to ``no'' unconditionally.

Default: ``yes''

TOOLDIR
Directory to hold the host tools, once built. This directory should be unique to a given host system and NetBSD source tree. (However, multiple targets may share the same TOOLDIR; the target-dependent files have unique names.) If unset, a default based on the uname(1) information of the host platform will be created in the .OBJDIR of src/tools.

Default: Unset.

UPDATE
If set, then all install operations intended to write to DESTDIR will compare file timestamps before installing, and skip the install phase if the destination files are up-to-date. This also has implications on full builds (see next subsection).

Default: Unset.

USETOOLS
Indicates whether the tools specified by TOOLDIR should be used as part of a build in progress. Must be set to ``yes'' if cross-compiling.

yes
Use the tools from TOOLDIR.

no
Do not use the tools from TOOLDIR, but refuse to build native compilation tool components that are version-specific for that tool.

never
Do not use the tools from TOOLDIR, even when building native tool components. This is similar to the traditional NetBSD build method, but does not verify that the compilation tools in use are up-to-date enough in order to build the tree successfully. This may cause build or runtime problems when building the whole NetBSD source tree.

Default: ``yes'' if building all or part of a whole NetBSD source tree (detected automatically); ``no'' otherwise (to preserve traditional semantics of the <bsd.*.mk> make(1) include files).

"make" variables for full builds

These variables only affect the top level ``Makefile'' and do not manually building subtrees of the NetBSD source code.

MKOBJDIRS
Can be set to ``yes'' or ``no''. Indicates whether object directories will be created automatically (via a ``make obj'' pass) at the start of a build.

Default: ``yes''

MKTOOLS
Indicates whether the host tools will be built and installed automatically if they are out-of-date.

yes
Build tools as needed into TOOLDIR, but only if the tools in question are out-of-date.

no
Do not update the tools in TOOLDIR; halt the build as a safety precaution if tools are out-of-date.

always
Always rebuild the tools in TOOLDIR from scratch during a build. This is similar to the standard NetBSD source tree build method, but is not typically required for host tools.

Default: ``yes''

NBUILDJOBS
If set, specifies the number of parallel make(1) processes that should be run simultaneously. This can speed up builds on SMP machines, or machines with much more CPU power than I/O availability. This should be used instead of the make(1) option -j, in order to ensure proper ordering of build components.

Default: Unset.

NOCLEANDIR
If set, avoids the ``make cleandir'' phase of a full build. This has the effect of allowing only changed files in a source tree to be recompiled. This can speed up builds when updating only a few files in the tree.

Default: Unset.

NODISTRIBDIRS
If set, avoids the ``make distrib-dirs'' phase of a full build. This skips running mtree(8) on DESTDIR, useful on systems where building as an unprivileged user, or where it is known that the system-wide mtree files have not changed.

Default: Unset.

NOINCLUDES
If set, avoids the ``make includes'' phase of a full build. This has the effect of preventing make(1) from thinking that some programs are out-of-date simply because the system include files have changed. However, this option should not be used when updating the entire NetBSD source tree arbitrarily; it is suggested to use UPDATE in that case.

Default: Unset.

RELEASEDIR
If set, specifies the directory to which a release(7) layout will be written at the end of a ``make release''.

Default: Unset.

UPDATE
If set, then in addition to the effects described for UPDATE above, this implies the effects of NOCLEANDIR.

BUILDING

"make" command line options

This is only a summary of options available to make(1); only the options used most frequently with NetBSD builds are listed here.

-m dir
Specify the default directory for searching for system Makefile segments, mainly the <bsd.*.mk> files. When building any full NetBSD source tree, this should be set to the ``share/mk'' directory in the source tree. (This is set automatically when building from the top level.)

-n
Display the commands that would have been executed, but do not actually execute them. This will still cause recursion to take place.

-v var
Print make(1)'s idea of the value of var. Does not build any targets.

var=value
Set the variable var to value, overriding any setting specified by the process environment, the MAKECONF configuration file, or the system Makefile segments.

"make" targets

These default targets may be built by running make(1) in any subtree of the NetBSD source code. It is recommended that none of these be used from the top level Makefile; as a specific exception, ``make obj'' and ``make cleandir'' are useful in that context.

all
Build programs, libraries, and preformatted documentation.

clean
Remove program and library object code files.

cleandir
Same as clean, but also remove preformatted documentation, dependency files generated by ``make depend'', and any other files known to be created at build time. ``make distclean'' may be used as a synonym, for familiarity with a similar well-known convention.

depend
Create dependency files (.depend) containing more detailed information about the dependencies of source code on header files. Allows programs to be recompiled automatically when a dependency changes.

dependall
Does a ``make depend'' immediately followed by a ``make all''. This combined target recurses as an atomic unit, so that the ``make depend'' phase can participate in make -j parallelism.

includes
Build and install system header files. Typically needed before any system libraries or programs can be built.

install
Install programs, libraries, and documentation into DESTDIR.

lint
Run lint(1) against the C source code, where appropriate, and generate system-installed lint libraries.

obj
Create object directories to be used for built files, instead of building directly in the source tree.

tags
Create ctags(1) searchable function lists usable by the ex(1) and vi(1) text editors.

"make" targets for the top level

Additional make(1) targets are usable specifically from the top source level to facilitate building the entire NetBSD source tree.

build
Build the entire NetBSD system. This orders portions of the source tree such that prerequisites will be built in the proper order.

release
Do a ``make build'', then package the system into a standard release layout as described by release(7). This requires that RELEASEDIR be set (see above).

regression-tests
Can only be run after building the regression tests in the directory ``regress''. Runs the compiled regression tests on the local host.

The "build.sh" script

This script file is a Bourne shell script designed to build the entire NetBSD system on any host with a Bourne shell in /bin/sh, including many that are not POSIX compliant. Note that if a host system's /bin/sh is unusually old and broken, the Korn Shell (/bin/ksh), if available, may be a usable alternative.

All cross-compile builds, and most native builds, of the entire system should make use of build.sh rather than just running ``make''. This way, the make(1) program will be bootstrapped properly, in case the host system has an older or incompatible ``make'' program.

When compiling the entire system via build.sh, many make(1) variables are set for you in order to help encapsulate the build process. In the list of options below, variables that are automatically set by build.sh are noted where applicable.

The following are available command line options that may be supplied to build.sh:

-a arch
Set the value of MACHINE_ARCH to arch.

-b
Bootstrap ``make'' and create a nbmake-MACHINE script (see below).

-j njob
Set the value of NBUILDJOBS to njob. This provides similar functionality to the familiar ``make -j'', but preserves the ordering of the top level ``make build''.

-m mach
Set the value of MACHINE to mach. This will also override any value of MACHINE_ARCH in the process environment with a value deduced from mach, unless -a is specified. All cross builds require -m, but if unset on a NetBSD host, the host's value of MACHINE will be detected and used automatically.

-n
Show the commands that would be executed by build.sh, but do not make any changes. This is similar in concept to ``make -n''.

-o
Set the value of MKOBJDIRS to ``no''.

-r
Remove the contents of DESTDIR and TOOLDIR before building (provides a clean starting point). This will skip deleting DESTDIR if building on a native system to the root directory.

-t
Build and install tools only. This option implies -b.

-u
Set the UPDATE variable.

-w wrapper
Create the nbmake wrapper script (see below) in a custom location, specified by wrapper. This allows, for instance, to place the wrapper in PATH automatically. Note that wrapper is the full name of the file, not just a directory name.

-D dest
Set the value of DESTDIR to dest.

-O obj
Create an appropriate transform macro for MAKEOBJDIR that will place the built object files under obj. For instance, a setting of /usr/obj will place build-time files files under /usr/obj/bin, /usr/obj/lib, and so forth.

-R rel
Set the value of RELEASEDIR to rel. Setting this option will cause build.sh to run ``make release'' instead of ``make build''.

-T tools
Set the value of TOOLDIR to tools. If set, the bootstrap ``make'' will only be rebuilt as needed (when the source files for make(1) change).

The "nbmake-MACHINE" wrapper script

If using the build.sh script to build NetBSD, a nbmake-MACHINE script will be created in TOOLDIR/bin upon the first build to assist in building subtrees on a cross-compile host.

nbmake-MACHINE can be invoked in lieu of make(1), and will instead call the up-to-date version of ``nbmake'' installed into TOOLDIR/bin with several key variables pre-set, including MACHINE, MACHINE_ARCH, and TOOLDIR. This script can be symlinked into a directory listed in PATH, or called with an absolute path.

SEE ALSO

make(1), hier(7), release(7)

HISTORY

The USE_NEW_TOOLCHAIN based build scheme was introduced in the ``NetBSD-current'' development sources between NetBSD1.5 and NetBSD1.6.

BUGS

Many platforms are not yet using the USE_NEW_TOOLCHAIN system. @ 1.6 log @Document build.sh -t @ text @@ 1.5 log @Document new build.sh options, and remove the temporary note on USETOOLS ("no" functions as documented now). @ text @d771 3 d879 3 @ 1.4 log @Drop some unnecessary whitespace, sort sections as in man pages, and fix an xref and a formatting nit. @ text @d366 7 a372 3 the target-dependent files have unique names.) Must be set if USETOOLS is ``yes''. a424 8

Note: Currently, the ``no'' option functions similarly to the ``never'' option. Proper checks will be added in the near future to add the described functionality for version-specific tool components. d470 1 a470 1 ``no'' d710 2 a711 16 process. In particular, both USETOOLS and MKTOOLS are set to ``yes'', and MACHINE_ARCH (if unset) is deduced from the value of MACHINE.

The variables DESTDIR, MACHINE, MACHINE_ARCH, and TOOLDIR are required in order for d713 1 a713 6 to function, and thus they cannot be set in the configuration file specified by MAKECONF. They may be set either in the process environment, or via command line options to build.sh. d723 6 a728 5

-D dest
Set the value of DESTDIR to dest. d749 50 a798 1 is specified. d804 1 a804 1 Setting this option will make d806 1 a806 1 run a809 6

-r
Remove the contents of DESTDIR and TOOLDIR before building (provides a clean starting point). d815 5 a875 2 @ 1.3 log @Fix quote characters (" does not work; nor does \*(Lq and \*(Rq in HTML). @ text @d503 1 a503 1 mtree(1) a831 6 BUGS Many platforms are not yet using the USE_NEW_TOOLCHAIN system.

d842 6 @ 1.2 log @Fix the names of the BUILDING files in the description of the source tree layout. @ text @d167 2 a168 2 make variables d431 2 a432 2 make variables for full builds d543 2 a544 2 make command line options d582 2 a583 2 make targets d651 2 a652 2 make targets for the top level d681 2 a682 2 The build.sh script d795 5 a799 3

The nbmake-MACHINE wrapper script

d849 4 @ 1.1 log @Add plaintext and HTML generated versions of the BUILDING document. @ text @a90 2

BUILDING
This document (in formatted plaintext). d92 5 a96 1 This document (in -mdoc troff format). a846 2 @