POUDRIERE(8) BSD System Manager's Manual POUDRIERE(8)NAME
poudriere — bulk package builder and port tester
SYNOPSIS
poudriere command subcommand [options]
DESCRIPTION
The poudriere tool is used to build packages from the ports tree. It can
also be used to test a single port.
GLOBAL OPTIONS
poudriere accepts a global option:
-e etcdir Path to the directory where poudriere will find its configu‐
ration data. See FILES and ENVIRONMENT for more informa‐
tion.
-N Disable color support.
COMMANDS
The first argument to poudriere must be a command from the following
list:
bulk This command makes a ready-to-export package tree, and fills
it with binary packages built from a given list of ports.
During the build, hit ^T to send SIGINFO and get stats and
progress back.
jail This command allows you to manage the jails used by
poudriere which are building environments differing by OS
version and architecture.
combo This command works on jail-port build combinations. The
options are kept out of bulk to avoid damage by a command to
a running bulk build.
ports This command allows you to manage different portstrees which
will be used by poudriere (create, update and delete port‐
strees).
testport This command, mainly targeted at ports developers, launches
a test on a given port (useful before submitting/committing
a port).
options This command allows to configure the options for a given
port
distclean This command will cleanup old distfiles
pkgclean This command will cleanup old and unwanted packages
queue This command allows a non-root user to queue poudriere com‐
mands.
status This command shows status of current and previous builds
version Show version of poudriere.
SUBCOMMANDS
Here are the list of subcommands and associated options supported by
poudriere, sorted by command order.
bulk
These subcommands are mutually exclusive.
-a Build all ports in the tree.
-f file Absolute path to a file which contains the list of ports to
build. Ports must be specified in the form category/port
and shell-style comments are allowed. Multiple -f file
arguments may be specified at once.
cat/port cat/port2 ...
A list of ports can be specified directly.
See CUSTOMISATION to know how to build binary packages with options that
differs from defaults.
Here are the options associated with the bulk command.
-1 Override poudriere.conf to DISABLE_MAKE_JOBS on all ports.
-B name Specify which buildname to use. By default
YYYY-MM-DD_HH:MM:SS will be used. This can be used to
resume a previous build and use the same log and URL paths.
Resuming a build will not retry built/failed/skipped/ignored
packages.
-c Clean all previously built packages and logs.
-C Clean only the packages specified on the command line or in
in the file given in -f file
-F Only fetch from original MASTER_SITES. Skip FreeBSD mir‐
rors.
-j name Run the bulk build on the jail named name.
-J number[:number]
This argument specifies how many number jobs will run in
parallel for a bulk build. The optional second number is
the number of jobs used for the steps before the build, they
are more IO bound than CPU bound, so you may want to use a
different number.
-n Dry run. Show what woud be done, but do not actually build
or delete any packages.
-N Build package repository when build is completed.
-p tree This flag specifies on which ports tree the bulk build will
be done.
-R Clean RESTRICTED packages after building.
-s Skip incremental rebuild and sanity checks. Sanity tests
are made to check if the ports exists, does not have an
increased version number, packaged dependencies match, pkg‐
name matches, if the compiled options match the current
options from the make.conf files and
/usr/local/etc/poudriere.d/options, and that its own depen‐
dencies did not require rebuild as well.
-S Don't recrusively rebuild packages affected by other pack‐
ages requiring incremental rebuild. This is a subset of -s.
This may result in broken packages if the ones they depend
on are updated and are not ABI-compatible.
-t Add some testing to the specified ports. Add -r to recur‐
sively test all port dependencies as well. Currently unin‐
stalls the port, and disable parallel jobs for make. When
used with -a then -rk are implied.
-r Recursively test all dependencies as well. This flag is
automatically set when using -at.
-k When using -t do not consider failures as fatal. Do not
skip dependent ports on findings. This flag is automati‐
cally set when using -at.
-T Try building BROKEN ports by defining TRYBROKEN for the
build.
-w Save WRKDIR on build failure. The WRKDIR will be tarred up
into ${POUDRIERE_DATA}/wrkdirs.
-v This will show more information during the build. Specify
twice to enable debug output.
-z set This specifies which SET to use for the build. See
CUSTOMISATION for examples of how this is used.
jail
These subcommands are mutually exclusive.
-c Creates a jail.
-d Deletes a jail.
-i Show information about a jail. See also status.
-l List all available jails.
-n When combined with -l, only display jail name.
-s Starts a jail (chroot).
-u Update a jail using full buildworld.
Except for -l, all of the subcommands require the -j option (see below).
Here are the options associated with the jail command.
-J number This argument specifies how many number jobs will run in
parallel for buildworld.
-q Remove the header when -l is the specified mandatory option.
Otherwise, it has no effect.
-Q When used with -u, it rebuilds the jail faster with quick‐
world instead of buildworld.
-j name Specifies the name of the jail.
-v version Specifies which version of DragonFly to use in the jail,
e.g. 3.6, 3.8, or master
-M mountpoint
Gives an alternative mountpoint when creating jail.
-p name This specifies which port tree to start/stop the jail with.
-P patch Apply the specified patch to the source tree before building
the jail.
-t version instead of upgrading to the latest security fix of the jail
version, you can jump to the new specified version.
-z set This specifies which SET to start/stop the jail with.
combo
These subcommands are mutually exclusive.
-C Attempts to remove all poudriere mounts. It is normally
used to clean up leftover mounts after aborting a run with
control-c.
-L days Delete all <jail-portstree> logs older than the specified
number of days.
-d Run a dependency check of all ports in a given ports tree.
-i Show information about the jail.
-x List all failed ports in last or ongoing build.
Here are the options associated with the combo command.
-j name If given, reference bulk build using the jail name name
-p tree This required flag specifies on which ports tree is used for
the reference bulk build.
ports
These subcommands are mutually exclusive.
-c Creates a ports tree.
-d Deletes a ports tree.
-u Updates a ports tree.
-l List all available ports trees.
Except for -l, all of the subcommands require the -p switch (see below).
Here are the options associated with the ports command.
-q Remove the header when -l is the specified subcommand. Oth‐
erwise, it has no effect.
-p name Specifies the name of the ports tree to use.
-n When combined with -l, only display ports tree name.
-M mountpoint
Gives an alternative mountpoint when creating ports tree.
-m method Specifies which method to use to create the ports tree.
Could be git or rsync (Default: git)
-k When used with -d, only unregister the ports tree with out
removing the files.
testport
The specified port will be tested for build and packaging problems. All
missing dependencies will first be built in parallel. TRYBROKEN=yes is
automatically defined in the environment to test ports marked as BROKEN.
There is only 1 subcommand for the testport command.
-o origin Specifies an origin in the ports tree
Here are the options associated with the testport command.
-c Run make config for the given port.
-i Interactive mode. Enter jail for interactive testing and
automatically cleanup when done. A local pkg.conf(5) repos‐
itory configuration will be installed to
LOCALBASE/etc/pkg/repos/local.conf so that pkg(8) can be
used with any existing packages built for the jail. The
default repository will be disabled by default.
-I Advanced Interactive mode. Leaves jail running with port
installed after test. When done with the jail you will need
to manually shut it down:
poudriere jail -k -j JAILNAME.
As with -i this will install a pkg.conf(5) file for pkg(8)
usage.
-j name Runs only inside the jail named name.
-J number This argument specifies how many number jobs will run in
parallel for building the dependencies.
-k Do not consider failures as fatal. Find all failures.
-P Use custom prefix.
-N Do not build package repository or INDEX when build of
dependencies is completed.
-p tree Specifies which ports tree to use.
-s Skip incremental rebuild and sanity checks. Sanity tests
are made to check if the ports exists, does not have an
increased version number, packaged dependencies match, pkg‐
name matches, if the compiled options match the current
options from the make.conf files and
/usr/local/etc/poudriere.d/options, and that its own depen‐
dencies did not require rebuild as well.
-S Don't recrusively rebuild packages affected by other pack‐
ages requiring incremental rebuild. This is a subset of -s.
This may result in broken packages if the ones they depend
on are updated and are not ABI-compatible.
-v This will show more information during the build. Specify
twice to enable debug output.
-w Save WRKDIR on build failure. The WRKDIR will be tarred up
into ${POUDRIERE_DATA}/wrkdirs.
-z set This specifies which SET to use for the build. See
CUSTOMISATION for examples of how this is used.
distclean
This command accepts the following options:
-J number This argument specifies how many number jobs will run in
parallel for gathering distfile information.
-n Dry run, do not actually delete anything.
-p tree Specifies which ports tree to use. This can be specified
multiple times to consider multiple tress.
-y Assume yes, do not confirm and just delete the files.
-v This will show more information during the build. Specify
twice to enable debug output.
pkgclean
This command is used to delete all packages not specified to build.
These subcommands are mutually exclusive.
-a Keep all ports in the tree.
-f file Absolute path to a file which contains the list of ports to
keep. Ports must be specified in the form category/port and
shell-style comments are allowed. Multiple -f file argu‐
ments may be specified at once.
cat/port cat/port2 ...
A list of ports can be specified directly.
Here are the options associated with the pkgclean command. This command
accepts the following options:
-j name Jail to use for the packages to inspect.
-J number This argument specifies how many number jobs will run in
parallel for gathering package information.
-n Dry run, do not actually delete anything.
-N Do not build package repository or INDEX when done cleaning.
-p tree Specifies which ports tree to use.
-R Also clean restricted packages.
-y Assume yes, do not confirm and just delete the files.
-v This will show more information during the build. Specify
twice to enable debug output.
-z set SET to use for the packages to inspect.
options
This command accepts the following parameters:
-f file Absolute path to a file which contains the list of ports to
configure. Ports must be specified in the form
category/port and shell-style comments are allowed.
cat/port cat/port2 ...
A list of ports can be specified directly.
This command accepts the following options:
-c Use 'config' target, which will always show the dialog for
the given ports.
-C Use 'config-conditional' target, which will only bring up
the dialog on new options for the given ports. (This is the
default)
-j jailname If given, configure the options only for the given jail.
-p portstree
Run the configuration inside the given ports tree (by
default uses default)
-n Do not be recursive
-r Remove port options instead of configuring them
-s Show port options instead of configuring them
-z set This specifies which SET to use for the build. See
CUSTOMISATION for examples of how this is used.
The options subcommand can also take the list of ports to configure
through command line arguments instead of the using a file list.
queue
This command takes a poudriere command in argument.
There are no options associated with the queue command.
status
status sorts by SETNAME, PORTSTREE, JAILNAME and then BUILDNAME.
This command accepts the following options:
-a Show all builds, not just latest. This implies -f.
-b Show details about what each builder for the matched builds
are doing.
-B name Specifies which buildname to match on. This supports shell
globbing. Defaults to "latest". Specifying this implies
the -f flag.
-c Show a more compact output and do not include some columns.
-f Show finished builds, not just currently running. This is
implied by the -a, -B and -r flags.
-H Do not print headers and separate fields by a single tab
instead of arbitrary white space.
-j name Specifies the name of the jail to filter by.
-l Show logs instead of URL.
-p tree This flag specifies which ports tree to filter builds by.
-r Show build results. This implies the -f flag.
-z set This specifies which SET to filter builds by. Use 0 to
match on empty SET.
ENVIRONMENT
The poudriere command may use the following environment variable:
POUDRIERE_ETC If specified, the path to poudriere's config directory.
Defaults to /usr/local/etc.
FILES
POUDRIERE_ETC/poudriere.conf See self-documented
/usr/local/etc/poudriere.conf.sample
for example.
POUDRIERE_ETC/poudriere.d/poudriere.conf The configuration can be stored
in the poudriere.d directory as
well.
POUDRIERE_ETC/poudriere.d This directory contains various
configuration files for the
different jails.
EXIT STATUS
The poudriere utility exits 0 on success, and >0 if an error occurs.
EXAMPLES
bulk build of binary packages
This first example provides a guide on how to use poudriere for bulk
build packages.
[Prepare infrastructure]
First you have to create a jail, which will hold all the building infra‐
structure needs.
poudriere jail -c -v 3.8 -j 38D64
A jail will take approximately 1GB of space.
You also need to have at least one ports tree to build packages from it,
so let us take the default configuration by creating a ports tree.
poudriere ports -c
A ports tree will take approximately 250M of space.
[Specify a list of ports you want to build]
Create a flat text file in which you put the ports you want to see built
by poudriere.
echo 'sysutils/screen' > ~/pkglist
echo 'editors/vim' >> ~/pkglist
Any line starting with the hash sign will be treated as a comment.
[Launch the bulk build]
Now you can launch the bulk build. You can specify to build for only one
arch/version ; by default it will make the bulk build on all the jails
created by poudriere.
poudriere bulk -f ~/pkglist -j 38D64
[Find your packages]
Once the bulk build is over, you can meet your shiny new packages here:
/usr/local/poudriere_data/packages/38D64
with 38D64 as the name of the jail.
test a single port
This second example show how to use poudriere for a single port.
Let's take the example of building a single port;
poudriere testport -o category/port -j myjail
all the tests will be done in myjail.
It starts the jail, then mount the ports tree (nullfs), then mounts the
package dir (pourdriere_data/packages/<jailname>-<tree>-<setname>), then
it mounts the ~/ports-cvs/mybeautifulporttotest (nullfs) it builds all
the dependencies (except runtime ones) and log it to
poudriere_data/logs/testport/jailname/default/mybeautifulporttotest.log).
If packages for the dependencies already exists it will use them
When all the dependencies are built, packages for them are created so
that next time it will be faster.
All the dependency phase is done with PREFIX == LOCALBASE.
After that it will build the port itself with LOCALBASE != PREFIX and log
the build to poudriere_data/logs/testport/jailname/default/mybeautiful‐
porttotest.log
It will try to: install it, create a package from it, deinstall it, check
for cruft left behind and propose the line to add to pkg-plist if needed.
It is very easy to extend it so that we can easily add other tests if
wanted.
CUSTOMISATION
For bulk building, you can customize binary packages produced by
poudriere by changing build options port by port, and you can also spec‐
ify building directives in a make.conf file.
Custom build options
Before building a package, poudriere can mount a directory containing
option files if available. poudriere will check for any of these direc‐
tories in this order:
/usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-options
/usr/local/etc/poudriere.d/<jailname>-<setname>-options
/usr/local/etc/poudriere.d/<jailname>-<tree>-options
/usr/local/etc/poudriere.d/<setname>-options
/usr/local/etc/poudriere.d/<tree>-options
/usr/local/etc/poudriere.d/<jailname>-options
/usr/local/etc/poudriere.d/options
If a directory with this name exists, it is null-mounted into the
/var/db/ports/ directory of the jail, thus allowing to build package with
custom OPTIONS.
The options subcommand can be used to easily configure options in the
correct directory.
This directory has the usual layout for options: it contains one direc‐
tory per port (the name of the port) containing an 'options' file with
lines similar to:
WITH_FOO=true
WITHOUT_BAR=true
As a starter, you may want to copy an existing /var/db/ports/ to
/usr/local/etc/poudriere.d/options.
Blacklist ports
You can also specify a blacklist which will disallow the lists port ori‐
gins from building on the matched jail. Any of the following are allowed
and will all be used in the order shown:
/usr/local/etc/poudriere.d/blacklist
/usr/local/etc/poudriere.d/<setname>-blacklist
/usr/local/etc/poudriere.d/<tree>-blacklist
/usr/local/etc/poudriere.d/<jailname>-blacklist
/usr/local/etc/poudriere.d/<jailname>-<tree>-blacklist
/usr/local/etc/poudriere.d/<jailname>-<setname>-blacklist
/usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-blacklist
Create optional poudriere.conf
You can also specify an optional poudriere.conf that is pulled in depend‐
ing on the build. Any of the following are allowed and will all be used
in the order shown:
/usr/local/etc/poudriere.d/poudriere.conf
/usr/local/etc/poudriere.d/<setname>-poudriere.conf
/usr/local/etc/poudriere.d/<tree>-poudriere.conf
/usr/local/etc/poudriere.d/<jailname>-poudriere.conf
/usr/local/etc/poudriere.d/<jailname>-<tree>-poudriere.conf
/usr/local/etc/poudriere.d/<jailname>-<setname>-poudriere.conf
/usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-poudriere.conf
Create optional make.conf
You can also specify a global make.conf which will be used for all the
jails. Any of the following are allowed and will all be used in the
order shown:
/usr/local/etc/poudriere.d/make.conf
/usr/local/etc/poudriere.d/<setname>-make.conf
/usr/local/etc/poudriere.d/<tree>-make.conf
/usr/local/etc/poudriere.d/<jailname>-make.conf
/usr/local/etc/poudriere.d/<jailname>-<tree>-make.conf
/usr/local/etc/poudriere.d/<jailname>-<setname>-make.conf
/usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-make.conf
Create optional src.conf
You can also specify a global src.conf which will be used for building
jails with the jail -c subcommand. Any of the following are allowed and
will all be used in the order shown:
/usr/local/etc/poudriere.d/src.conf
/usr/local/etc/poudriere.d/<jailname>-src.conf
COMPATIBILITY
The poudriere command must be used on a DragonFly 3.6 or later.
BUGS
In case of bugs, feel free to fill
http://fossil.etoilebsd.net/poudriere/reportlist
AUTHORS
Baptiste Daroussin ⟨bapt@FreeBSD.org⟩
Bryan Drewery ⟨bdrewery@FreeBSD.org⟩
John Marino ⟨marino@FreeBSD.org⟩
BSD October 1, 2014 BSD
