A few things in BUILDING have gone out of date, and also,
some things
that should be are not documented (e.g. how build.sh -u
interacts with
kernel=foo). I have done an editing pass and propose the
following
patch.
The highlights:
- mention src/tests and reference atf;
- provide examples of MACHINE and MACHINE_ARCH -- someone
please
double-check these to make sure I haven't lied;
- mention that MKOBJ=no is not recommented;
- correct the default setting of USETOOLS;
- document the interaction of build.sh -[uo] with various
things;
- document the interaction of build.sh tools and
kernel=foo;
- various typo fixes and wording adjustments, and use
fewer
parentheses.
Index: BUILDING.mdoc
============================================================
=======
RCS file: /cvsroot/src/doc/BUILDING.mdoc,v
retrieving revision 1.55
diff -U 10 -r1.55 BUILDING.mdoc
--- BUILDING.mdoc 8 Mar 2008 14:48:57 -0000 1.55
+++ BUILDING.mdoc 10 Mar 2008 05:59:47 -0000
 -120,23
+120,30
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/
+.It Sy tests/ , regress/
Regression test harness.
Can be cross-compiled, but only run natively.
+.Pa tests/
+uses the
+.Xr atf 7
+test framework;
+.Pa regress/
+contains older tests that have not yet been migrated to
+.Xr atf 7 .
.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
-190,24
+197,26
.Li $ build.sh Op Ar options
.Ed
.
.It Sy HOST_CC
Path name to C compiler used to create the toolchain.
.
.It Sy HOST_CXX
Path name to C++ compiler used to create the toolchain.
.
.It Sy MACHINE
-Machine type.
+Machine type, e.g.,
+.Dq macppc .
.
.It Sy MACHINE_ARCH
-Machine architecture.
+Machine architecture, e.g.,
+.Dq powerpc .
.
.It Sy MAKE
Path name to invoke
.Xr make 1
as.
.
.It Sy MAKEFLAGS
Flags to invoke
.Xr make 1
with.
-314,21
+323,21
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
+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 MAKEVERBOSE
-414,20
+423,27
.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
+.Pp
+Note that setting
+.Sy MKOBJ
+to
+.Dq no
+is not recommended and may cause problems when updating the
tree with
+.Xr cvs 1 .
.
.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.
-551,30
+567,21
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).
+.DFLTy
.
.It Sy X11SRCDIR
Directory containing the X11R6 source.
If specified, must be an absolute path.
The main X11R6 source is found in
.Sy X11SRCDIR Ns Pa /xfree/xc .
.DFLT
.Dq /usr/xsrc
.
.El
-596,49
+603,71
.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
+.Pp
+If using
+.Sy build.sh ,
+the default is
+.Dq yes .
+This may be set back to
+.Dq no
+by giving
+.Sy build.sh
+the
+.Fl o
+option.
.
.It Sy MKUPDATE
.YorN
If set, then in addition to the effects described for
.Sy MKUPDATE=yes
above, this implies the effects of
.Sy NOCLEANDIR
(i.e.,
.Dq make cleandir
is avoided).
.DFLTn
+.Pp
+If using
+.Sy build.sh ,
+this may be set by giving the
+.Fl u
+option.
.
.It Sy NBUILDJOBS
Now obsolete.
Use the
.Xr make 1
option
.Fl j ,
-instead (see below)
+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
+.Pp
+See also
+.Sy MKUPDATE .
.
.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
-650,40
+679,40
.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 MKUPDATE=yes
-in that case.
+instead 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 .
If specified, must be an absolute path.
.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
+mode.
.
.El
.
.Sh BUILDING
.
.Ss *qmake*q command line options
This is not a summary of all the options available to
.Xr make 1 ;
only the options used most frequently with
.Nx
-704,21
+733,22
.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.)
+This is set automatically when building from the top level,
or when using
+.Sy build.sh .
.
.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
-854,90
+884,90
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).
+.Sy INSTALLWORLDDIR ,
+which defaults to the root directory.
Ensures that
.Sy INSTALLWORLDDIR
is not the root directory if cross compiling.
.Pp
The
.Sy INSTALLSETS
environment variable may be set to a list of
distribution sets to be installed.
By default, all sets except
.Dq etc
and
.Dq xetc
-are installed (so most files in
+are installed, so most files in
.Sy INSTALLWORLDDIR Ns Pa /etc
-will not be installed or modified).
+will not be installed or modified.
.Pp
.Em Note :
Before performing this operation with
.Sy INSTALLWORLDDIR Ns = Ns Pa / ,
it is highly recommended that you upgrade your kernel and
reboot.
After performing this operation,
it is recommended that you use
.Xr etcupdate 8
to update files in
.Sy INSTALLWORLDDIR Ns Pa /etc
and that you use
.Xr postinstall 8
to check for inconsistencies (and possibly to fix them).
.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 distribution ,
+as
.Dq make build
-does not install all of the required files).
+alone 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 syspkgs
Create syspkgs from
.Sy DESTDIR
into
.Sy RELEASEDIR/MACHINE Ns Pa /binary/syspkgs .
Should be run after
-.Dq make distribution
-(as
+.Dq make distribution ,
+as
.Dq make build
-does not install all of the required files).
+alone does not install all of the required files.
.
.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 iso-image
+.It Sy iso-image
Create a
.Nx
installation CD-ROM image in the
.Sy RELEASEDIR Ns Pa /iso
directory.
The CD-ROM file system will have a layout as described in
.Xr release 7 .
.Pp
For most machine types, the CD-ROM will be bootable, and
will automatically
run the
-1013,21
+1043,24
This requires the
.Xr mkisofs 1
utility, which is not part of
.Nx ,
but which can be installed from
.Pa pkgsrc/sysutils/cdrtools .
.
.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.
+Runs those compiled regression tests on the local host.
+Note that most tests are now managed instead using
+.Xr atf 7 ;
+this target will disappear when all tests have been
migrated.
.
.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 ,
-1062,54
+1095,72
.
.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
+Before the main part of the build commences, this command
runs the
.Sy obj
-and
+operation (unless the
+.Fl o
+option is given),
+.Dq make cleandir
+(unless the
+.Fl u
+option is given),
+and the
.Sy tools
-operations.
+operation.
.
.It Sy distribution
Build a full distribution as per
.Dq make distribution .
-This option implies the
+This command first runs the
.Sy build
operation.
.
.It Sy release
Build a full release as per
.Dq make release .
-This option implies the
+This command first runs 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 .
+This command will first run
+.Dq make obj
+and
+.Dq make cleandir
+in the
+.Pa tools
+subdirectory unless the
+.Fl o
+or
+.Fl u
+options (respectively) are given.
.
.It Sy install Ns = Ns Ar idir
Install the contents of
.Sy DESTDIR
to
.Ar idir ,
using
.Dq make installworld .
Note that files that are part of the
.Dq etc
-1130,29
+1181,41
.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
+.Pp
+This command does
+.Em not
+imply the
+.Sy tools
+command; run the
.Sy tools
-operation).
+command first unless it is
+.Em certain
+that the tools already exist and are up to date.
+.Pp
+This command will run
+.Dq make cleandir
+on the kernel in question first unless the
+.Fl u
+option is given.
.
.It Sy releasekernel Ns = Ns Ar kconf
Install a
.Xr gzip 1 Ns ed
-copy of the kernel built by
+copy of the kernel previously 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
-1238,21
+1301,25
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 h
Print a help message.
.
.It Fl j Ar njob
-Passed through to
+Run up to
+.Ar njob
+.Xr make 1
+subjobs in parallel;
+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
-1335,22
+1402,23
and so forth.
Unsets
.Sy MAKEOBJDIRPREFIX .
.
.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).
+.Dq yes .
+This default is opposite to the behaviour when not using
+.Sy build.sh .
.
.It Fl R Ar rel
Set the value of
.Sy RELEASEDIR
to
.Ar rel .
If a relative path is specified, it will be converted to
an
absolute path before being used.
.
.It Fl r
-1365,23
+1433,23
.
.It Fl T Ar tools
Set the value of
.Sy TOOLDIR
to
.Ar tools .
If a relative path is specified, it will be converted to
an
absolute path before being used.
If set, the bootstrap
.Dq make
-will only be rebuilt as needed (when the source files for
+will only be rebuilt if the source files for
.Xr make 1
-change).
+have changed.
.
.It Fl U
Set
.Sy MKUNPRIVED=yes .
.
.It Fl u
Set
.Sy MKUPDATE=yes .
.
.It Xo
-1453,21
+1521,21
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 .
-.Sy build.sh
+.Sy *[toolprefix]make-MACHINE
will also set variables specified with
.Fl V ,
and unset variables specified with
.Fl Z .
.Pp
This script can be symlinked into a directory listed in
.Sy PATH ,
or called with an absolute path.
.
.Sh EXAMPLES
-1524,21
+1592,21
.El
.
.Sh OBSOLETE VARIABLES
.
.Bl -tag -width "NBUILDJOBS"
.
.It Sy NBUILDJOBS
Use the
.Xr make 1
option
-.Fl j ,
+.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 ,
--
David A. Holland
dhollandnetbsd.org
|