4e33a0f5d5
* add "releasekernel=conf", to install a gzipped copy of the kernels
built by "kernel=conf" to RELEASEDIR/MACHINE/binary/kernel
build.sh:
* be more consistent in various status messages
* move the {release,}kernel=conf conf parsing code into getkernelconf()
and use in both buildkernel() and releasekernel()
* only warn once when building multiple kernels without updating the tools
1294 lines
28 KiB
Plaintext
1294 lines
28 KiB
Plaintext
.\" $NetBSD: BUILDING.mdoc,v 1.22 2003/05/25 12:34:28 lukem Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001-2003 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Todd Vierling and Luke Mewburn.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" NOTE: After changing this file, run "make build-docs" to generate the
|
|
.\" proper plaintext versions, and check in all BUILDING.* files!
|
|
.\"
|
|
.\" Toolchain prefix for commands
|
|
.ds toolprefix nb
|
|
.
|
|
.Dd May 25, 2003
|
|
.Dt BUILDING 8
|
|
.Os NetBSD
|
|
.
|
|
.Sh NAME
|
|
.
|
|
.Nm BUILDING
|
|
.Nd Procedure for building
|
|
.Nx
|
|
from source code.
|
|
.
|
|
.Sh 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.
|
|
.Pp
|
|
Discrepancies between this documentation and the current reality of
|
|
implementation are noted specially, as with the note below:
|
|
.Pp
|
|
.Em Note :
|
|
This document applies only to platforms which use the new toolchain as
|
|
indicated by the default setting of
|
|
.Sy TOOLCHAIN_MISSING
|
|
in
|
|
.Aq 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
|
|
.Sy UPDATING .
|
|
.
|
|
.Sh REQUIREMENTS
|
|
.
|
|
.Nx
|
|
is designed to be buildable on most POSIX-compliant host systems.
|
|
The basic build procedure is the same whether compiling
|
|
.Em natively
|
|
(on the same
|
|
.Nx
|
|
architecture) or
|
|
.Em cross compiling
|
|
(on another architecture or OS).
|
|
.Pp
|
|
This source tree contains a special subtree,
|
|
.Dq 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
|
|
.Nm ( make
|
|
is not required); all other tools are created as part of the
|
|
.Nx
|
|
build process.
|
|
.Pp
|
|
.Bd -ragged -offset indent
|
|
.Em Note :
|
|
A couple of 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
|
|
.Nx
|
|
is not currently supported.
|
|
.Ed
|
|
.
|
|
.Sh FILES
|
|
.
|
|
.Ss Source tree layout
|
|
.
|
|
.Bl -tag -width "BUILDING.mdoc"
|
|
.It Sy doc/BUILDING.mdoc
|
|
This document (in -mdoc troff format; the original copy).
|
|
.It Sy BUILDING
|
|
This document (in plaintext).
|
|
.It Sy Makefile
|
|
The main Makefile for
|
|
.Nx ;
|
|
should only be run for native builds with an appropriately up-to-date
|
|
version of
|
|
.Nx
|
|
.Xr make 1 .
|
|
(For building from out-of-date systems or on a non-native host, see the
|
|
.Nm build.sh
|
|
shell script.)
|
|
.It Sy UPDATING
|
|
Special notes for updating from an earlier revision of
|
|
.Nx .
|
|
It is important to read this file before every build of an updated
|
|
source tree.
|
|
.It Sy build.sh
|
|
Bourne-compatible shell script used for building the host build tools
|
|
and the
|
|
.Nx
|
|
system from scratch.
|
|
Can be used for both native and cross builds, and should be used instead of
|
|
.Xr make 1
|
|
for any source tree that is updated and recompiled regularly.
|
|
.It Sy crypto/dist/ , dist/ , gnu/dist/
|
|
Sources imported verbatim from third parties, without mangling the
|
|
existing build structure.
|
|
Other source trees in
|
|
.Sy bin
|
|
through
|
|
.Sy usr.sbin
|
|
use the
|
|
.Nx
|
|
.Xr make 1
|
|
.Dq reachover
|
|
Makefile semantics when building these programs for a native host.
|
|
.It Sy distrib/ , etc/
|
|
Sources for items used when making a full release snapshot, such as
|
|
files installed in
|
|
.Sy DESTDIR Ns Pa /etc
|
|
on the destination system, boot media, and release notes.
|
|
.It Sy regress/
|
|
Regression test harness.
|
|
Can be cross-compiled, but only run natively.
|
|
.It Sy sys/
|
|
.Nx
|
|
kernel sources.
|
|
.It Sy tools/
|
|
.Dq Reachover
|
|
build structure for the host build tools.
|
|
This has a special method of determining out-of-date status.
|
|
.It Sy bin/ ... usr.sbin/
|
|
Sources to the
|
|
.Nx
|
|
userland (non-kernel) programs.
|
|
If any of these directories are missing, they will be skipped during the build.
|
|
.El
|
|
.
|
|
.Ss Build tree layout
|
|
.
|
|
The
|
|
.Nx
|
|
build tree is described in
|
|
.Xr hier 7 ,
|
|
and the release layout is described in
|
|
.Xr release 7 .
|
|
.Pp
|
|
.
|
|
.Sh CONFIGURATION
|
|
.
|
|
.Ss Environment variables
|
|
..
|
|
Several environment variables control the behaviour of
|
|
.Nx
|
|
builds.
|
|
.
|
|
.Bl -tag -width "MAKEOBJDIRPREFIX"
|
|
.
|
|
.It Sy MACHINE
|
|
Machine type.
|
|
.
|
|
.It Sy MACHINE_ARCH
|
|
Machine architecture.
|
|
.
|
|
.It Sy MAKE
|
|
Path name to invoke
|
|
.Xr make 1
|
|
as.
|
|
.
|
|
.It Sy MAKEFLAGS
|
|
Flags to invoke
|
|
.Xr make 1
|
|
with.
|
|
.
|
|
.It Sy MAKEOBJDIR
|
|
Directory to use as the
|
|
.Sy .OBJDIR
|
|
for the current directory.
|
|
Used only if
|
|
.Sy MAKEOBJDIRPREFIX
|
|
is not defined.
|
|
.Sy MAKEOBJDIR
|
|
can only be provided in the environment.
|
|
.
|
|
.It Sy MAKEOBJDIRPREFIX
|
|
Top level directory of the object directory tree.
|
|
If this is defined,
|
|
${MAKEOBJDIRPREFIX}/${.CURDIR}
|
|
is used as the
|
|
.Sy .OBJDIR
|
|
for the current directory.
|
|
The current directory may be read only.
|
|
.Sy MAKEOBJDIRPREFIX
|
|
can only be provided in the environment.
|
|
.
|
|
.El
|
|
.
|
|
.Ss \*qmake\*q variables
|
|
.
|
|
.de YorN
|
|
Can be set to
|
|
.Dq yes
|
|
or
|
|
.Dq no .
|
|
..
|
|
.de DFLT
|
|
.Pp
|
|
.Em Default :
|
|
..
|
|
.de DFLTu
|
|
.DFLT
|
|
Unset.
|
|
..
|
|
.de DFLTy
|
|
.DFLT
|
|
.Dq yes
|
|
..
|
|
.de DFLTn
|
|
.DFLT
|
|
.Dq no
|
|
..
|
|
Several variables control the behavior of
|
|
.Nx
|
|
builds.
|
|
Unless otherwise specified, these variables may be set in
|
|
either the process environment or the
|
|
.Xr make 1
|
|
configuration file specified by
|
|
.Sy MAKECONF .
|
|
.
|
|
.Bl -tag -width "MKCATPAGES"
|
|
.
|
|
.It Sy BUILDID
|
|
Identifier for the build.
|
|
The identifier will be appended to
|
|
object directory names, and can be consulted in the
|
|
.Xr make 1
|
|
configuration file in order to set additional build parameters,
|
|
such as compiler flags.
|
|
.
|
|
.It Sy DESTDIR
|
|
Directory to contain the built
|
|
.Nx
|
|
system.
|
|
If set, special options are passed to the compilation tools to
|
|
prevent their default use of the host system's
|
|
.Sy /usr/include , /usr/lib ,
|
|
and so forth.
|
|
This pathname should
|
|
.Em not
|
|
end with a slash
|
|
.Pq /
|
|
character (for installation into the system's root directory, set
|
|
.Sy DESTDIR
|
|
to an empty string).
|
|
The directory must reside on a file system which supports long file
|
|
names and hard links.
|
|
.DFLT
|
|
Empty string if
|
|
.Sy USETOOLS
|
|
is
|
|
.Dq yes ;
|
|
unset otherwise.
|
|
.Pp
|
|
.Em Note :
|
|
.Sy build.sh
|
|
will provide a default of
|
|
.Pa destdir. Ns Sy MACHINE
|
|
(in the top-level
|
|
.Sy .OBJDIR )
|
|
unless run in
|
|
.Sq expert
|
|
mode
|
|
.
|
|
.It Sy MAKECONF
|
|
The name of the
|
|
.Xr make 1
|
|
configuration file.
|
|
.Em Only settable in the process environment.
|
|
.DFLT
|
|
.Dq /etc/mk.conf
|
|
.
|
|
.It Sy MKCATPAGES
|
|
.YorN
|
|
Indicates whether preformatted plaintext manual pages will be created
|
|
during a build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKCRYPTO
|
|
.YorN
|
|
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,
|
|
.Xr crypt 3 .
|
|
.DFLTy
|
|
.
|
|
.It Sy MKDOC
|
|
.YorN
|
|
Indicates whether system documentation destined for
|
|
.Sy DESTDIR Ns Pa /usr/share/doc
|
|
will be installed during a build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKHOSTOBJ
|
|
.YorN
|
|
If set to
|
|
.Dq yes ,
|
|
then for programs intended to be run on the compile host,
|
|
the name, release, and architecture of the host operating system
|
|
will be suffixed to the name of the object directory created by
|
|
.Dq make obj .
|
|
(This allows multiple host systems to compile NetBSD for a single target.)
|
|
If set to
|
|
.Dq no ,
|
|
then programs built to be run on the compile host will use the same
|
|
object directory names as programs built to be run on the target.
|
|
.DFLTn
|
|
.
|
|
.It Sy MKINFO
|
|
.YorN
|
|
Indicates whether GNU Info files, used for the documentation for
|
|
most of the compilation tools, will be created and installed during a
|
|
build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKLINT
|
|
.YorN
|
|
Indicates whether
|
|
.Xr lint 1
|
|
will be run against portions of the
|
|
.Nx
|
|
source code during the build, and whether lint libraries will be
|
|
installed into
|
|
.Sy DESTDIR Ns Pa /usr/libdata/lint .
|
|
.DFLTy
|
|
.
|
|
.It Sy MKMAN
|
|
.YorN
|
|
Indicates whether manual pages will be installed during a build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKNLS
|
|
.YorN
|
|
Indicates whether Native Language System locale zone files will be
|
|
compiled and installed during a build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKOBJ
|
|
.YorN
|
|
Indicates whether object directories will be created when running
|
|
.Dq make obj .
|
|
If set to
|
|
.Dq no ,
|
|
then all built files will be located inside the regular source tree.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKPIC
|
|
.YorN
|
|
Indicates whether shared objects and libraries will be created and
|
|
installed during a build.
|
|
If set to
|
|
.Dq no ,
|
|
the entire built system will be statically linked.
|
|
.DFLT
|
|
Platform dependent.
|
|
As of this writing, all platforms except
|
|
.Sy sh3
|
|
default to
|
|
.Dq yes .
|
|
.
|
|
.It Sy MKPICINSTALL
|
|
.YorN
|
|
Indicates whether the
|
|
.Xr ar 1
|
|
format libraries
|
|
.Sy ( lib*_pic.a ) ,
|
|
used to generate shared libraries, are installed during a build.
|
|
.DFLTy
|
|
.
|
|
.It Sy MKPROFILE
|
|
.YorN
|
|
Indicates whether profiled libraries
|
|
.Sy ( lib*_p.a )
|
|
will be built and installed during a build.
|
|
.DFLT
|
|
.Dq yes ;
|
|
however, some platforms turn off
|
|
.Sy MKPROFILE
|
|
by default at times due to toolchain problems with profiled code.
|
|
.
|
|
.It Sy MKSHARE
|
|
.YorN
|
|
Indicates whether files destined to reside in
|
|
.Sy DESTDIR Ns Pa /usr/share
|
|
will be built and installed during a build.
|
|
If set to
|
|
.Dq no ,
|
|
then all of
|
|
.Sy MKCATPAGES , MKDOC , MKINFO , MKMAN ,
|
|
and
|
|
.Sy MKNLS
|
|
will be set to
|
|
.Dq no
|
|
unconditionally.
|
|
.DFLTy
|
|
.
|
|
.It Sy TOOLDIR
|
|
Directory to hold the host tools, once built.
|
|
This directory should be unique to a given host system and
|
|
.Nx
|
|
source tree.
|
|
(However, multiple targets may share the same
|
|
.Sy TOOLDIR ;
|
|
the target-dependent files have unique names.) If unset, a default based
|
|
on the
|
|
.Xr uname 1
|
|
information of the host platform will be created in the
|
|
.Sy .OBJDIR
|
|
of
|
|
.Pa src/tools .
|
|
.DFLTu
|
|
.
|
|
.It Sy UNPRIVED
|
|
If set, then an unprivileged install will occur.
|
|
The user, group, permissions, and file flags, will not be set on
|
|
the installed item; instead the information will be appended to
|
|
a file called
|
|
.Pa METALOG
|
|
in
|
|
.Sy DESTDIR .
|
|
The contents of
|
|
.Pa METALOG
|
|
is used during the generation of the distribution tar files to ensure
|
|
that the appropriate file ownership is stored.
|
|
.DFLTu
|
|
.
|
|
.It Sy UPDATE
|
|
If set, then all install operations intended to write to
|
|
.Sy 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).
|
|
.DFLTu
|
|
.
|
|
.It Sy USETOOLS
|
|
Indicates whether the tools specified by
|
|
.Sy TOOLDIR
|
|
should be used as part of a build in progress.
|
|
Must be set to
|
|
.Dq yes
|
|
if cross-compiling.
|
|
.Bl -tag -width "never"
|
|
.It Sy yes
|
|
Use the tools from
|
|
.Sy TOOLDIR .
|
|
.It Sy no
|
|
Do not use the tools from
|
|
.Sy TOOLDIR ,
|
|
but refuse to build native compilation tool components that are
|
|
version-specific for that tool.
|
|
.It Sy never
|
|
Do not use the tools from
|
|
.Sy TOOLDIR ,
|
|
even when building native tool components.
|
|
This is similar to the traditional
|
|
.Nx
|
|
build method, but does
|
|
.Em 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
|
|
.Nx
|
|
source tree.
|
|
.El
|
|
.DFLT
|
|
.Dq yes
|
|
if building all or part of a whole
|
|
.Nx
|
|
source tree (detected automatically);
|
|
.Dq no
|
|
otherwise (to preserve traditional semantics of the
|
|
.Aq bsd.*.mk
|
|
.Xr make 1
|
|
include files).
|
|
.
|
|
.El
|
|
.
|
|
.Ss \*qmake\*q variables for full builds
|
|
These variables only affect the top level
|
|
.Dq Makefile
|
|
and do not affect manually building subtrees of the
|
|
.Nx
|
|
source code.
|
|
.
|
|
.Bl -tag -width "INSTALLWORLDDIR"
|
|
.
|
|
.It Sy INSTALLWORLDDIR
|
|
Location for the
|
|
.Dq make installworld
|
|
target to install to.
|
|
.DFLT
|
|
.Dq /
|
|
.
|
|
.It Sy MKOBJDIRS
|
|
.YorN
|
|
Indicates whether object directories will be created automatically
|
|
(via a
|
|
.Dq make obj
|
|
pass) at the start of a build.
|
|
.DFLTn
|
|
.
|
|
.It Sy NBUILDJOBS
|
|
Now obsolete.
|
|
Use the
|
|
.Xr make 1
|
|
option
|
|
.Fl j ,
|
|
instead (see below)
|
|
.DFLTu
|
|
.
|
|
.It Sy NOCLEANDIR
|
|
If set, avoids the
|
|
.Dq 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.
|
|
.DFLTu
|
|
.
|
|
.It Sy NODISTRIBDIRS
|
|
If set, avoids the
|
|
.Dq make distrib-dirs
|
|
phase of a full build.
|
|
This skips running
|
|
.Xr mtree 8
|
|
on
|
|
.Sy DESTDIR ,
|
|
useful on systems where building as an unprivileged user, or where it is
|
|
known that the system-wide mtree files have not changed.
|
|
.DFLTu
|
|
.
|
|
.It Sy NOINCLUDES
|
|
If set, avoids the
|
|
.Dq make includes
|
|
phase of a full build.
|
|
This has the effect of preventing
|
|
.Xr 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
|
|
.Nx
|
|
source tree arbitrarily; it is suggested to use
|
|
.Sy UPDATE
|
|
in that case.
|
|
.DFLTu
|
|
.
|
|
.It Sy RELEASEDIR
|
|
If set, specifies the directory to which a
|
|
.Xr release 7
|
|
layout will be written at the end of a
|
|
.Dq make release .
|
|
.DFLTu
|
|
.Pp
|
|
.Em Note :
|
|
.Sy build.sh
|
|
will provide a default of
|
|
.Pa releasedir
|
|
(in the top-level
|
|
.Sy .OBJDIR )
|
|
unless run in
|
|
.Sq expert
|
|
mode
|
|
.
|
|
.It Sy UPDATE
|
|
If set, then in addition to the effects described for UPDATE above, this
|
|
implies the effects of
|
|
.Sy NOCLEANDIR
|
|
(i.e.,
|
|
.Dq make cleandir
|
|
is avoided).
|
|
.
|
|
.El
|
|
.
|
|
.Sh BUILDING
|
|
.
|
|
.Ss \*qmake\*q command line options
|
|
This is only a summary of options available to
|
|
.Xr make 1 ;
|
|
only the options used most frequently with
|
|
.Nx
|
|
builds are listed here.
|
|
.
|
|
.Bl -tag -width "var=value"
|
|
.
|
|
.It Fl j Ar njob
|
|
Run up to
|
|
.Ar njob
|
|
.Xr make 1
|
|
subjobs in parallel.
|
|
Makefiles should use .WAIT or have explicit dependancies
|
|
as necessary to enforce build ordering.
|
|
If you see build failures with -j, please save complete build logs
|
|
so the failures can be analyzed.
|
|
.
|
|
.It Fl m Ar dir
|
|
Specify the default directory for searching for system Makefile
|
|
segments, mainly the
|
|
.Aq bsd.*.mk
|
|
files.
|
|
When building any full
|
|
.Nx
|
|
source tree, this should be set to the
|
|
.Dq share/mk
|
|
directory in the source tree.
|
|
(This is set automatically when building from the top level.)
|
|
.
|
|
.It Fl n
|
|
Display the commands that would have been executed, but do not
|
|
actually execute them.
|
|
This will still cause recursion to take place.
|
|
.
|
|
.It Fl v Ar var
|
|
Print
|
|
.Xr make 1 Ns 's
|
|
idea of the value of
|
|
.Ar var .
|
|
Does not build any targets.
|
|
.
|
|
.It Em var=value
|
|
Set the variable
|
|
.Em var
|
|
to
|
|
.Em value ,
|
|
overriding any setting specified by the process environment, the
|
|
.Sy MAKECONF
|
|
configuration file, or the system Makefile segments.
|
|
.
|
|
.El
|
|
.
|
|
.Ss \*qmake\*q targets
|
|
.
|
|
These default targets may be built by running
|
|
.Xr make 1
|
|
in any subtree of the
|
|
.Nx
|
|
source code.
|
|
It is recommended that none of these be used from the top
|
|
level Makefile; as a specific exception,
|
|
.Dq make obj
|
|
and
|
|
.Dq make cleandir
|
|
are useful in that context.
|
|
.
|
|
.Bl -tag -width "dependall"
|
|
.
|
|
.It Sy all
|
|
Build programs, libraries, and preformatted documentation.
|
|
.
|
|
.It Sy clean
|
|
Remove program and library object code files.
|
|
.
|
|
.It Sy cleandir
|
|
Same as
|
|
.Sy clean ,
|
|
but also remove preformatted documentation, dependency files generated
|
|
by
|
|
.Dq make depend ,
|
|
and any other files known to be created at build time.
|
|
.Dq make distclean
|
|
may be used as a synonym, for familiarity with a similar well-known
|
|
convention.
|
|
.
|
|
.It Sy depend
|
|
Create dependency files
|
|
.Sy ( .depend )
|
|
containing more detailed information about the dependencies of source
|
|
code on header files.
|
|
Allows programs to be recompiled automatically when a dependency changes.
|
|
.
|
|
.It Sy dependall
|
|
Does a
|
|
.Dq make depend
|
|
immediately followed by a
|
|
.Dq make all .
|
|
This improves cache locality of the build since both passes read the source
|
|
files in their entirety.
|
|
.
|
|
.It Sy includes
|
|
Build and install system header files.
|
|
Typically needed before any system libraries or programs can be built.
|
|
.
|
|
.It Sy install
|
|
Install programs, libraries, and documentation into
|
|
.Sy DESTDIR .
|
|
Few files will be installed to
|
|
.Sy DESTDIR Ns Pa /dev ,
|
|
.Sy DESTDIR Ns Pa /etc ,
|
|
.Sy DESTDIR Ns Pa /root
|
|
or
|
|
.Sy DESTDIR Ns Pa /var
|
|
in order to prevent user supplied configuration data from being overwritten.
|
|
.It Sy lint
|
|
Run
|
|
.Xr lint 1
|
|
against the C source code, where appropriate, and generate
|
|
system-installed lint libraries.
|
|
.
|
|
.It Sy obj
|
|
Create object directories to be used for built files, instead of
|
|
building directly in the source tree.
|
|
.
|
|
.It Sy tags
|
|
Create
|
|
.Xr ctags 1
|
|
searchable function lists usable by the
|
|
.Xr ex 1
|
|
and
|
|
.Xr vi 1
|
|
text editors.
|
|
.
|
|
.El
|
|
.
|
|
.Ss \*qmake\*q targets for the top level
|
|
.
|
|
Additional
|
|
.Xr make 1
|
|
targets are usable specifically from the top source level to facilitate
|
|
building the entire
|
|
.Nx
|
|
source tree.
|
|
.
|
|
.Bl -tag -width "distribution"
|
|
.
|
|
.It Sy build
|
|
Build the entire
|
|
.Nx
|
|
system.
|
|
This orders portions of the source tree such that prerequisites
|
|
will be built in the proper order.
|
|
.
|
|
.It Sy distribution
|
|
Do a
|
|
.Dq make build ,
|
|
and then install a full distribution into
|
|
.Sy DESTDIR ,
|
|
including files in
|
|
.Sy DESTDIR Ns Pa /dev ,
|
|
.Sy DESTDIR Ns Pa /etc ,
|
|
.Sy DESTDIR Ns Pa /root
|
|
and
|
|
.Sy DESTDIR Ns Pa /var .
|
|
.
|
|
.It Sy buildworld
|
|
As per
|
|
.Dq make distribution ,
|
|
except that it ensures that
|
|
.Sy DESTDIR
|
|
is not the root directory.
|
|
.
|
|
.It Sy installworld
|
|
Install the distribution from
|
|
.Sy DESTDIR
|
|
to
|
|
.Sy INSTALLWORLDDIR
|
|
(which defaults to the root directory).
|
|
Ensures that
|
|
.Sy INSTALLWORLDDIR
|
|
is the not root directory if cross compiling.
|
|
.Pp
|
|
.Em Note :
|
|
It is highly recommended that you upgrade your kernel and reboot
|
|
before performing this operation.
|
|
.
|
|
.It Sy sets
|
|
Create distribution sets from
|
|
.Sy DESTDIR
|
|
into
|
|
.Sy RELEASEDIR/MACHINE Ns Pa /binary/sets .
|
|
Should be run after
|
|
.Dq make distribution
|
|
(as
|
|
.Dq make build
|
|
does not install all of the required files).
|
|
.
|
|
.It Sy sourcesets
|
|
Create source sets of the source tree into
|
|
.Sy RELEASEDIR Ns Pa /source/sets .
|
|
.
|
|
.It Sy release
|
|
Do a
|
|
.Dq make distribution ,
|
|
build kernels, distribution media, and install sets
|
|
(this as per
|
|
.Dq make sets ) ,
|
|
and
|
|
then package the system into a standard release layout as described by
|
|
.Xr release 7 .
|
|
This requires that
|
|
.Sy RELEASEDIR
|
|
be set (see above).
|
|
.
|
|
.It Sy regression-tests
|
|
Can only be run after building the regression tests in the directory
|
|
.Dq regress .
|
|
Runs the compiled regression tests on the local host.
|
|
.
|
|
.El
|
|
.
|
|
.Ss The \*qbuild.sh\*q script
|
|
.
|
|
This script file is a Bourne shell script designed to build the
|
|
entire
|
|
.Nx
|
|
system on any host with a Bourne shell in
|
|
.Sy /bin/sh ,
|
|
including many that are not POSIX compliant.
|
|
Note that if a host system's
|
|
.Sy /bin/sh
|
|
is unusually old and broken, the Korn Shell
|
|
.Sy ( /bin/ksh ) ,
|
|
if available, may be a usable alternative.
|
|
.Pp
|
|
All cross-compile builds, and most native builds, of the entire system
|
|
should make use of
|
|
.Sy build.sh
|
|
rather than just running
|
|
.Dq make .
|
|
This way, the
|
|
.Xr make 1
|
|
program will be bootstrapped properly, in case the host system has an
|
|
older or incompatible
|
|
.Dq make
|
|
program.
|
|
.Pp
|
|
When compiling the entire system via
|
|
.Sy build.sh ,
|
|
many
|
|
.Xr 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
|
|
.Sy build.sh
|
|
are noted where applicable.
|
|
.
|
|
.Pp
|
|
The following operations are supported by
|
|
.Sy build.sh :
|
|
.
|
|
.Bl -tag -width "distribution"
|
|
.
|
|
.It Sy build
|
|
Build the system as per
|
|
.Dq make build .
|
|
This option implies the
|
|
.Sy obj
|
|
and
|
|
.Sy tools
|
|
operations.
|
|
.
|
|
.It Sy distribution
|
|
Build a full distribution as per
|
|
.Dq make distribution .
|
|
This option implies the
|
|
.Sy build
|
|
operation.
|
|
.
|
|
.It Sy release
|
|
Build a full release as per
|
|
.Dq make release .
|
|
This option implies the
|
|
.Sy distribution
|
|
operation.
|
|
.
|
|
.It Sy makewrapper
|
|
Create the
|
|
.Sy \*[toolprefix]make-MACHINE
|
|
wrapper.
|
|
This operation is automatically performed for any of the other
|
|
operations.
|
|
.
|
|
.It Sy obj
|
|
Perform
|
|
.Dq make obj .
|
|
.
|
|
.It Sy tools
|
|
Build and install the host tools from
|
|
.Pa src/tools .
|
|
.
|
|
.It Sy install Ns = Ns Ar idir
|
|
Install the contents of
|
|
.Sy DESTDIR
|
|
to
|
|
.Ar idir ,
|
|
using
|
|
.Dq make installworld .
|
|
.
|
|
.It Sy kernel Ns = Ns Ar kconf
|
|
Build a new kernel.
|
|
The
|
|
.Ar kconf
|
|
argument is the name of a configuration file suitable
|
|
for use by
|
|
.Xr config 8 .
|
|
If
|
|
.Ar kconf
|
|
does not contain any
|
|
.Sq /
|
|
characters, the configuration file is expected to be found in the
|
|
.Sy KERNCONFDIR
|
|
directory, which is typically
|
|
.Sy sys/arch/MACHINE/conf .
|
|
The new kernel will be built in a subdirectory of
|
|
.Sy KERNOBJDIR ,
|
|
which is typically
|
|
.Sy sys/arch/MACHINE/compile
|
|
or an associated object directory.
|
|
In order to ensure that the kernel is built using up-to-date tools,
|
|
it is strongly recommended that the tools be rebuilt (using the
|
|
.Sy tools
|
|
operation).
|
|
.
|
|
.It Sy releasekernel Ns = Ns Ar kconf
|
|
Install a
|
|
.Xr gzip 1 Ns ed
|
|
copy of the kernel built by
|
|
.Sy kernel Ns = Ns Ar kconf
|
|
into
|
|
.Sy RELEASEDIR/MACHINE Ns Pa /binary/kernel ,
|
|
usually as
|
|
.Pa netbsd- Ns Ar kconf Ns Pa .gz ,
|
|
although the
|
|
.Dq Pa netbsd
|
|
prefix is determined from the
|
|
.Dq Sy config
|
|
directives in
|
|
.Ar kconf .
|
|
.
|
|
.It Sy sets
|
|
Perform
|
|
.Dq make sets .
|
|
.
|
|
.It Sy sourcesets
|
|
Perform
|
|
.Dq make sourcesets .
|
|
.
|
|
.El
|
|
.
|
|
.Pp
|
|
The following command line options alter the behaviour of the above
|
|
operations:
|
|
The following command line options alter the behaviour of the
|
|
.Sy build.sh
|
|
operations described above:
|
|
.
|
|
.Bl -tag -width "-T tools"
|
|
.
|
|
.It Fl a Ar arch
|
|
Set the value of
|
|
.Sy MACHINE_ARCH
|
|
to
|
|
.Ar arch .
|
|
.
|
|
.It Fl B Ar buildid
|
|
Set the value of
|
|
.Sy BUILDID
|
|
to
|
|
.Ar buildid .
|
|
This will also append the build idenfitier to the name of the
|
|
.Dq make
|
|
wrapper script so that the resulting name is of the form
|
|
.Dq Sy \*[toolprefix]make-MACHINE-BUILDID .
|
|
.
|
|
.It Fl D Ar dest
|
|
Set the value of
|
|
.Sy DESTDIR
|
|
to
|
|
.Ar dest .
|
|
.
|
|
.It Fl E
|
|
Set
|
|
.Sq expert
|
|
mode.
|
|
This overrides various sanity checks, and allows:
|
|
.Sy DESTDIR
|
|
does not have to be set to a non-root path for builds,
|
|
and
|
|
.Sy UNPRIVED
|
|
does not have to be set when building as a non-root user.
|
|
.Pp
|
|
.Em Note :
|
|
It is highly recommended that you know what you are doing when
|
|
you use this option.
|
|
.
|
|
.It Fl j Ar njob
|
|
Passed through to
|
|
.Xr make 1 .
|
|
Makefiles should use .WAIT or have explicit dependancies
|
|
as necessary to enforce build ordering.
|
|
If you see build failures with -j, please save complete build logs
|
|
so the failures can be analyzed.
|
|
.
|
|
.It Fl M Ar obj
|
|
Set
|
|
.Sy MAKEOBJDIRPREFIX
|
|
to
|
|
.Ar obj .
|
|
.
|
|
.It Fl m Ar mach
|
|
Set the value of
|
|
.Sy MACHINE
|
|
to
|
|
.Ar mach .
|
|
This will also override any value of
|
|
.Sy MACHINE_ARCH
|
|
in the process environment with a value deduced from
|
|
.Ar mach ,
|
|
unless
|
|
.Fl a
|
|
is specified, or
|
|
.Ar mach
|
|
is a special case listed below.
|
|
All cross builds require
|
|
.Fl m ,
|
|
but if unset on a NetBSD host, the host's value of MACHINE will be
|
|
detected and used automatically.
|
|
.Pp
|
|
Some machines support multiple values for
|
|
.Sy MACHINE_ARCH .
|
|
For a given value of
|
|
.Ar mach ,
|
|
the following
|
|
.Sy MACHINE
|
|
and
|
|
.Sy MACHINE_ARCH
|
|
values will result:
|
|
.Bl -column "evbmips-el" "MACHINE" "MACHINE_ARCH" -offset indent
|
|
.It Sy Ar mach Ta Sy "MACHINE" Ta Sy "MACHINE_ARCH"
|
|
.It evbmips Ta evbmips Ta (not set)
|
|
.It evbmips-eb Ta evbmips Ta mipseb
|
|
.It evbmips-el Ta evbmips Ta mipsel
|
|
.It evbsh3 Ta evbsh3 Ta (not set)
|
|
.It evbsh3-eb Ta evbsh3 Ta sh3eb
|
|
.It evbsh3-el Ta evbsh3 Ta sh3el
|
|
.It sbmips Ta sbmips Ta (not set)
|
|
.It sbmips-eb Ta sbmips Ta mipseb
|
|
.It sbmips-el Ta sbmips Ta mipsel
|
|
.El
|
|
.
|
|
.It Fl n
|
|
Show the commands that would be executed by
|
|
.Sy build.sh ,
|
|
but do not make any changes.
|
|
This is similar in concept to
|
|
.Dq make -n .
|
|
.
|
|
.It Fl O Ar obj
|
|
Create an appropriate transform macro for
|
|
.Sy MAKEOBJDIR
|
|
that will place the built object files under
|
|
.Ar obj .
|
|
For instance, a setting of
|
|
.Sy /usr/obj
|
|
will place build-time files under
|
|
.Sy /usr/obj/bin , /usr/obj/lib ,
|
|
and so forth.
|
|
.
|
|
.It Fl o
|
|
Set the value of
|
|
.Sy MKOBJDIRS
|
|
to
|
|
.Dq no .
|
|
Otherwise, it will be automatically set to
|
|
.Dq yes
|
|
(which is opposite to the default behaviour).
|
|
.
|
|
.It Fl R Ar rel
|
|
Set the value of
|
|
.Sy RELEASEDIR
|
|
to
|
|
.Ar rel .
|
|
.
|
|
.It Fl r
|
|
Remove the contents of
|
|
.Sy DESTDIR
|
|
and
|
|
.Sy TOOLDIR
|
|
before building (provides a clean starting point).
|
|
This will skip deleting
|
|
.Sy DESTDIR
|
|
if building on a native system to the root directory.
|
|
.
|
|
.It Fl T Ar tools
|
|
Set the value of
|
|
.Sy TOOLDIR
|
|
to
|
|
.Ar tools .
|
|
If set, the bootstrap
|
|
.Dq make
|
|
will only be rebuilt as needed (when the source files for
|
|
.Xr make 1
|
|
change).
|
|
.
|
|
.It Fl U
|
|
Set the
|
|
.Sy UNPRIVED
|
|
variable.
|
|
.
|
|
.It Fl u
|
|
Set the
|
|
.Sy UPDATE
|
|
variable.
|
|
.
|
|
.It Xo
|
|
.Fl V
|
|
.Sm off
|
|
.Ar var
|
|
.Li =
|
|
.Op Ar value
|
|
.Sm on
|
|
.Xc
|
|
Set the variable
|
|
.Ar var
|
|
to
|
|
.Ar value
|
|
(which is optional).
|
|
.
|
|
.It Fl w Ar wrapper
|
|
Create the \*[toolprefix]make wrapper script (see below) in a custom location,
|
|
specified by
|
|
.Ar wrapper .
|
|
This allows, for instance, to place the wrapper in
|
|
.Sy PATH
|
|
automatically.
|
|
Note that
|
|
.Ar wrapper
|
|
is the full name of the file, not just a directory name.
|
|
.
|
|
.El
|
|
.
|
|
.Ss The \*q\*[toolprefix]make-MACHINE\*q wrapper script
|
|
.
|
|
If using the
|
|
.Sy build.sh
|
|
script to build
|
|
.Nx ,
|
|
a
|
|
.Sy \*[toolprefix]make-MACHINE
|
|
script will be created in
|
|
.Sy TOOLDIR/bin
|
|
upon the first build to assist in building subtrees on a cross-compile
|
|
host.
|
|
.Pp
|
|
.Sy \*[toolprefix]make-MACHINE
|
|
can be invoked in lieu of
|
|
.Xr make 1 ,
|
|
and will instead call the up-to-date version of
|
|
.Dq \*[toolprefix]make
|
|
installed into
|
|
.Sy TOOLDIR/bin
|
|
with several key variables pre-set, including
|
|
.Sy MACHINE , MACHINE_ARCH ,
|
|
and
|
|
.Sy TOOLDIR .
|
|
This script can be symlinked into a directory listed in
|
|
.Sy PATH ,
|
|
or called with an absolute path.
|
|
.
|
|
.Sh EXAMPLES
|
|
.
|
|
.Bl -enum
|
|
.
|
|
.It
|
|
.Li "./build.sh tools kernel=GENERIC"
|
|
.Pp
|
|
Build a new toolchain, and use the new toolchain to
|
|
configure and build a new GENERIC kernel.
|
|
.
|
|
.It
|
|
.Li "./build.sh -U distribution"
|
|
.Pp
|
|
Using unprivileged mode,
|
|
build a complete distribution to a
|
|
.Sy DESTDIR
|
|
directory that
|
|
.Sy build.sh
|
|
selects (and will display).
|
|
.
|
|
.It
|
|
.Li "# ./build.sh -U install=/"
|
|
.Pp
|
|
As root, install to
|
|
.Pa /
|
|
the distribution that was built
|
|
by example 2.
|
|
Even though this is run as root,
|
|
.Fl U
|
|
is required so that the permissions stored in
|
|
.Sy DESTDIR Ns Pa /METALOG
|
|
are correctly applied to the files as they're copied to
|
|
.Pa / .
|
|
.
|
|
.It
|
|
.Li "./build.sh -U -u release"
|
|
.Pp
|
|
Using unprivileged mode,
|
|
build a complete release to
|
|
.Sy DESTDIR
|
|
and
|
|
.Sy RELEASEDIR
|
|
directories that
|
|
.Sy build.sh
|
|
selects (and will display).
|
|
.Sy UPDATE
|
|
.Pq Fl u
|
|
is set to prevent the
|
|
.Dq make cleandir ,
|
|
so that if this is run after example 2, it doesn't need to redo that
|
|
portion of the release build.
|
|
.El
|
|
.
|
|
.Sh OBSOLETE VARIABLES
|
|
.
|
|
.Bl -tag -width "NBUILDJOBS"
|
|
.
|
|
.It Sy NBUILDJOBS
|
|
Use the
|
|
.Xr make 1
|
|
option
|
|
.Fl j ,
|
|
instead.
|
|
.
|
|
.It Sy USE_NEW_TOOLCHAIN
|
|
The new toolchain is now the default.
|
|
To disable, use
|
|
.Sy TOOLCHAIN_MISSING=yes .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr make 1 ,
|
|
.Xr hier 7 ,
|
|
.Xr release 7
|
|
.
|
|
.Sh HISTORY
|
|
.
|
|
The
|
|
.Nm build.sh
|
|
based build scheme was introduced for
|
|
.Nx 1.6
|
|
as
|
|
.Sy USE_NEW_TOOLCHAIN ,
|
|
and re-worked to
|
|
.Sy TOOLCHAIN_MISSING
|
|
after that.
|
|
.
|
|
.Sh BUGS
|
|
.
|
|
A few platforms are not yet using this build system.
|