.\"-
.\" Copyright (c) 2003-2014 Dag-Erling Smørgrav
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD$
.\"
.Dd May 24, 2014
.Dt TINDERBOX 1
.Os
.Sh NAME
.Nm tinderbox
.Nd build and release testing
.Sh SYNOPSIS
.Nm
.Op options
.Ar command Op ...
.Op Ar variable Ns = Ns Ar value ...
.Sh DESCRIPTION
The
.Nm
script tests the
.Fx
build and release system by performing a cross-build (and optionally a
cross-release) of an arbitrary branch of the source tree for an
arbitrary target platform.
.Pp
The following options are recognized:
.Bl -tag -width 12n
.It Fl -arch Ns = Ns Ar ARCH
Specifies the target architecture
.Pq Va $arch .
The default value is whatever the host system's
.Xr uname 1
reports.
.It Fl -branch Ns = Ns Ar BRANCH
The branch to check out from
.Xr svn 1
when updating the source tree
.Pq Va $branch .
The default is to check out HEAD.
For historical compatibility,
.Xr cvs 1 Ns -style
branch names are translated to
.Xr svn 1
paths; for instance,
.Dv RELENG_9
becomes
.Pa stable/9
and
.Dv RELENG_9_1
becomes
.Pa releng/9.1 .
.It Fl -destdir Ns = Ns Ar DIR
The directory (aka
.Dv DESTDIR )
in which the results of the build will be installed if the
.Cm install
command is specified.
The default is
.Pa $SANDBOX/inst .
.It Fl -hostname Ns = Ns Ar NAME
The name of the host running the tinderbox.
This defaults to the name reported by the
.Fl n
option of the
.Xr uname 1
command, and is only used for cosmetic purposes.
.It Fl -jobs Ns = Ns Ar NUM
The maximum number of paralell jobs
.Pq Va $jobs ,
as specified to
.Xr make 1
using the
.Fl j
option.
The default is 1.
.It Fl -logfile Ns = Ns Ar FILE
The name of a file to which the output and error messages produced by
the build should be written.
Note that this file can grow quite large.
The default is to redirect all output to
.Pa /dev/stdout .
.It Fl -machine Ns = Ns Ar MACHINE
Specifies the target machine
.Pq Va $machine .
The default value is whatever the host system's
.Xr uname 1
reports, unless a target architecture was specified with the
.Fl -arch
option, in which case the target machine is set to the same value.
.It Fl -objdir Ns = Ns Ar DIR
Specifies the object directory prefix
.Pq Va $objdir .
.It Fl -patch Ns = Ns Ar PATCH
The file name of a patch to apply to the source tree before building
if the
.Cm patch
command is specified.
The patch should be relative to the root of the source tree.
When building a release, the patch is passed to the release process
through the
.Ev LOCAL_PATCHES
environment variable (see
.Xr release 7
for more information), regardless of whether the
.Cm patch
command was specified.
The default is to not apply any patches.
.It Fl -sandbox Ns = Ns Ar DIR
The location of the sandbox in which the builds are to take place.
This directory should reside on a reasonably fast disk with at least
1.5 GB available (3 GB if building a release).
.It Fl -srcdir Ns = Ns Ar DIR
Specifies the source directory
.Pq Va $srcdir .
Normally, the
.Nm
script creates a separate source directory within the sandbox for each
branch, architecture and platform.
This option allows a single source directory to be shared between
multiple architectures and platforms.
This may simplify the process of build-testing modified sources, and,
depending on the exact setup, speed up the build significantly.
.Pp
Note that it is generally not a good idea to combine this with any of
the
.Dq preclean ,
.Dq precleansrc
or
.Dq update
commands.
.It Fl -svnbase Ns = Ns Ar URL
The URL to the base of the Subversion repository.
The default is
.\" There does not seem to be an mdoc macro for URLs; use Pa instead.
.Pa svn://svn.freebsd.org/base .
.It Fl -timeout Ns = Ns Ar NUM
The maximum wall-time duration of the run, in seconds.
The default is to continue until all targets are completed.
.It Fl -verbose
Enable additional debugging output.
.El
.Pp
Following the options on the command line, at least one of the
following commands must be specified:
.Bl -tag -width 12n
.It Cm clean
Alias for
.Cm preclean .
.It Cm cleansrc
Alias for
.Cm precleansrc .
.It Cm cleanobj
Alias for
.Cm precleanobj .
.It Cm cleaninst
Alias for
.Cm precleaninst .
.It Cm cleanroot
Alias for
.Cm precleanroot .
.It Cm preclean
Delete the source, object, installation and release trees at the
start of each job.
See
.Cm precleansrc ,
.Cm precleanobj ,
.Cm precleaninst
and
.Cm precleanroot
below.
.It Cm precleansrc
Delete the source tree at the start of each job.
This is highly recommended when sources are patched, as successive
builds will fail due to repeated application of the same patch to the
same sources.
.It Cm precleanobj
Delete the object tree at the start of each job.
.It Cm precleaninst
Delete the installation tree at the start of each job.
.It Cm precleanroot
Delete the release chroot tree at the start of each job.
.It Cm revert
Revert the source tree to a clean state.
.It Cm update
Update the source tree using
.Xr svn 1 .
.It Cm patch
Apply the patch specified with the
.Fl -patch
option to the source tree.
If the specified patch file does not exist, the
.Cm patch
command will fail gracefully.
.It Cm version
After updating and patching the source tree but before doing anything
else, log information about the current state of the source tree.
.It Cm world
Build the world.
.It Cm lint
Build LINT kernels if available.
In
.Fx
5 and newer, the
.Pa LINT
configuration files will first be generated from the corresponding
.Pa NOTES
file.
If there are no
.Pa LINT
configurations in the kernel configuration directory and
.Pa NOTES
does not exist, the
.Cm lint
command will fail gracefully.
.It Cm kernel: Ns Ar CONF
Build the
.Ar CONF
kernel.
If a file named
.Ar CONF
does not exist in the kernel configuration directory, this command
will fail gracefully.
.It Cm generic
Equivalent to
.Cm kernel: Ns Ar GENERIC ,
for backward compatibility.
.It Cm kernels
Build all available kernel configurations other than
.Pa LINT .
.It Cm install
Install the result of the build into
.Pa ${DESTDIR} .
Each kernel that was built will be installed into a subdirectory of
.Pa ${DESTDIR}/boot
named after the corresponding kernel configuration file.
.It Cm release
Build a release by following the procedure described in
.Xr release 7 .
Note that this is a lengthy process which requires root privileges.
.It Cm postclean
As
.Cm preclean ,
but at the end of each job.
.It Cm cleansrc
As
.Cm precleansrc ,
but at the end of each job.
.It Cm cleanobj
As
.Cm precleanobj ,
but at the end of each job.
.It Cm cleaninst
As
.Cm precleaninst ,
but at the end of each job.
.It Cm cleanroot
As
.Cm precleanroot ,
but at the end of each job.
.El
.Pp
The commands are executed in the order in which they are listed above,
regardless of the order in which they are listed on the command line.
.Pp
Finally, any arguments of the form
.Ar variable Ns = Ns Ar value
are interpreted as environment variables which are exported into the
build environment.
These variables are not allowed to override those set by the script
itself (see
.Sx ENVIRONMENT
below).
.Sh NOTES
The
.Nm
script was originally written to perform daily build testing of
.Fx
4 and 5.
It is not intended for use with older releases, and probably will not
work with anything older than
.Fx 4.2 .
.Sh ENVIRONMENT
The
.Nm
script clears its environment at startup and provides its child
processes with a tailored environment.
The following variables are set for all builds:
.Bl -tag -width 18n
.It PATH
.Ar /usr/bin:/usr/sbin:/bin:/sbin
.It TZ
.Ar UTC
.It __MAKE_CONF
.Ar /dev/null
.It SRCCONF
.Ar /dev/null
.It MAKEOBJDIRPREFIX
.Ar $objdir
.It TARGET
.Ar $machine
.It TARGET_ARCH
.Ar $arch
.It CROSS_BUILD_TESTING
.Ar YES
.El
.Pp
The following additional variables are set for release builds:
.Bl -tag -width 18n
.It CHROOTDIR
.Ar $SANDBOX/root
.It RELEASETAG
.Ar -r$branch
if specified using the
.Fl -branch
option, or
.Ar -A
otherwise.
.It WORLD_FLAGS , KERNEL_FLAGS
Both of these are set to
.Ar -j$jobs
if specified using the
.Fl -jobs
option, or
.Ar -B
otherwise.
.It LOCAL_PATCHES
Set to the path of the patch that was specified with the
.Fl -patch
option, if any.
.It PATCH_FLAGS
Set to
.Ar -fs
if a patch was specified.
.It NOCDROM
.Ar YES
.It NODOC
.Ar YES
.It NOPORTS
.Ar YES
.El
.Pp
None of these variables may be overridden by command-line arguments.
.Sh SEE ALSO
.Xr make 1 ,
.Xr patch 1 ,
.Xr svn 1 ,
.Xr tbmaster 1 ,
.Xr build 7 ,
.Xr release 7
.Sh AUTHORS
The
.Nm
script was written by
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
.Sh BUGS
are crunchy and nutritious.