Kevin Daughtridge

Boxenator tutorial

This tutorial will demonstrate and explain the uses of Boxenator, a scriptable generator of configuration files for Gentoo's Portage package manager. It is based on version 1.0.0 of Boxenator.

Contents

Introduction

Boxenator and this tutorial assume that you have working knowledge of Portage and its configuration. Part 2 (chapters 1, 2, and 3) and Part 3 of the Gentoo Handbook provide thorough coverage, but the existing configuration files should not be overwritten by Boxenator unless you are certain that the script output is properly recreating them.

Advanced knowledge of Python is not required to use Boxenator, but the Python Tutorial (up to and including Data Structures) is recommended.

Before you begin, download and install Boxenator.

Creating a basic Boxenator script

This section will demonstrate the Boxenator methods for the basic Portage configuration described in Installing Gentoo (Part 1 of the Gentoo Handbook). Sample values will be provided for demonstration. We begin with an empty text file. It will be referred to as sample.box throughout the tutorial.

When a Boxenator script is executed, a global variable called box has been defined. box is an instance of boxenator.Context, and all specifications are made through its attributes and methods. The boxenator.Context reference provides a full list of these.

To set a global Portage variable as would appear in /etc/make.conf, use box.set_env (envvar, value), where envvar is the name of the variable to be set (e.g. CHOST or MAKEOPTS), and value is the value its value. value will appear in double quotes ("") in the output, so any shell variable (${VAR}) or command ($(command)) substitutions will be evaluated.

Some global variables have special support methods. To add Gentoo download mirrors to GENTOO_MIRRORS, use box.add_mirror with mirror URIs as arguments. To add C or C++ compiler flags to CFLAGS or CXXFLAGS, use box.add_cflag or box.add_cxxflag with flags as arguments. Other variables, such as USE and LINGUAS, will be discussed later.

These global variables, as discussed in the Handbook, are added to our configuration:

box.set_env ("CHOST", "i686-pc-linux-gnu")
box.add_cflag ("-O2", "-pipe", "-march=prescott")
box.add_cxxflag ("${CFLAGS}")
box.set_env ("MAKEOPTS", "-j2")
box.add_mirror ("http://gentoo.osuosl.org/", "http://gentoo.llarian.net/")

The system architecture is defined by the chosen Portage profile. Boxenator does not currently output the /etc/make.profile symbolic link, but the architecture name is used for other purposes. Set it with box.set_arch:

box.set_arch ("x86")

The enabling and disabling of USE flags control much of a Portage configuration. This is accomplished with box.enable_use and box.disable_use, with USE flags as arguments. Our sample configuration will use GNOME instead of KDE:

box.enable_use ("gnome", "gtk")
box.disable_use ("qt3", "qt4", "kde")

Finally, to add packages to the world set, use box.add_package with DEPEND atoms as arguments. A DEPEND atom is a name for a package or package version, as would appear in arguments to emerge. See the ebuild(5) man page for a full definition. The category named argument prepends a category name to each DEPEND atom. Other named arguments will be discussed later. Our sample configuration will include these packages:

box.add_package ("sys-kernel/gentoo-sources", "sys-boot/grub")
box.add_package ("app-admin/metalog", "sys-process/fcron", "sys-apps/slocate")
box.add_package ("reiserfsprogs", "sysfsutils", category="sys-fs")

Running and installing the configuration

Now that our sample.box script contains a basic configuration, we can run Boxenator to see the resulting output. If run without any other options, Boxenator will output the target files on standard output. We can add --verbose to see details about progress. (For a full explanation of Boxenator invocation, see command line options.)

boxenator -v sample.box

will produce:

boxenator: Including spec file "sample.box" ...
boxenator: Outputting target "virtuals" ...
boxenator: Outputting target "package.use.mask" ...
boxenator: Outputting target "package.use" ...
boxenator: Outputting target "mirrors" ...
boxenator: Outputting target "package.unmask" ...
boxenator: Outputting target "package.mask" ...
boxenator: Outputting target "package.provided" ...
boxenator: Outputting target "use.force" ...
boxenator: Outputting target "package.keywords" ...
boxenator: Outputting target "package.env" ...
boxenator: Outputting target "package.licenses" ...
boxenator: Outputting target "make.conf" ...
# This file was generated by boxenator.
# Changes will be overwritten if it is run again.
CFLAGS="-O2 -pipe -march=prescott"
CHOST="i686-pc-linux-gnu"
CXXFLAGS="${CFLAGS}"
GENTOO_MIRRORS="http://gentoo.osuosl.org/ http://gentoo.llarian.net/"
MAKEOPTS="-j2"
USE="gnome gtk -qt3 -qt4 -kde"
boxenator: Outputting target "use.mask" ...
boxenator: Outputting target "world" ...
app-admin/metalog
sys-apps/slocate
sys-boot/grub
sys-fs/reiserfsprogs
sys-fs/sysfsutils
sys-kernel/gentoo-sources
sys-process/fcron
boxenator: Outputting target "package.use.force" ...
boxenator: Outputting target "packages" ...
boxenator: Outputting target "package.patch" ...
boxenator: Outputting target "categories" ...

With the output checked, we can rerun Boxenator to produce output files. With the --shallow option, each target file will be output in the current or specified directory. With the --files option, the files will be output in a tree of directories, rooted at the current or specified directory, that matches the Portage configuration layout. The --destination option takes the name of a directory in which the files will be output.

Combining --files and --destination, we install the Portage configuration to our new chrooted Gentoo box: (This command, run with root privileges, would overwrite existing Portage configuration files on your system. Replace the / destination with a test directory for demonstration purposes.)

boxenator -v -F -d/ sample.box

Boxenator checks specified DEPEND atoms, USE flags, and other input for validity. If invalid input is encountered, the program prints an error message and aborts. The --force option may be specified to print a warning and continue anyway.

Maintaining a Boxenator-configured system

General maintenance of a Gentoo system via Portage includes three major actions: installing new packages as needed, updating packages to new versions, and removing unneeded packages.

Installing new packages usually involves a call to emerge and, if --oneshot is not specified, adds the packages to the world set. Because Boxenator overwrites the world set, packages which have been added to it must be installed separately. This can be done automatically with the --world option to Boxenator.

With --world, each uninstalled package in the world set is installed to the system. Root access is required for this option. If --world is specified along with other options, this will be done after configuration files have been output. If --force has been specified, Boxenator will continue attempting to install each package even after a failure has occurred in emerge.

Our sample configuration has seven new packages in world, so we should install them:

boxenator -w

After the installation is complete, we are ready to configure our kernel, boot loader, and whatnot (not shown). (Note that a less-than-stage3 installation would require an emerge system before the world packages were installed.) In the future, we can install new packages at the same time we install the configuration files:

boxenator -vwF -d/ sample.box

Updating packages is largely the same as for a typical Portage setup. The --newuse option to emerge is recommended to catch configuration changes, and --pretending or --asking first is always a good idea:

emerge --update --deep --newuse --ask world
emerge -uDNa world

Removing unneeded packages is a delicate task in a source-based distribution like Gentoo. If you have maintained an accurate world package set and USE flags, you should receive an accurate list from:

emerge --depclean --pretend

Note that --pretend is strongly recommended, as this package list may contain errors even in a comprehensive configuration. After you have reviewed this list, the actually unneeded packages may be removed with emerge --unmerge. See the Portage documentation for more information on --depclean's pitfalls and how to recover from them.

The eclean-dist utility is recommended to keep your distfiles directory in check. It is part of the highly useful gentoolkit package.

Notes