path: root/src/bin/poudriere.8

.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org>
.\" Copyright (c) 2012-2014 Bryan Drewery <bdrewery@FreeBSD.org>
.\" All rights reserved.
.\"
.\" 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. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD$
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd March 11, 2017
.Dt POUDRIERE 8
.Os
.Sh NAME
.Nm poudriere
.Nd bulk package builder and port tester
.Sh SYNOPSIS
.Nm
.Cm command
.Cm subcommand
.Op Ar options
.Sh DESCRIPTION
The
.Nm
tool is used to build packages from the ports tree.
It can also be used to test a single port.
.Sh GLOBAL OPTIONS
.Nm
accepts a global option:
.Bl -tag -width "-f conffile"
.It Fl e Ar etcdir
Path to the directory where poudriere will find its configuration data.
See 
.Sx FILES
and
.Sx ENVIRONMENT
for more information.
.It Fl N
Disable color support.
.It Fl v
This will show more information during the build.
Specify twice to enable debug output.
.El
.Sh COMMANDS
The first argument to
.Nm
must be a
.Cm command
from the following list:
.Bl -tag -width "-f conffile"
.It 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
.Dv SIGINFO
and get stats and progress back.
.It jail
This command allows you to manage the jails used by
.Nm
which are building environments differing by OS version and architecture.
.It ports
This command allows you to manage different portstrees which will be used
by
.Nm
(create, update and delete portstrees).
.It testport
This command, mainly targeted at ports developers, launches a
test on a given port (useful before submitting/committing a port).
.It options
This command allows to configure the options for a given port
.It distclean
This command will cleanup old distfiles
.It pkgclean
This command will cleanup old and unwanted packages
.It queue
This command allows a non-root user to queue
.Nm
commands.
It is currently
.Sy EXPERIMENTAL .
Using it requires starting
.Sy poudriered
via the provided rc script.
.It status
This command shows status of current and previous builds
.It version
Show version of poudriere.
.Nm.
.El
.Sh SUBCOMMANDS
Here are the list of subcommands and associated options supported by
.Nm ,
sorted by
.Cm command
order.
.Ss bulk
.Pp
These subcommands are mutually exclusive.
.Bl -tag -width "-f conffile"
.It Fl a
Build all ports in the tree.
.It Fl f Ar file
Absolute path to a file which contains the list of ports to build.
Ports must be specified in the form
.Ar category/port
and shell-style comments are allowed.
Multiple
.Fl f Ar file
arguments may be specified at once.
.It cat/port cat/port2 ...
A list of ports can be specified directly.
.El
.Pp
See
.Sx CUSTOMISATION
to know how to build binary packages with options that differs from
defaults.
.Pp
Here are the options associated with the
.Cm bulk
command.
.Bl -tag -width "-f conffile"
.It Fl B Ar name
Specify which buildname to use.
By default 
.Ar 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.
.It Fl c
Clean
.Em all
previously built packages and logs.
.It Fl C
Clean only the packages specified on the command line or in in the file given in
.Fl f Ar file
.
.It Fl F
Only fetch from original MASTER_SITES.
Skip FreeBSD mirrors.
.It Fl j Ar name
Run the bulk build on the jail named
.Ar name .
.It Fl J Ar number[:number]
This argument specifies how many
.Ar number
jobs will run in parallel for a bulk build.
The optional second
.Ar 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.
The default pre-build value is 1.25 times the value of the build value.
.It Fl i
Interactive mode.
Enter jail for interactive testing and automatically cleanup when done.
A local
.Xr pkg.conf 5
repository configuration will be installed to
.Pa LOCALBASE/etc/pkg/repos/local.conf
so that
.Xr pkg 8
can be used with any existing packages built for the jail.
The FreeBSD repository will be disabled by default.
.It Fl I
Advanced Interactive mode.
Leaves jail running with ports installed after test.
When done with the jail you will need to manually shut it down:
.Dl "poudriere jail -k -j JAILNAME" .
As with
.Fl i
this will install a
.Xr pkg.conf 5
file for
.Xr pkg 8
usage.
.It Fl n
Dry run. Show what would be done, but do not actually build or delete any
packages.
.It Fl N
Do not build package repository or INDEX when build is completed.
.It Fl p Ar tree
This flag specifies on which ports
.Ar tree
the bulk build will be done.
.It Fl R
Clean RESTRICTED packages after building.
.It Fl 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,
pkgname matches, if the compiled options match the current options from the
.Pa make.conf
files and
.Pa /usr/local/etc/poudriere.d/options ,
and that its own dependencies did not require rebuild as well.
.It Fl S
Don't recursively rebuild packages affected by other packages requiring
incremental rebuild.
This is a subset of
.Fl s .
This may result in broken packages if the ones they depend on are updated
and are not ABI-compatible.
.It Fl t
Add some testing to the specified ports.
Add
.Fl r
to recursively test all port dependencies as well.
Currently uninstalls the port, and disable parallel
jobs for make.
When used with
.Fl a
then
.Fl rk
are implied.
.It Fl r
Recursively test all dependencies as well.
This flag is automatically set when using
.Fl at .
.It Fl k
When using
.Fl t
do not consider failures as fatal.
Do not skip dependent ports on findings.
This flag is automatically set when using
.Fl at .
.It Fl T
Try building BROKEN ports by defining TRYBROKEN for the build.
.It Fl w
Save WRKDIR on build failure.
The WRKDIR will be tarred up into
.Sy ${POUDRIERE_DATA}/wrkdirs .
.It Fl v
This will show more information during the build.
Specify twice to enable debug output.
.It Fl z Ar set
This specifies which SET to use for the build.
See
.Sx CUSTOMISATION
for examples of how this is used.
.El
.Ss jail
.Pp
These subcommands are mutually exclusive.
.Bl -tag -width "-f conffile"
.It Fl c
Creates a jail.
.It Fl d
Deletes a jail.
.It Fl i
Show information about a jail.
See also
.Cm status .
.It Fl l
List all poudriere jails.
.It Fl n
When combined with
.Fl l ,
only display jail name.
.It Fl s
Starts a jail.
.It Fl k
Kills a jail (stops it).
.It Fl r Ar name
Rename a jail to
.Ar name .
.It Fl u
Update a jail.
.El
.Pp
Except for
.Fl l ,
all of the subcommands require the
.Fl j
option (see below).
.Pp
Here are the options associated with the
.Cm jail
command.
.Bl -tag -width "-f conffile"
.It Fl b
Build the source provided with the -m src=PATH option.
.It Fl J Ar number
The
.Ar number
of make jobs will run in parallel for buildworld.
Defaults to the number of CPUs reported by:  sysctl hw.ncpu.
.It Fl q
Remove the header when
.Fl l
is the specified mandatory option.
Otherwise, it has no effect.
.It Fl j Ar name
Specifies the
.Ar name
of the jail.
.It Fl v Ar version
Specifies which
.Ar version
of FreeBSD to use in the jail.
If you are using method ftp then the
.Ar version
should in the form of: 9.0-RELEASE.
If you are using method of svn then the
.Ar version
should be in the form of git or svn branches: stable/9 or head for CURRENT.
Other methods only use the value for display.
.It Fl a Ar architecture
Specifies which
.Ar architecture
of FreeBSD to use in the jail. (Default: same as host)
.It Fl m Ar method
Specifies which
.Ar method
to use to create the jail.
(default:
.Sy http )
.Pp
Pre-built distribution options:
.Bl -tag -width "ftp-archiveXX"
.It Sy allbsd
Use
.Lk www.allbsd.org.
.It Sy ftp Sy http
Fetch from configured
.Sy FREEBSD_HOST
variable from
.Pa poudriere.conf .
.It Sy ftp-archive
Fetch from
.Lk ftp-archive.freebsd.org.
.It Sy null
This option can be used to import an existing directory that already contains an installed system.
The path must be specified with
.Fl M Ar path .
It is expected that this directory be installed to with the following:
.Bd -literal -offset indent
/usr/src# make installworld DESTDIR=PATH DB_FROM_SRC=1
/usr/src# make distrib-dirs DESTDIR=PATH DB_FROM_SRC=1
/usr/src# make distribution DESTDIR=PATH DB_FROM_SRC=1
.Ed
.Pp
The path will be null-mounted during builds.
It will not be copied at the time of running
.Nm jail .
Deleting the jail will attempt to revert any files changed by poudriere.
.It Sy src=PATH
Install from the given src directory at
.Sy PATH .
This directory will not be built from.
It is expected that it is already built and maps to a corresponding
.Pa /usr/obj
directory.
.It Sy tar=PATH
Install from the tarball at the given
.Sy PATH .
Note that this method requires the tarball contains the
.Pa /usr/src
files as well if you plan to build any port containing modules.
.It Sy url=PATH
Fetch from given
.Sy PATH .
Any URL supported by
.Xr fetch 1
can be used.
For example:
.Dl "url=file:///mirror/10.0"
.El
.Pp
Build from source options:
.Bl -tag -width "ftp-archiveXX"
.It Sy git Sy git+http Sy git+https Sy git+ssh
Will use git, the -v flag to set the branch name and the
.Sy GIT_BASEURL
variable in
.Pa poudriere.conf .
.It Sy src=PATH
With the
.Fl b
flag, the src tree will be copied into the jail and built.
.It Sy svn Sy svn+file Sy svn+http Sy svn+https
Will use SVN and the
.Sy SVN_HOST
variable in
.Pa poudriere.conf .
.El
.It Fl f Ar filesystem
Specifies the
.Ar filesystem
name (${ZPOOL}/jails/filesystem).
.It Fl K Ar kernelname
Install the jail with a kernel.
If the
.Ar kernelname
is an empty string GENERIC will be used.
If installing from ftp then the default kernel will be installed what ever the
.Ar kernelname
value is.
.It Fl M Ar mountpoint
Gives an alternative
.Ar mountpoint
when creating jail.
.It Fl p Ar name
This specifies which port tree to start/stop the jail with.
.It Fl P Ar patch
Apply the specified
.Ar patch
to the source tree before building the jail.
.It Fl S Ar srcpath
Use the specified
.Ar srcpath
as the FreeBSD source tree mounted inside the jail.
.It Fl t Ar version
instead of upgrading to the latest security fix of the jail version, you can
jump to the new specified
.Ar version .
.It Fl z Ar set
This specifies which SET to start/stop the jail with.
.It Fl x
Build the native-xbuild target and copy this into the jail.
Used exclusively
for cross building a ports set, typically via qemu-user tools.
.El
.Ss ports
.Pp
These subcommands are mutually exclusive.
.Bl -tag -width "-f conffile"
.It Fl c
Creates a ports tree.
.It Fl d
Deletes a ports tree.
.It Fl l
List all available ports trees.
.It Fl u
Update a ports tree.
.El
.Pp
Except for
.Fl l ,
all of the subcommands require the
.Fl p
switch (see below).
.Pp
Here are the options associated with the
.Cm ports
command.
.Bl -tag -width "-f conffile"
.It Fl B Ar branch
Specifies which
.Ar branch
to checkout when using the
.Sy svn
or
.Sy git
methods.
(Default: head/master)
.It Fl F
When used with
.Fl c ,
only create the needed file systems (for ZFS) and directories, but do
not populate them.
.It Fl M Ar mountpoint
Path to the source of a ports tree.
.It Fl f Ar filesystem
The name of the
.Ar filesystem
to create for the ports tree.
If 'none' then do not create a filesystem.
Defaults to poudriere/ports/default.
.It Fl k
When used with
.Fl d ,
only unregister the ports tree without removing the files.
.It Fl m Ar method
When used with
.Fl c ,
specify which
.Ar method
to use to create the ports tree.
Could be portsnap, git, none, svn{,+http,+https,+file,+ssh}.
The default is portsnap.
.It Fl n
When combined with
.Fl l ,
only display the name of the ports tree.
.It Fl p Ar name
Specifies the
.Ar name
of the ports tree to use.
.It Fl q
When used with
.Fl l ,
remove the header in the list view.
.It Fl v
Show more verbose output.
.El
.Ss testport
.Pp
The specified port will be tested for build and packaging problems.
All missing dependencies will first be built in parallel.
.Ev TRYBROKEN=yes
is automatically defined in the environment to test ports marked as
.Ev BROKEN .
.Pp
.Bl -tag -width "-f conffile"
.It Fl Oo o Oc Ar origin
Specifies an origin in the ports tree
.El
.Pp
Here are the options associated with the
.Cm testport
command.
.Bl -tag -width "-f conffile"
.It Fl c
Run make config for the given port.
.It Fl i
Interactive mode.
Enter jail for interactive testing and automatically cleanup when done.
A local
.Xr pkg.conf 5
repository configuration will be installed to
.Pa LOCALBASE/etc/pkg/repos/local.conf
so that
.Xr pkg 8
can be used with any existing packages built for the jail.
The FreeBSD repository will be disabled by default.
.It Fl 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:
.Dl "poudriere jail -k -j JAILNAME" .
As with
.Fl i
this will install a
.Xr pkg.conf 5
file for
.Xr pkg 8
usage.
.It Fl j Ar name
Runs only inside the jail named
.Ar name .
.It Fl J Ar number[:number]
This argument specifies how many
.Ar number
jobs will run in parallel for building the dependencies.
The optional second
.Ar 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.
The default pre-build value is 1.25 times the value of the build value.
.It Fl k
Do not consider failures as fatal.
Find all failures.
.It Fl P
Use custom prefix.
.It Fl N
Do not build package repository or INDEX when build of dependencies is completed.
.It Fl p Ar tree
Specifies which ports
.Ar tree
to use.
.It Fl 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,
pkgname matches, if the compiled options match the current options from the
.Pa make.conf
files and
.Pa /usr/local/etc/poudriere.d/options ,
and that its own dependencies did not require rebuild as well.
.It Fl S
Don't recursively rebuild packages affected by other packages requiring
incremental rebuild.
This is a subset of
.Fl s .
This may result in broken packages if the ones they depend on are updated
and are not ABI-compatible.
.It Fl v
This will show more information during the build.
Specify twice to enable debug output.
.It Fl w
Save WRKDIR on build failure.
The WRKDIR will be tarred up into
.Sy ${POUDRIERE_DATA}/wrkdirs .
.It Fl z Ar set
This specifies which SET to use for the build.
See
.Sx CUSTOMISATION
for examples of how this is used.
.El
.Ss distclean
This command accepts the following options:
.Bl -tag -width "-f conffile"
.It Fl J Ar number
This argument specifies how many
.Ar number
jobs will run in parallel for gathering distfile information.
.It Fl n
Dry run, do not actually delete anything.
.It Fl p Ar tree
Specifies which ports
.Ar tree
to use.
This can be specified multiple times to consider multiple tress.
.It Fl y
Assume yes, do not confirm and just delete the files.
.It Fl v
This will show more information during the build.
Specify twice to enable debug output.
.El
.Pp
.Ss pkgclean
This command is used to delete all packages not specified to build.
.Pp
These subcommands are mutually exclusive.
.Bl -tag -width "-f conffile"
.It Fl a
Keep all ports in the tree.
.It Fl f Ar file
Absolute path to a file which contains the list of ports to keep.
Ports must be specified in the form
.Ar category/port
and shell-style comments are allowed.
Multiple
.Fl f Ar file
arguments may be specified at once.
.It cat/port cat/port2 ...
A list of ports can be specified directly.
.El
.Pp
Here are the options associated with the
.Cm pkgclean
command.
This command accepts the following options:
.Bl -tag -width "-f conffile"
.It Fl j Ar name
Jail to use for the packages to inspect.
.It Fl J Ar number
This argument specifies how many
.Ar number
jobs will run in parallel for gathering package information.
.It Fl n
Dry run, do not actually delete anything.
.It Fl N
Do not build package repository or INDEX when done cleaning.
.It Fl p Ar tree
Specifies which ports
.Ar tree
to use.
.It Fl R
Also clean restricted packages.
.It Fl y
Assume yes, do not confirm and just delete the files.
.It Fl v
This will show more information during the build.
Specify twice to enable debug output.
.It Fl z Ar set
SET to use for the packages to inspect.
.El
.Pp
.Ss options
This command accepts the following parameters:
.Bl -tag -width "-f conffile"
.It Fl f Ar file
Absolute path to a file which contains the list of ports to configure.
Ports must be specified in the form
.Ar category/port
and shell-style comments are allowed.
.It cat/port cat/port2 ...
A list of ports can be specified directly.
.El
.Pp
This command accepts the following options:
.Bl -tag -width "-f conffile"
.It Fl c
Use 'config' target, which will always show the dialog for the given ports.
.It Fl C
Use 'config-conditional' target, which will only bring up the dialog on new options for the given ports.
(This is the default)
.It Fl j Ar jailname
If given, configure the options only for the given jail.
.It Fl p Ar portstree
Run the configuration inside the given ports tree (by default uses default)
.It Fl n
Do not be recursive
.It Fl r
Remove port options instead of configuring them
.It Fl s
Show port options instead of configuring them
.It Fl z Ar set
This specifies which SET to use for the build.
See
.Sx CUSTOMISATION
for examples of how this is used.
.El
.Pp
The
.Cm options
subcommand can also take the list of ports to configure through command line
arguments instead of the using a file list.
.Ss queue
.Pp
This command takes a
.Nm
command in argument.
.Pp
There are no options associated with the
.Cm queue
command.
.Ss status
.Nm status
sorts by SETNAME, PORTSTREE, JAILNAME and then BUILDNAME.
.Pp
This command accepts the following options:
.Bl -tag -width "-f conffile"
.It Fl a
Show all builds, not just latest.
This implies
.Fl f .
.It Fl b
Show details about what each builder for the matched builds are doing.
.It Fl B Ar name
Specifies which buildname to match on.
This supports shell globbing.
Defaults to "latest".
Specifying this implies the
.Fl f
flag.
.It Fl c
Show a more compact output and do not include some columns.
.It Fl f
Show finished builds, not just currently running.
This is implied by the
.Fl a ,
.Fl B
and
.Fl r
flags.
.It Fl H
Do not print headers and separate fields by a single tab instead of arbitrary
white space.
.It Fl j Ar name
Specifies the
.Ar name
of the jail to filter by.
.It Fl l
Show logs instead of URL.
.It Fl p Ar tree
This flag specifies which ports
.Ar tree
to filter builds by.
.It Fl r
Show build results.
This implies the
.Fl f
flag.
.It Fl z Ar set
This specifies which SET to filter builds by.
Use
.Sy 0
to match on empty SET.
.El
.Pp
.Sh ENVIRONMENT
The
.Nm
command may use the following environment variable:
.Bl -tag -width "POUDRIERE_ETC"
.It Pa POUDRIERE_ETC
If specified, the path to poudriere's config directory.
Defaults to /usr/local/etc.
.El
.Sh FILES
.Bl -tag -width ".Pa POUDRIERE_ETC/poudriere.d/poudriere.conf" -compact
.It Pa POUDRIERE_ETC/poudriere.conf
See self-documented
.Ar /usr/local/etc/poudriere.conf.sample
for example.
.It Pa POUDRIERE_ETC/poudriere.d/poudriere.conf
The configuration can be stored in the poudriere.d directory as well.
.It Pa POUDRIERE_ETC/poudriere.d
This directory contains various configuration files for the different jails.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
.Ss bulk build of binary packages
This first example provides a guide on how to use
.Nm
for bulk build packages.
.Pp
.Bq Prepare infrastructure
.Pp
First you have to create a jail, which will hold all the building
infrastructure needs.
.Pp
.Dl "poudriere jail -c -v 8.2-RELEASE -a amd64 -j 82amd64"
.Pp
A jail will take approximately 3GB of space.
.Pp
Of course you can use another version of FreeBSD, regarless on what
version you are running.
amd64 users can choose i386 arch like in this
example:
.Pp
.Dl "poudriere jail -c -v 8.1-RELEASE -a i386 -j 81i386"
.Pp
This command will fetch and install a minimal jail, small (~400MB) so
you can create a lot of them.
It will install the jail under the pool
you have chosen, at poudriere/jailname.
.Pp
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.
.Pp
.Dl "poudriere ports -c"
.Pp
A ports tree will take approximately 4GB of space.
.Pp
.Bq Specify a list of ports you want to build
.Pp
Create a flat text file in which you put the ports you want to see
built by poudriere.
.Pp
.Dl "echo 'sysutils/screen' > ~/pkglist"
.Dl "echo 'editors/vim' >> ~/pkglist"
.Pp
Any line starting with the hash sign will be treated as a comment.
.Pp
.Bq Launch the bulk build
.Pp
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.
.Dl "poudriere bulk -f ~/pkglist -j 81i386"
.Pp
.Bq Find your packages
.Pp
Once the bulk build is over, you can meet your shiny new packages here:
.Pp
.Dl "/usr/local/poudriere/data/packages/81i386"
.Pp
with 81i386 as the name of the jail.
.Ss test a single port
This second example show how to use
.Nm
for a single port.
.Pp
Let's take the example of building a single port;
.Pp
.Dl "poudriere testport -o category/port -j myjail"
.Pp
all the tests will be done in myjail.
.Pp
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).
.Pp
If packages for the dependencies already exists it will use them
.Pp
When all the dependencies are built, packages for them are created so
that next time it will be faster.
.Pp
All the dependency phase is done with PREFIX == LOCALBASE.
.Pp
After that it will build the port itself with LOCALBASE != PREFIX
and log the build to
poudriere/data/logs/testport/jailname/default/mybeautifulporttotest.log
.Pp
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.
.Pp
It is very easy to extend it so that we can easily add other tests if
wanted.
.Sh CUSTOMISATION
For bulk building, you can customize binary packages produced by
.Nm
by changing build options port by port, and you can also specify
building directives in a make.conf file.
.Ss Custom build options
Before building a package,
.Nm
can mount a directory containing option files if available.
.Nm
will check for any of these directories in this order:
.Pp
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-options
.Dl /usr/local/etc/poudriere.d/<jailname>-<setname>-options
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-options
.Dl /usr/local/etc/poudriere.d/<setname>-options
.Dl /usr/local/etc/poudriere.d/<tree>-options
.Dl /usr/local/etc/poudriere.d/<jailname>-options
.Dl /usr/local/etc/poudriere.d/options
.Pp
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.
.Pp
The
.Cm options
subcommand can be used to easily configure options in the correct directory.
.Pp
This directory has the usual layout for options: it contains one directory per
port (the name of the port) containing an 'options' file with lines similar to:
.Pp
.Dl WITH_FOO=true
.Dl WITHOUT_BAR=true
.Pp
As a starter, you may want to copy an existing /var/db/ports/ to
/usr/local/etc/poudriere.d/options.
.Ss Blacklist ports
You can also specify a blacklist which will disallow the lists port origins
from building on the matched jail.
Any of the following are allowed and will all be used in the order shown:
.Pp
.Dl /usr/local/etc/poudriere.d/blacklist
.Dl /usr/local/etc/poudriere.d/<setname>-blacklist
.Dl /usr/local/etc/poudriere.d/<tree>-blacklist
.Dl /usr/local/etc/poudriere.d/<jailname>-blacklist
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-blacklist
.Dl /usr/local/etc/poudriere.d/<jailname>-<setname>-blacklist
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-blacklist
.Pp
If QEMU is being used then a special qemu blacklist is also loaded.
.Dl /usr/local/etc/poudriere.d/qemu-blacklist
.Ss Create optional poudriere.conf
You can also specify an optional poudriere.conf that is pulled in
depending on the build.
Any of the following are allowed and will all be used in the order shown:
.Pp
.Dl /usr/local/etc/poudriere.d/poudriere.conf
.Dl /usr/local/etc/poudriere.d/<setname>-poudriere.conf
.Dl /usr/local/etc/poudriere.d/<tree>-poudriere.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-poudriere.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-poudriere.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<setname>-poudriere.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-poudriere.conf
.Ss 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:
.Pp
.Dl /usr/local/etc/poudriere.d/make.conf
.Dl /usr/local/etc/poudriere.d/<setname>-make.conf
.Dl /usr/local/etc/poudriere.d/<tree>-make.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-make.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-make.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<setname>-make.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-<tree>-<setname>-make.conf
.Ss Create optional src.conf
You can also specify a global src.conf which will be used for building
jails with the
.Cm jail -c
subcommand.
Any of the following are allowed and will all be used in the order shown:
.Pp
.Dl /usr/local/etc/poudriere.d/src.conf
.Dl /usr/local/etc/poudriere.d/<setname>-src.conf
.Dl /usr/local/etc/poudriere.d/<jailname>-src.conf
.Sh CAVEATS
.Ss Jailname
.Fl j ,
.Fl z
and
.Fl p
are all used in the name of the jail.
.Pp
Be careful to respect the names supported by jail(8):
.Pp
.Bd -literal
    "This is an arbitrary string that identifies a jail (except it
     may not contain a '.')"
.Ed
.Pp
Be also careful to not begin the name of the jail by a number if you are
not in -stable or current:
.Pp
.Lk http://svn.freebsd.org/viewvc/base?view=revision&revision=209820
.Sh BUGS
In case of bugs, feel free to file a report:
.Pp
.Lk https://github.com/freebsd/poudriere/issues
.Sh AUTHORS
.An Baptiste Daroussin Aq bapt@FreeBSD.org
.An Bryan Drewery Aq bdrewery@FreeBSD.org