SYSBUILD(1)

NAME
sysbuild - performs fully automatic builds of NetBSD

SYNOPSIS
sysbuild [-c config_name] [-o variable=value] build [-f] [build_targets]
sysbuild [-c config_name] [-o variable=value] config
sysbuild [-c config_name] [-o variable=value] env [machine]
sysbuild [-c config_name] [-o variable=value] fetch

DESCRIPTION
sysbuild is a utility to build NetBSD 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 sysbuild into cron(8), please take a look to sysbuild4cron(1) now.

sysbuild can be seen as a simple wrapper over cvs(1) and the build.sh script that ships with the NetBSD source tree. sysbuild provides the following additional features:

•   Automatically fetch or update the NetBSD source trees (both src and xsrc) before performing a build.

•   Preconfigure the way build.sh is invoked by storing all relevant details in a configuration file.

•   Perform builds for a variety of platforms with a single invocation.

•   Trivially set up periodic NetBSD rebuilds by adding a single line to your crontab(5).

•   Hooks to plug other components into the build procedure. For example: use rsync(1) to push the results of a successful build to a file server.

As you can see in the SYNOPSIS section, sysbuild 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.

The following options apply to all commands:

-c config_name
    Specifies the configuration file to use. The format of the file is described in sysbuild.conf(5).

    If config_name includes any directory separator (aka, one or more slashes) or the ‘.conf’ suffix, then this specifies the path of the configuration file to load.

    If config_name is a plain name without any directory components nor extension, then this specifies the name of the configuration. sysbuild will first look for a configuration file in ~/.sysbuild/<config_name>.conf and, if not found, will use /usr/pkg/etc/sysbuild/<config_name>.conf. Any of the two files must exist, or else sysbuild will exit with an error.

-o variable=value
    Applies an override to the loaded configuration.

    The variable part of the argument must be any of the recognized configuration variables described in sysbuild.conf(5). The value, if not empty, specifies the value to set the configuration variable to. If value is empty, then the configuration variable is unset.

  The build command
The build command provides the main functionality of sysbuild. It performs the following steps:

1.  If UPDATE_SOURCES is true, the fetch command is invoked first. See The fetch command for more details.

2.  For every machine type listed in MACHINES, issues a build.sh call for that particular machine using the rest of the settings defined in the configuration file. The targets passed to the build.sh script are those defined in the BUILD_TARGETS variable, or the arguments passed through the command line if any.

The following options apply only to the build command:

-f  Enables fast mode, which skips updating the source trees and performs update builds. This is a shorthand for these generic flags: -o INCREMENTAL_BUILD=true -o UPDATE_SOURCES=false.

  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 sysbuild. 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.

  The env command
The env command prints a shell script snippet that defines environment variables to simplify working with the directory layout of a NetBSD build for a particular machine. If the MACHINES variable is not defined, or if it lists more than one machine, then the machine argument is required.

The common mechanism to use these variables is by executing sysbuild in the following way:

    $ eval $(sysbuild env)

The following variables are defined and/or modified:

PATH
    The path to the tools is prepended to the path. Of particular interest is the nbmake-<machine> script made available in this way, which allows you to build arbitrary targets within the source directory using the tools.

D   Path to the destdir.

O   Path to the objects directory for the source tree.

S   Path to the source tree.

T   Path to the tools. Note that this points to the root of the tools, not their bin subdirectory.

XO  If XSRCDIR is defined, path to the objects directory for the X source tree.

XS  If XSRCDIR is defined, path to the X source tree.

And the following functions are defined:

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:

        $ cd /usr/src/bin/ls
        /usr/src/bin/ls$ nbmake-amd64
        /usr/src/bin/ls$ cd $(curobj)
        /usr/obj/usr/src/bin/ls$

  The fetch command
The fetch command downloads or updates the NetBSD source trees, which include src and, optionally, xsrc.

If the modules do not exist yet in the locations specified by SRCDIR and XSRCDIR, this performs an initial CVS checkout of the trees. If the modules exist, this performs a CVS update.

The CVSROOT and CVSTAG variables are used to determine where to get the sources from and whether a particular tag is desired.

The major use of this subcommand is the following. Consider that you wish to use the standard locations of /usr/src and /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 NetBSD builds as an unprivileged user. In this situation, you can use the ‘fetch’ command as root only, set UPDATE_SOURCES to ‘false’ in your user configuration files, and do your builds as another user.

FILES

/usr/pkg/etc/sysbuild/
    Directory containing all system-wide configuration files.

/usr/pkg/etc/sysbuild/default.conf
    Default configuration file to load if the user does not have a corresponding ~/.sysbuild/default.conf file and the -c flag is not provided.

~/.sysbuild/
    Directory containing all user-specific configuration files.

~/.sysbuild/default.conf
    Default configuration file to load when the -c flag is not provided.

SEE ALSO
cvs(1), sysbuild4cron(1), sysbuild.conf(5), hier(7), /usr/src/BUILDING

HISTORY
sysbuild 1.x existed in pkgsrc from November 28th, 2002 to June 1st, 2004. The package was removed from the tree because NetBSD's build.sh had improved enough to make the 1.x series of sysbuild unnecessary, and also because sysbuild 1.x did not work with NetBSD 2.0 and above.

sysbuild 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.

See /usr/pkg/share/doc/sysbuild/NEWS for more details on the changes across releases.

AUTHORS
The sysbuild utility was developed by Julio Merino <jmmv@google.com>.