.\"-
.\" 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 March 24, 2014
.Dt TBMASTER 1
.Os
.Sh NAME
.Nm tbmaster
.Nd manage tinderbox runs
.Sh SYNOPSIS
.Nm
.Op options
.Sh DESCRIPTION
The
.Nm
script manages
.Xr tinderbox 1
runs, generates log summaries, and mails out failure reports.
.Pp
The following options are recognized:
.Bl -tag -width 12n
.It Fl a , Fl -abbreviate
Abbreviate path names in the log file.
Every occurrence of the source directory will be replaced with
.Dq /src ,
and every occurrence of the object directory with
.Dq /obj .
The resulting output should be exactly the same as if the source and
object directories really were
.Pa /src
and
.Pa /obj ,
respectively.
.It Fl c Ar NAME , Fl -config Ns = Ns Ar NAME
The name of the configuration to use.
If specified multiple times, all listed configurations will be run in
sequence.
The default value is the hostname minus the domain part.
.It Fl d , Fl -dump
Dumps the configuration and exits without running the tinderbox.
.It Fl e Ar DIR , Fl -etcdir Ns = Ns Ar DIR
The directory where configuration files are located.
The default value is
.Pa $HOME/etc .
.It Fl h Ar HOSTNAME , Fl -hostname Ns = Ns Ar HOSTNAME
The name of the host running the tinderbox, used in logs and reports.
Can be overridden by the
.Va HOSTNAME
configuration variable.
The default value is that reported by
.Xr uname 1 .
.It Fl l Ar FILE , Fl -lockfile Ns = Ns Ar FILE
The name of a file to lock upon startup.
If the lock is already held by another process,
.Nm
will terminate immediately rather than block.
.It Fl n Ar NUMBER , Fl -ncpu Ns = Ns Ar NUMBER
The maximum number of concurrent builds to run.
Can be overridden by the
.Va NCPU
configuration variable.
The default value is the number of cores in the machine, or 1 if that
number could not be determined.
See the
.Sx Concurrency
section for additional information.
.El
.Ss Configuration files
The
.Nm
script uses named configurations located in individual files named for
the setup they describe, with a
.Pa .rc
suffix.
For instance, the
.Dq snoosnoo
configuration is contained in
.Pa snoosnoo.rc .
.Pp
In addition,
.Nm
attempts to read
.Pa default.rc
and
.Pa site.rc
before and after the actual configuration file, respectively; thus,
they can be used to specify default values shared by multiple
configurations and to override the values set in the individual
configuration files.
.Pp
Each configuration file consists of a list of single- or
multiple-value variable assignments:
.Bl -tag
.It Va variable No = Ar value
Assigns
.Ar value
to the single-value variable
.Va variable .
.It Va variable No = Ar value1 Op No , Ar value2 ...
Assigns
.Ar value1 ,
.Ar value2
etc. to the multi-value variable
.Va variable .
.It Va variable No += Ar value3 Op No , Ar value4 ...
Appends
.Ar value3 ,
.Ar value4
etc. to the multi-value variable
.Va variable .
.It Va variable No -= Ar value5 Op No , Ar value6 ...
Removes
.Ar value5 ,
.Ar value6
etc. from the multi-value variable
.Va variable .
.El
.Pp
Whitespace around the assigment operator and around the commas
separating multiple values is optional.
.Pp
Blank lines are ignored, as is anything following a hash sign
.Pq Sq # .
.Pp
Additionally,
.Cm include
statements can be used to include one configuration in another:
.Bl -tag
.It Cm include Ar otherconfig
.El
.Ss Configuration variables
Below is a list of the configuration variables
.Nm
recognizes and their semantics.
.Pp
Note that many of these variables are passed on as command-line
arguments to
.Xr tinderbox 1 ,
which may provide its own default values for variables which are left
undefined by
.Nm .
.Pp
Some variables are read-only and are provided so that other variables
may include them.
For instance, a common idiom is to derive
.Va OBJDIR
from a combination of
.Va BRANCH ,
.Va ARCH
and
.Va MACHINE .
.Bl -tag -width 12n
.It ARCH
.Pq Vt single, read-only
The architecture currently being built for.
.It BRANCH
.Pq Vt single, read-only
The branch currently being built.
.It BRANCHES
.Pq Vt multiple
A list of source branches to build.
The default value is
.Dq HEAD .
.It CFLAGS
.Pq Vt single
The desired value for the
.Va CFLAGS
.Xr make 1
variable.
This is equivalent to specifying
.Va CFLAGS
in
.Va ENV .
No default value.
.It COPTFLAGS
.Pq Vt single
The desired value for the
.Va COPTFLAGS
.Xr make 1
variable.
This is equivalent to specifying
.Va COPTFLAGS
in
.Va ENV .
No default value.
.It COMMENT
.Pq Vt single
A terse comment describing the setup.
No default value.
.It ENV
.Pq Vt multiple
A list of environment variables to pass to the
.Xr tinderbox 1
script.
Each value is the name and value of an environment variable, separated
by an equal sign
.Pq Sq = .
No default value.
.It HOME
.Pq Vt single, read-only
The current user's home directory, as specified by the
.Ev HOME
environment variable.
Note that it will not be defined unless it passes some simple sanity
checks.
.It HOSTNAME
.Pq Vt single
The name of the host running the tinderbox.
.It JOBS
The maximum number of concurrent
.Xr make 1
processes to run within each build.
No default value.
See the
.Sx Concurrency
section for additional information.
.It LOGDIR
.Pq Vt single
The location of the log directory.
The default value is
.Pa ${SANDBOX}/logs .
.It MACHINE
.Pq Vt single, read-only
The machine currently being built for.
.It NCPU
.Pq Vt single
The maximum number of concurrent builds to run.
No default value.
See the
.Sx Concurrency
section for additional information.
.It OBJDIR
.Pq Vt single
The object directory.
No default value.
.It OPTIONS
.Pq Vt multiple
A list of additional options to pass to the
.Xr tinderbox 1
script.
No default value.
.It PATCH
.Pq Vt single
The file name (either absolute, or relative to the sandbox directory)
of the patch to apply if the
.Dq patch
command is specified.
No default value.
.It PLATFORMS
.Pq Vt multiple
Which architectures and machines to build for.
Each value is the name of an architecture, optionally followed by a
forward slash
.Pq Sq /
and a machine name.
If the machine name is not specified, it is assumed to be identical to
the architecture name.
The default value is
.Dq i386 .
.It RECIPIENT
.Pq Vt multiple
The addresses to which failure reports should be mailed.
The default value is
.Dq ${SENDER} .
.Pp
To avoid unintentional spamming,
.Nm
will strip recipients in the
.Li freebsd.org
domain from this list unless the correct magic sauce is used.
.It SANDBOX
.Pq Vt single
The location of the sandbox directory.
The default value is
.Pa /tmp/tinderbox .
.It SENDER
.Pq Vt single
The envelope sender to use when mailing out failure reports.
This should be a single email address.
No default value.
.It SRCDIR
.Pq Vt single
The source directory.
No default value.
.Pp
Normally, a separate directory within the sandbox will be used for
each build.
Using a shared source directory for all builds reduces disk space
requirements and speeds up the build.
Note that it is generally not a good idea to combine this with any of
the
.Dq clean ,
.Dq cleansrc
or
.Dq update
targets.
.It SUBJECT
.Pq Vt single
The subject to use on failure reports.
The default value is
.Dq Tinderbox failure on ${arch}/${machine} .
.It SVNBASE
.Pq Vt single
The URL to the base of the Subversion repository.
No default value.
.It TARGETS
.Pq Vt multiple
A list of targets (commands) to pass to the
.Xr tinderbox 1
script.
The default value is
.Dq update, world .
.It TIMEOUT
.Pq Vt single
The number of seconds after which each tinderbox invocation will time
out.
No default value.
.It TINDERBOX
.Pq Vt single
The location of the
.Xr tinderbox 1
script.
The default value is
.Dq ${HOME}/bin/tinderbox .
.It URLBASE
.Pq Vt single
If defined, a URL constructed by appending the file name of the full
log file to the expanded value of this variable will be included in
failure reports.
There is no default value.
.El
.Ss Variable Substitution
All configuration variables are subject to variable substitution
immediately before use:
.Bl -bullet
.It
If a single-value variable contains substrings of the form
.Va ${VAR}
or
.Va ${var} ,
those substrings are replaced with the values of the corresponding
variables, after recursive substitution.
The difference between the first and the second form is that the
latter is converted to lower-case before use.
For instance,
.Dq ${BRANCH}
might expand to
.Dq RELENG_4
while
.Dq ${branch}
would expand to
.Dq releng_4 .
.It
If a single-value varaible contains substrings of the form
.Va $ENV{VAR} ,
those substrings are replaced with the values of the corresponding
environment variables.
Use this with care.
.It
If an element of a multiple-value variable is of the form
.Va ${VAR}
or
.Va ${var}
and the corresponding variable is a multiple-value variable, recursive
substitution is first performed on that variable, and the resulting
values are included individually in the result.
.It
Otherwise, elements of multiple-value variables are expanded
individually according to the same rules as single-value variables.
.El
.Pp
For backward compatibility with earlier versions, the forms
.Va %%VAR%%
and
.Va %%var%%
may be used instead of
.Va ${VAR}
and
.Va ${var} .
.Ss Concurrency
On multiprocessor machines, performance can generally be improved by
running multiple builds in parallel, up to a certain limit.
By default,
.Nm
will run one build for each processor core in the system.
This can be overridden with the
.Fl -ncpu
command-line option and the
.Va NCPU
configuration variable, the latter taking precedence.
.Pp
In addition, each build may run multiple
.Xr make 1
processes in parallel, up to the number specified by the
.Va JOBS
configuration variable.
.Pp
The total number of parallel
.Xr make 1
processes will vary, but can be as high as the product of of
.Va NCPU
and
.Va JOBS.
As a result of processor, memory and filesystem contention, an
excessively large value can have a significant negative impact on
performance.
.Pp
As a rule of thumb,
.Va NCPU
should not exceed one build per gigabyte of physical memory in the
system, and the
.Va NCPU
x
.Va JOBS
product should not exceed the number of processor cores in the system
by a large amount.
.Sh SEE ALSO
.Xr tinderbox 1
.Sh AUTHORS
.Nm
was written by
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
.Sh BUGS
- part of a complete breakfast!