sysbuild.1.in

.\" Copyright 2012 Google Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\"   notice, this list of conditions and the following disclaimer.
.\" * 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.
.\" * Neither the name of Google Inc. 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 COPYRIGHT HOLDERS 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 COPYRIGHT
.\" OWNER 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.
.Dd February 10, 2017
.Dt SYSBUILD 1
.Os
.Sh NAME
.Nm sysbuild
.Nd performs fully automatic builds of NetBSD
.Sh SYNOPSIS
.Nm
.Op Fl c Ar config_name
.Op Fl o Ar variable=value
build
.Op Fl f
.Op Ar build_targets
.Nm
.Op Fl c Ar config_name
.Op Fl o Ar variable=value
config
.Nm
.Op Fl c Ar config_name
.Op Fl o Ar variable=value
env
.Op Ar machine
.Nm
.Op Fl c Ar config_name
.Op Fl o Ar variable=value
fetch
.Sh DESCRIPTION
.Nm
is a utility to build
.Nx
releases in a fully automated manner.
The process is made unattended by relying on a configuration file that
prespecifies the location of all build components and the desired goals of
the build.
If you want to plug
.Nm
into
.Xr cron 8 ,
please take a look to
.Xr sysbuild4cron 1
now.
.Pp
.Nm
can be seen as a simple wrapper over
.Xr cvs 1
and the
.Nm build.sh
script that ships with the
.Nx
source tree.
.Nm
provides the following additional features:
.Bl -bullet
.It
Automatically fetch or update the
.Nx
source trees (both src and xsrc)
before performing a build.
.It
Preconfigure the way
.Nm build.sh
is invoked by storing all relevant details in a configuration file.
.It
Perform builds for a variety of platforms with a single invocation.
.It
Trivially set up periodic
.Nx
rebuilds by adding a single line to your
.Xr crontab 5 .
.It
Hooks to plug other components into the build procedure.
For example: use
.Xr rsync 1
to push the results of a successful build to a file server.
.El
.Pp
As you can see in the
.Sx SYNOPSIS
section,
.Nm
provides a subcommand-interface: the tool has several modes of operation,
and the particular mode to use for a given run is selected by the first
non-option argument in the command line.
.Pp
The following options apply to all commands:
.Bl -tag -width XXXX
.It Fl c Ar config_name
Specifies the configuration file to use.
The format of the file is described in
.Xr sysbuild.conf 5 .
.Pp
If
.Ar config_name
includes any directory separator (aka, one or more slashes) or the
.Sq .conf
suffix, then this specifies the path of the configuration file to load.
.Pp
If
.Ar config_name
is a plain name without any directory components nor extension, then this
specifies the name of the configuration.
.Nm
will first look for a configuration file in
.Pa ~/.sysbuild/<config_name>.conf
and, if not found, will use
.Pa __SYSBUILD_ETCDIR__/<config_name>.conf .
Any of the two files must exist, or else
.Nm
will exit with an error.
.It Fl o Ar variable=value
Applies an override to the loaded configuration.
.Pp
The
.Ar variable
part of the argument must be any of the recognized configuration variables
described in
.Xr sysbuild.conf 5 .
The
.Ar value ,
if not empty, specifies the value to set the configuration variable to.
If
.Ar value
is empty, then the configuration variable is unset.
.El
.Ss The build command
The build command provides the main functionality of
.Nm .
It performs the following steps:
.Bl -enum
.It
If
.Va UPDATE_SOURCES
is true, the fetch command is invoked first.
See
.Sx The fetch command
for more details.
.It
For every machine type listed in
.Va MACHINES ,
issues a
.Nm build.sh
call for that particular machine using the rest of the settings defined in
the configuration file.
The targets passed to the
.Nm build.sh
script are those defined in the
.Va BUILD_TARGETS
variable, or the arguments passed through the command line if any.
.El
.Pp
The following options apply only to the build command:
.Bl -tag -width XXXX
.It Fl f
Enables fast mode, which skips updating the source trees and performs
update builds.
This is a shorthand for these generic flags:
.Fl o Ar INCREMENTAL_BUILD=true
.Fl o Ar UPDATE_SOURCES=false .
.El
.Ss The config command
The config command dumps the loaded configuration to the standard output.
The format of the output is not a script, so it cannot be fed back into
.Nm .
The purpose of this command is to aid in debugging the configuration of the
tool before performing any builds, particularly when the configuration
files use shell logic to determine the value of any variables.
.Ss The env command
The env command prints a shell script snippet that defines environment variables
to simplify working with the directory layout of a
.Nx
build for a particular machine.
If the
.Va MACHINES
variable is not defined, or if it lists more than one machine, then the
.Ar machine
argument is required.
.Pp
The common mechanism to use these variables is by executing
.Nm
in the following way:
.Bd -literal -offset indent
$ eval $(sysbuild env)
.Ed
.Pp
The following variables are defined and/or modified:
.Bl -tag -width PATH
.It Va PATH
The path to the tools is prepended to the path.
Of particular interest is the
.Pa nbmake-<machine>
script made available in this way, which allows you to build arbitrary targets
within the source directory using the tools.
.It Va D
Path to the destdir.
.It Va O
Path to the objects directory for the source tree.
.It Va S
Path to the source tree.
.It Va T
Path to the tools.
Note that this points to the root of the tools, not their
.Pa bin
subdirectory.
.It Va XO
If
.Va XSRCDIR
is defined, path to the objects directory for the X source tree.
.It Va XS
If
.Va XSRCDIR
is defined, path to the X source tree.
.El
.Pp
And the following functions are defined:
.Bl -tag -width curobj
.It Fn curobj
When invoked from a subdirectory of either src or xsrc, prints the path to that
same subdirectory within the objects hierarchy.
You may use this to reference temporary build files easily when you are working
within the source tree as follows:
.Bd -literal -offset indent
$ cd /usr/src/bin/ls
/usr/src/bin/ls$ nbmake-amd64
/usr/src/bin/ls$ cd $(curobj)
/usr/obj/usr/src/bin/ls$
.Ed
.El
.Ss The fetch command
The fetch command downloads or updates the
.Nx
source trees, which include src and, optionally, xsrc.
.Pp
If the modules do not exist yet in the locations specified by
.Va SRCDIR
and
.Va XSRCDIR ,
this performs an initial CVS checkout of the trees.
If the modules exist, this performs a CVS update.
.Pp
The
.Va CVSROOT
and
.Va CVSTAG
variables are used to determine where to get the sources from and whether a
particular tag is desired.
.Pp
The major use of this subcommand is the following.
Consider that you wish to use the standard locations of
.Pa /usr/src
and
.Pa /usr/xsrc
for your source trees, and that you would like to keep these owned by root
while, at the same time, you run your
.Nx
builds as an unprivileged user.
In this situation, you can use the
.Sq fetch
command as root only, set
.Va UPDATE_SOURCES
to
.Sq false
in your user configuration files, and do your builds as another user.
.Sh FILES
.Bl -tag -width XXXX
.It Pa __SYSBUILD_ETCDIR__/
Directory containing all system-wide configuration files.
.It Pa __SYSBUILD_ETCDIR__/default.conf
Default configuration file to load if the user does not have a
corresponding
.Pa ~/.sysbuild/default.conf
file and the
.Fl c
flag is not provided.
.It Pa ~/.sysbuild/
Directory containing all user-specific configuration files.
.It Pa ~/.sysbuild/default.conf
Default configuration file to load when the
.Fl c
flag is not provided.
.El
.Sh SEE ALSO
.Xr cvs 1 ,
.Xr sysbuild4cron 1 ,
.Xr sysbuild.conf 5 ,
.Xr hier 7 ,
.Pa /usr/src/BUILDING
.Sh HISTORY
.Nm
1.x existed in pkgsrc from November 28th, 2002 to June 1st, 2004.
The package was removed from the tree because NetBSD's
.Nm build.sh
had improved enough to make the 1.x series of
.Nm
unnecessary, and also because
.Nm
1.x did not work with
.Nx 2.0
and above.
.Pp
.Nm
2.x, documented here, first appeared on July 25, 2012 as a full rewrite of
the original tool.
The new codebase is much more robust and comes with detailed unit and
integration tests to ensure its functionality.
Fun fact: the generous paternity leave I got from Google for my first child
is what gave me the time to work on the 2.0 release.
.Pp
See
.Pa __SYSBUILD_DOCDIR__/NEWS
for more details on the changes across releases.
.Sh AUTHORS
The
.Nm
utility was developed by
.An Julio Merino
.Aq jmmv@google.com .