321 lines
8.7 KiB
Groff
321 lines
8.7 KiB
Groff
.\" $NetBSD: sysbuild.1,v 1.7 2013/03/08 17:47:26 jmmv Exp $
|
|
.\" 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 March 8, 2013
|
|
.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 AUTHORS
|
|
The
|
|
.Nm
|
|
utility was developed by
|
|
.An Julio Merino
|
|
.Aq jmmv@NetBSD.org .
|