path: root/tools/tools/tinderbox/tbmaster.1

.\"-
.\" Copyright (c) 2003 Dag-Erling Coïdan 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.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" 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 2, 2006
.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 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 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 is
.Pa $HOME/etc .
.It Fl l 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.
.El
.Ss Configuration
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 reading the actual configuration file; thus, these files may be
used to specify default values shared by multiple configurations.
.Pp
The configuration consists of a list of single- or multiple-value
variable assignments:
.Bl -tag
.It Va single_variable = Ar value
.It Va multi_variable = Ar value1 , Ar value2, ...
.It Va multi_variable += Ar value3 , ...
.El
.Pp
Whitespace around the equal sign and around the commas separating
multiple values is optional.
.Pp
Blank lines are ignored, as is anything following a hash sign
.Pq Dq # .
.Pp
The following configuration variables are defined:
.Bl -tag -width 12n
.It ARCH
.Pq Vt single
The architecture currently being built for.
Read-only.
.It BRANCH
.Pq Vt single
The branch currently being built.
Read-only.
.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 CVSUP
.Pq Vt single
The name of the
.Xr cvsup 1
server to use.
No default value.
.It DATE
.Pq Vt single
The date to use when checking out sources, or
.Dq today
for today's sources.
If left undefined, the top of each branch is used.
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 Dq = .
No default value.
.It HOME
.Pq Vt single
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.
Read-only.
.It HOSTNAME
.Pq Vt single
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 JOBS
The maximum number of concurrent
.Xr make 1
jobs to run.
No default value.
.It LOGDIR
.Pq Vt single
The location of the log directory.
The default value is
.Pa %%SANDBOX%%/logs .
.It MACHINE
.Pq Vt single
The machine currently being built for.
Read-only.
.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 Dq /
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 single
The address to which failure reports should be mailed.
No default value.
.It REPOSITORY
.Pq Vt single
The location of the
.Xr cvs 1
repository.
No default value.
.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 SUBJECT
.Pq Vt single
The subject to use on failure reports.
The default value is
.Dq Tinderbox failure on %%arch%%/%%machine%% .
.It TARGETS
.Pq Vt multiple
A list of targets (commands) to specify to the
.Xr tinderbox 1
script.
The default is
.Dq world .
.It TIMEOUT
The number of seconds after which each tinderbox invocation will time
out.
No default value.
.It TINDERBOX
The location of the
.Xr tinderbox 1
script.
The default value is
.Dq %%HOME%%/bin/tinderbox .
.El
.Pp
Fields which are left undefined are filled in from the
.Dq global
setup.
.Ss Variable Substitution
All single-valued configuration variables are subject to variable
substitution immediately before use.
If a variable's value contains strings of the form
.Va %%VAR%%
or
.Va %%var%% ,
those strings are replaced with the values of the corresponding
variables.
The difference between the first and the second form is that the
latter expands to lower-case.
For instance,
.Dq %%BRANCH%%
might expand to
.Dq RELENG_4
while
.Dq %%branch%%
would expand to
.Dq releng_4 .
.Sh SEE ALSO
.Xr perl 1 ,
.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!