.\" $NetBSD: pkg_comp.8,v 1.1.1.1 2002/09/07 00:08:50 rh Exp $ .\" .\" pkg_comp - Build packages inside a clean chroot environment .\" Copyright (c) 2002, Julio Merino .\" .\" 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 26, 2002 .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 dependancies and the correct behaviour of a package in a fresh system installation. .Pp The behavior of .Nm is controlled trought 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. .Pp .Ss What to use it for? You can use .Nm to achieve many goals when buildling packages. Here are some ideas: .Bl -bullet -item .It Build packages for other system versions. For example, build packages for .Nx 1.5 while you are running .Nx current . .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 .Pp .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 . .Pp .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 buildling 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 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 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 PTHREAD_TYPE The threading type to use when building packages. Defaults to .Ql pth . .It ROOTSHELL The shell of the root user. Defaults to .Pa /bin/sh . .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 empty, no X Window is configured inside the chroot jail and no other X variables take effect. Default to .Ql xbase.tgz xcomp.tgz xcontrib.tgz xfont.tgz xmisc.tgz xserver.tgz . .It USE_XF86_4 If set to .Ql yes , sets specified in SETS_X11 contain X Window version 4. Has no effect if X is unconfigured. Defaults to .Ql yes . .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 unconfiguerd. Defaults to .Ql yes . .El .Ss Mounted filesystems In order to avoid duplicating huge system trees, .Nm takes advantadge of filesystem layers. By default, it uses .Xr mount_null 8 , which duplicates a filesystem 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 filesystem 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 filesystems are mounted before entering the chroot and unmounted after exiting. In order to know if filesystems 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 filesystems, this status file may get out of sync. Be sure to check if NO filesystems 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 ro . .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 ro . .It REAL_PKGSRC The pkgsrc tree. This can be useful if you want to use several pkgsrc trees independantly. Defaults to .Pa /usr/pkgsrc . .It REAL_PKGSRC_OPTS Mount options. Defaults to .Sy -t null -o rw . .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 rw . .El .Pp .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. .It removepkgs Remove all the packages in the chroot environment. It starts deleting packages with .Xr pkg_delete 1 and then cleans the package tree and the database. This will rebuild .Sy MAKE_PACKAGES , reinstall .Sy INSTALL_PACKAGES and xpkgwedge if they are specified in the configuration file. .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 dependancies automatically. For this to be useful, you need to set .Sy REAL_PACKAGES and use .Sy MAKE_PACKAGES or pass package names trought the command line. .El .Pp .Sh NOTES This program uses nullfs to create virtual copies of real trees inside the chroot environment. .Pp .Sh AUTHORS Julio Merino .Sh SEE ALSO .Xr pkg_delete 1 , .Xr packages 7 , .Xr mount_null 8 . .Sh BUGS Probably many, specially error checking.