path: root/pkgtools/pkg_comp/files/pkg_comp.8

.\" $NetBSD: pkg_comp.8,v 1.9 2003/07/20 15:54:47 jmmv Exp $
.\"
.\" pkg_comp - Build packages inside a clean chroot environment
.\" Copyright (c) 2002, 2003, 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 July 20, 2003
.Dt PKG_COMP 8
.Os
.Sh NAME
.Nm pkg_comp
.Nd build packages inside a chroot
.Sh SYNOPSIS
.Nm
.Op Ar -c conf_file
.Ar target
.Op Ar pkg_name ...
.Sh DESCRIPTION
.Nm
is a tool that makes easy the compilation of packages inside a clean
chroot environment.
This allows an easy tracking of exact dependencies
and the correct behavior of a package in a fresh system installation.
.Pp
The behavior of
.Nm
is controlled through a small configuration file and a target (keep
reading to learn more).
The configuration file tells
.Nm
how to configure the new chroot environment, and the target specifies
which action to take.
.Ss What to use it for?
You can use
.Nm
to achieve many goals when building packages.
Here are some ideas:
.Bl -bullet
.It
Build packages for other system versions.
For example, build packages for
.Nx 1.5
while you are running
.Nx 1.6 .
.It
Build packages using different
.Pa mk.conf
options than your current system, like changing the threading library,
.Sy COPTS ,
placement of configuration files, etc.
.It
Debug the build process of a package, checking if buildlinks work
properly.
.It
Avoid autoconf's side effects by keeping a separate chroot for each
project, like one for GNOME2 and another one for KDE3.
.El
.Sh CONTROL DIRECTORY
.Nm
needs to store several information when it is running.
Instead of using normal system trees, it uses a special directory inside the
chroot to avoid polluting the system.
It stores there scripts, object files, built packages, etc.
This directory is located by default in
.Pa $DESTDIR/pkg_comp .
.Sh CONFIGURATION
With
.Nm
you can maintain several configuration files so you can work with
different chroot jails easily.
To make this easy, configuration files are stored inside
.Pa $HOME/pkg_comp ,
followed by the configuration file name and the .conf suffix.
The default configuration file is
.Pa $HOME/pkg_comp/default.conf ,
and is always used if you do not specify another one.
.Pp
Configuration files are simple shell scripts that define
variables.
The default values shown here are those written in the template when
issuing a maketemplate.
.Bl -tag -width indent
.It BUILD_TARGET
The target to use when building packages.
It can contain any target supported by the pkgsrc system, but
reasonable values are:
.Ql install
and
.Ql package .
Defaults to
.Ql package .
.It COPYROOTCFG
If set to
.Ql yes ,
all configuration files (not directories) that reside inside
.Pa /root
are copied to
.Sy $DESTDIR/root .
Defaults to
.Ql no .
.It DESTDIR
The chroot jail directory.
Defaults to
.Pa /var/chroot/pkg_comp/default .
.It DISTRIBDIR
This is the directory which holds
.Nb
binary sets and X sets.
Its structure is the same as official release
distributions, that is, tgz files must reside inside
.Pa $DISTRIBDIR/binary/sets .
Defaults to
.Pa /var/pub/NetBSD .
.It EXTRAMK
Specifies a file that must be appended to
.Pa $DESTDIR/etc/mk.conf .
This is useful to add special items to this configuration file.
Defaults to nothing.
.It INSTALL_PACKAGES
A list of packages to automatically install after the
.Sy makeroot
and after installing
.Sy MAKE_PACKAGES .
Each name must be the full package name, including the tgz suffix.
Packages are searched inside
.Pa $REAL_PACKAGES/All .
Defaults to nothing.
.It LOCALBASE
Where binary packages get installed.
Defaults to
.Pa /usr/pkg .
.It MAKE_PACKAGES
A list of packages to automatically build after the
.Sy makeroot
target.
A package is in the form section/name, like misc/colorls.
Defaults to nothing.
.It MKCONF_VARS
A list of variable names that will be appended to the generated
.Pa /etc/mk.conf
file, together with their values set in the configuration file.
Its default value contains all variables listed here.
.It NETBSD_RELEASE
Specifies which version number of
.Nx
is installed inside the chroot.
If set to
.Ql no ,
no special action is taken (this is useful if the system version inside
the chroot matches the outside one).
Otherwise, the
.Pa pkgtools/libkver
package is installed, configuring it with the version set in the variable.
This package fakes calls to the
.Xr sysctl 8
utility so that programs get the right kernel version with respect to the
installed userland (inside the chroot).
Note that
.Va REAL_SRC
has to point to a directory holding system sources
matching the selected version.
Defaults to
.Ql no .
.It PKG_SYSCONFBASE
Base directory of configuration files.
Defaults to
.Pa /usr/pkg/etc .
.It PKGVULNDIR
Directory where the
.Pa vulnerabilities
file will be installed (inside the chroot).
Defaults to
.Pa /usr/pkg/share .
.It REAL_PKGVULNDIR
Directory where the system-wide
.Pa vulnerabilities
file resides (outside the chroot).
Defaults to
.Pa /usr/pkgsrc/distfiles .
.It ROOTSHELL
The shell of the root user.
Defaults to
.Pa /bin/ksh .
.It SETS
A list of binary sets to be extracted inside
.Sy DESTDIR .
Defaults to
.Ql base.tgz comp.tgz etc.tgz text.tgz .
.It SETS_X11
A list of binary sets of the X Window system.
This has the same behavior
as
.Sy SETS .
If this variable is set to
.Ql no ,
no X Window is configured inside the chroot
jail and no other X variables take effect.
Defaults to
.Ql xbase.tgz xcomp.tgz xcontrib.tgz xfont.tgz xmisc.tgz xserver.tgz .
.It USE_AUDIT_PACKAGES
If set to
.Ql yes ,
install the
.Pa security/audit-packages
package inside the chroot and let
.Nm
handle the
.Pa vulnerabilities
file automatically.
This means that it will install the system-wide
.Pa vulnerabilities
file inside the chroot when needed, keeping both in sync.
Defaults to
.Ql yes .
.It USE_GCC3
If set to
.Ql yes ,
the GNU C Compiler version 3 will be installed inside the chroot
environment and used to build all packages, using the
.Pa lang/gcc3
package.
Defaults to
.Ql no .
.It USE_XPKGWEDGE
If set to
.Ql yes ,
you want xpkgwedge to be compiled and installed automatically inside the
chroot.
This takes care of setting up
.Pa /etc/profile
and
.Pa /etc/csh.login
for xpkgwedge to work.
Has no effect if X is unconfigured.
Defaults to
.Ql yes .
.El
.Ss Mounted file systems
In order to avoid duplicating huge system trees,
.Nm
takes advantage of file system layers.
By default, it uses
.Xr mount_null 8 ,
which duplicates a file system tree into another directory; although
you may want to use
.Xr mount_union 8 ,
or even
.Xr mount_overlay 8 .
If the
content of these variables is empty, that file system is not mounted.
.Pp
You can control which layer to use and which options you want with
special configuration options, as explained below.
.Pp
These file systems are mounted before entering the chroot and unmounted
after exiting.
In order to know if file systems are mounted or not, the
program uses a temporary file, called
.Pa $DESTDIR/pkg_comp/tmp/mount.stat ,
which controls the number of
.Nm
processes using the chroot environment.
If some of them crashes unexpectedly and you notice it does not try
to unmount the file systems, this status file may get out of sync.
Be sure to check that NO file systems are mounted when issuing a
.Sy removeroot .
.Bl -tag -width indent
.It REAL_DISTFILES
Specifies where distfiles reside in the real system.
Defaults to
.Pa /usr/pkgsrc/distfiles .
.It REAL_DISTFILES_OPTS
Mount options.
Defaults to
.Sy -t null -o rw .
.It REAL_PACKAGES
Specifies where to build binary packages.
This variable is specially useful.
Defaults to
.Pa /usr/pkgsrc/packages .
.It REAL_PACKAGES_OPTS
Mount options.
Defaults to
.Sy -t null -o rw .
.It REAL_PKGSRC
The pkgsrc tree.
This can be useful if you want to use several pkgsrc trees independently.
Defaults to
.Pa /usr/pkgsrc .
.It REAL_PKGSRC_OPTS
Mount options.
Defaults to
.Sy -t null -o ro .
.It REAL_SRC
The src system tree.
Usually useless, but may be needed by some packages, like sysutils/aperture.
Defaults to
.Pa /usr/src .
.It REAL_SRC_OPTS
Mount options.
Defaults to
.Sy -t null -o ro .
.El
.Sh TARGETS
A target specifies what
.Nm
should do (as in make).
The following list describes all supported targets,
in the logical order you should call them.
.Bl -tag -width indent
.It maketemplate
Create a sample
.Ar conf_file .
You should edit it after the creation as you will probably want to change
the default configuration, specially paths.
.It makeroot
Create the chroot environment, based on the specs of the configuration file.
This step is required before trying any other, except maketemplate .
.It build
Builds the specified packages inside the chroot.
You need to pass their names as relative paths inside pkgsrc, like
.Pa pkgtools/pkg_comp .
.It install
Install the specified binary packages into the chroot.
You must specify the full name of the package and they must be reside inside
.Sy REAL_PACKAGES .
.It chroot
Enters the chroot environment.
If no arguments are given,
.Va ROOTSHELL
is executed, otherwise whatever you typed.
.It removeroot
Remove the entire chroot tree.
You should do it with this target because it
will take care to umount needed mount points.
.It auto
This executes several targets automatically, setting
.Sy BUILD_TARGET
to package.
The order is: makeroot, build and removeroot.
This is useful to create binary packages of several pkgsrc and their
dependencies automatically.
For this to be useful, you need to set
.Sy REAL_PACKAGES
and use
.Sy MAKE_PACKAGES
or pass package names through the command line.
.El
.Sh NOTES
This program uses nullfs to create virtual copies of real trees inside the
chroot environment.
.Pp
You need to install the
.Pa security/audit-packages
package in the host system if you want security checks to work inside the
chroot environment.
.Sh SEE ALSO
.Xr pkg_delete 1 ,
.Xr packages 7 ,
.Xr mount_null 8 ,
.Xr sysctl 8
.Sh AUTHORS
.An Julio Merino Aq jmmv@netbsd.org