path: root/sysutils/sysbuild/files/sysbuild.8

.\" $NetBSD: sysbuild.8,v 1.4 2002/12/08 11:37:18 jmmv Exp $
.\"
.\" sysbuild - Automatic NetBSD system builds
.\" Copyright (c) 2002, Julio Merino <jmmv@netbsd.org>
.\"
.\" 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. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\" 3. Neither the name of author 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 16, 2002
.Dt SYSBUILD 8
.Os
.Sh NAME
.Nm sysbuild
.Nd Automates
.Nx
release and kernel builds
.Sh SYNOPSIS
.Nm
.Op Fl fms
.Op Fl c Ar conf
.Ar target
.Op Ar target_args ...
.Sh DESCRIPTION
The
.Nm
utility automates the building process of a
.Nx
release and all related stuff (like kernels), everything working as an
unprivileged, special user.
It should be clear enough that this program does not add any kind of
magic to the existing build mechanisms of the
.Nx
operating system; it just makes things easier if you want to automate
them (for example, to run them from a
.Xr cron 8
job).
.Pp
The following options are recognized:
.Bl -tag -width indent
.It Fl c Ar conf
Specify the name of the configuration file.
This is not a full name; it is just a symbolic name.
See
.Sx CONFIGURATION
for for information.
.It Fl f
Run in fast mode.
This option passes the
.Fl u
flag to the build.sh script; this way build directories are not
cleaned during builds.
While building kernels, it avoids the config, clean and depend
steps.
.It Fl m
Capture all output and send it by mail to the
.Va MAILTO
user specified in the configuration file.
.It Fl s
Automatically change privileges using
.Xr su 1 .
By default the program will
exit if user credentials for the specified target are incorrect.
.El
.Sh EXIT STATUS
Returns 0 on success, 1 if any error happened.
.Sh TARGETS
.Nm
behavior is controlled through a target.
A target specifies what the program should do when executed.
The following targets are recognized:
.Bl -tag -width ident
.It build-kernels
Automatically build all kernels listed in the
.Va KERNCONF
variable.
.Pp
Each kernel name listed in this variable is configured, cleaned,
depended and built inside its own directory, which is in turn placed in
.Pa $BUILDDIR/kernels .
Note that kernel configuration files must be stored inside the
directory pointed to by
.Va KERNCONFDIR .
.Pp
This target requires
.Ql @SYSBUILD_USER@
privileges.
.It build-release
Build a full release of the system.
A release is formed by all compressed system sets, installation floppy
disks and standard kernels.
.Pp
Release files are placed inside the directory pointed by
.Va RELEASEDIR .
During the build,
.Va BSDOBJDIR
is set to
.Pa $BUILDDIR/obj
and
.Va DESTDIR
is set to
.Pa $BUILDDIR/root .
.Pp
Depends on
.Ql clean .
.Pp
This target requires
.Ql @SYSBUILD_USER@
privileges.
.It build-sets
Build compressed system sets only.
If you want the sets to install them later on your own system, this is
the recommended target, as building a release takes much more time.
.Pp
Depends on
.Ql clean .
.Pp
This target requires
.Ql @SYSBUILD_USER@
privileges.
.It clean
Cleanup all work areas.
This will unconditionally clean all the stuff located under the
directory specified by
.Va BUILDDIR ,
but will not destroy the main directory hierarchy inside it.
.Pp
This target requires
.Ql @SYSBUILD_USER@
privileges.
.It clean-srcs Op Ar dir ...
Cleanup permissions of all source files inside the directories
specified by
.Va CVSDIRS ,
or the ones specified by the optional list
.Ar dir .
All files are set to
.Va CVSDIRS_OWNER
owner and
.Va CVSDIRS_GROUP
group.
Optional permissions can be provided through
.Va CVSDIRS_PERMS ,
which are set on all files using
.Xr chown 8 .
.Pp
This target requires
.Ql root
privileges.
.It config Op Ar conf
Edit the default configuration file or the one specified by
.Ar conf ,
if given (remember that these are symbolic names, not full paths).
This will run
.Xr vi 1
if no editor is specified by the
.Ev EDITOR
variable.
.Pp
If the specified configuration file does not exist, a sample one is
copied from
.Pa @EGDIR@/default.conf .
.Pp
This command is interactive, so output cannot be captured with
.Fl m .
.Pp
This target requires
.Ql root
privileges.
.It config-kernel Ar kernel
Edit a kernel configuration file interactively, located inside
.Pa @SYSBUILD_HOMEDIR@ .
If the configuration file is not found, the
.Pa GENERIC
kernel for your platform is copied as a template.
.Pp
This target requires
.Ql root
privileges.
.It destroy
Completely remove the work area specified by
.Va BUILDDIR .
You should run this target before deinstalling this program.
.Pp
This target requires
.Ql root
privileges.
.It etcupdate
Extract the compressed
.Pa etc.tgz
file, generated during the
.Ql build-sets
or the
.Ql build-release
stages, in a temporary place and then run
.Xr etcupdate 8
over it to update your
.Pa /etc
directory.
.Pp
This command is interactive, so output cannot be captured with
.Fl m .
.Pp
This target requires
.Ql root
privileges.
.It init
Initialize the work directory specified in
.Va BUILDDIR
plus all the subdirectories required inside it.
Should be run once, after configuring the program with the
.Ql config
target (or when creating new configuration files).
.Pp
This target requires
.Ql root
privileges.
.It install-kernel Op Ar kernel
Install the first kernel specified in the
.Va KERNCONF
variable or the one supplied by the
.Ar kernel
argument.
.Pp
This target requires
.Ql root
privileges.
.It install-sets
Install built system sets, placed inside
.Pa $RELEASEDIR/binary/sets .
Only sets specified in the
.Va SETS
variable are installed.
.Pp
This target requires
.Ql root
privileges.
.It update-srcs Op Ar dir ...
Use
.Xr cvs 1
to update all source trees specified by
.Va CVSDIRS ,
or the ones specified by the optional
.Ar dir
arguments.
.Pp
This target requires
.Ql @SYSBUILD_USER@
privileges.
.El
.Sh CONFIGURATION
.Nm
supports multiple configuration files.
This is specially useful if you usually need to build different
versions of
.Nx ,
that is, one configuration for each version.
.Pp
Configuration files are directly stored inside
.Pa @SYSBUILD_HOMEDIR@ ,
and have a
.Ql .conf
extension.
The symbolic name of the configuration file (the one used with the
.Ar -c
flag) is formed by the name of the configuration file, without the
path and without the extension.
For example, the default configuration file (used when no other one is
specified) is named
.Pa @SYSBUILD_HOMEDIR@/default.conf ,
but you could use
.Fl c Ar default
to select it.
You should not worry about where these files are stored, as the
.Ql config
target will take care of it.
.Pp
The sample configuration file (copied to all new configurations
created) is well documented and contains some reasonable
defaults.
Even though, a list of all known variables is provided here,
for reference:
.Bl -tag -width indent
.It BUILDDIR
The directory which holds all working stuff (object files, temporary
root, etc.).
You will need lots of space in this directory if you want
to build full releases.
.It CVSDIRS
White-space separated list of directories that are updated using
.Xr cvs 1
when executing the
.Ql update-srcs
target.
.It KEEP_TOOLS
If set to
.Ql yes ,
do not remove tools while running the
.Ql clean
target.
Therefore, the easiest way to really remove them will be with the
.Ql destroy
target.
.It KERNCONF
White-space separated list of kernels that are built with the
.Ql build-kernels
target.
The first one is the kernel that will be installed when running
.Ql install-kernel .
.It KERNCONFDIR
Directory which holds kernel configuration files.
Defaults to
.Pa @SYSBUILD_HOMEDIR@ .
.It RELEASEDIR
Base directory which will hold release files.
.It MAILTO
User who will receive all logs by mail when using the
.Fl m
flag.
.It MAIL_CMDLOG
If set to
.Ql yes ,
mail the entire log of commands to the user specified in
.Va MAILTO
(if using the
.Fl m
flag).
If set to
.Ql no ,
logs are left in
.Pa /tmp .
A summary of the process is always sent, regardless of this variable.
Remember that logs can become very big!
.It SETS
White-space separated list of compressed sets that should be
extracted in the machine while running
.Ql install-sets .
.It SRCDIR
Path to
.Nx
source directory tree, usually
.Pa /usr/src .
.El
.Sh SEE ALSO
.Xr crontab 1 ,
.Xr cvs 1 ,
.Xr mk.conf 5 ,
.Xr cron 8 ,
.Xr etcupdate 8 ,
.Pa /usr/src/BUILDING
.Sh CRON JOBS
.Xr cron 8
is our best friend to schedule these CPU tasks.
You can, for example, set a task to build a release while you are
sleeping, another to install it and when you get up you just have to
run the interactive
.Ql etcupdate
target to finish the process.
.Pp
To make this even easier, the
.Ql @SYSBUILD_USER@
comes with a sample crontab file, with several (disabled) entries,
ready to be edited.
You should note that the
.Fl m
flag is a good choice for unattended tasks, because you will get a
report by mail when they finish.
.Pp
To edit it, simply type:
.Pp
.Dl crontab -e -u @SYSBUILD_USER@
.Sh EXAMPLES
To initialize
.Nm
for the first time:
.Pp
.Dl sysbuild config
.Dl sysbuild init
.Pp
Once you have configured it properly, you can execute the following, as
.Ql root ,
to build your kernels and system sets.
Note that the
.Fl s
flag will automatically downgrade privileges.
.Pp
.Dl sysbuild -s build-kernels
.Dl sysbuild -s build-sets
.Pp
And then, as
.Ql root ,
you can install the results:
.Pp
.Dl sysbuild install-kernel
.Dl sysbuild install-sets
.Pp
Or, if you want to update all your source trees:
.Pp
.Dl sysbuild clean-srcs
.Dl sysbuild -s update-srcs
.Pp
The first command should be only required once, the first time you
want to do this task.
.Pp
Note that where we are using the
.Fl s
you could as well become the
.Ql @SYSBUILD_USER@
user using
.Xr su 1
and execute the command from there.
Read
.Sx SECURITY CONSIDERATIONS
for more details on this.
.Sh SECURITY CONSIDERATIONS
The unprivileged user
.Ql @SYSBUILD_USER@
account is disabled by default.
This means that root can access it through
.Xr su 1 ,
but no other user will be able to run
.Nm
properly.
If you want anybody to be able to use it, just set a password for the
account, give it to the user, and tell him to use the
.Fl s
flag.
.Sh NOTES
This program will only work in
.Nx 1.6
and above.
Some targets may work in previous versions, but do not expect it to
work fine.
.Pp
If you are changing some of the default directories in your
.Pa /etc/mk.conf ,
be sure to use the
.Ql ?=
operator instead of
.Ql =
so
.Nm
can override their value.
.Sh AUTHORS
.An Julio Merino Aq jmmv@netbsd.org
.Sh TO DO
There are many other things to do, but are left for future releases.
Here is a small list with some ideas:
.Bl -bullet -width indent
.It
Add support for X11R6 unprivileged builds.
This will require the use of
.Xr mount_union 8
because X11R6 build system creates object files together with sources.
.It
Support building for multiple architectures.
.El