Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
POUDRIERE(8)            FreeBSD 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
                  configuration data.  See FILES and ENVIRONMENT for more
                  information.

     -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.

     ports        This command allows you to manage different portstrees which
                  will be used by poudriere (create, update and delete
                  portstrees).

     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
                  commands.  It is currently EXPERIMENTAL.  Using it requires
                  starting poudriered via the provided rc script.

     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.

     -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
                  mirrors.

     -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.

     -i           Interactive mode.  Enter jail for interactive testing and
                  automatically cleanup when done.  A local pkg.conf(5)
                  repository 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
                  FreeBSD repository will be disabled by default.

     -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:
                        poudriere jail -k -j JAILNAME.
                  As with -i this will install a pkg.conf(5) file for pkg(8)
                  usage.

     -n           Dry run. Show what woud be done, but do not actually build
                  or delete any packages.

     -N           Do not build package repository or INDEX 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,
                  pkgname 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
                  dependencies did not require rebuild as well.

     -S           Don't recursively rebuild packages affected by other
                  packages 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
                  recursively test all port dependencies as well.  Currently
                  uninstalls 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
                  automatically 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.

     -k           Kills a jail (stops it).

     -r name      Rename a jail to name.

     -u           Update a jail.

     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.

     -j name      Specifies the name of the jail.

     -v version   Specifies which version of FreeBSD to use in the jail.  If
                  you are using method ftp then the version should in the form
                  of: 9.0-RELEASE.  If you are using method svn then the
                  version should be in the form of svn branches: stable/9 or
                  head for current.  Other methods only use the value for
                  display.

     -a architecture
                  Specifies which architecture of FreeBSD to use in the jail.
                  (Default: same as host)

     -m method    Specifies which method to use to create the jail.  (default:
                  ftp)

                  Pre-built distribution options:

                  allbsd         Use www.allbsd.org.

                  ftp http       Fetch from configured FREEBSD_HOST variable
                                 from poudriere.conf.

                  ftp-archive    Fetch from ftp-archive.freebsd.org.

                  null           This option can be used to import an existing
                                 directory that already contains an installed
                                 system.  The path must be specified with -M
                                 path.  It is expected that this directory be
                                 installed to with the following:

                                       /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

                                 The path will be null-mounted during builds.
                                 It will not be copied at the time of running
                                 jail.  Deleting the jail will attempt to
                                 revert any files changed by poudriere.

                  src=PATH       Install from the given src directory at PATH.
                                 This directory will not be built from.  It is
                                 expected that it is already built and maps to
                                 a corresponding /usr/obj directory.

                  tar=PATH       Install from the tarball at the given PATH.
                                 Note that this method requires the tarball
                                 contains the /usr/src files as well if you
                                 plan to build any port containing modules.

                  url=PATH       Fetch from given PATH.  Any URL supported by
                                 fetch(1) can be used.  For example:
                                       url=file:///mirror/10.0

                  Build from source options:

                  svn svn+file svn+http svn+https
                                 Use SVN.  This will use the SVN_HOST variable
                                 in poudriere.conf.

     -f filesystem
                  Specifies the filesystem name (${ZPOOL}/jails/filesystem).

     -K kernelname
                  Install the jail with a kernel.  If the kernelname is an
                  empty string GENERIC will be used.  If installing from ftp
                  then the default kernel will be installed what ever the
                  kernelname value is.

     -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.

     -S srcpath   Use the specified srcpath as the FreeBSD source tree mounted
                  inside 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.

     -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.

   ports
     These subcommands are mutually exclusive.

     -c           Creates a ports tree.

     -d           Deletes a ports tree.

     -l           List all available ports trees.

     -u           Update a ports tree.

     Except for -l, all of the subcommands require the -p switch (see below).

     Here are the options associated with the ports command.

     -B branch    Specifies which branch to checkout when using the svn or git
                  methods.  (Default: head/master)

     -F           When used with -c, only create the needed file systems (for
                  ZFS) and directories, but do not populate them.

     -M mountpoint
                  Path to the source of a ports tree.

     -f filesystem
                  The name of the filesystem to create for the ports tree.  If
                  'none' then do not create a filesystem.  Defaults to
                  poudriere/ports/default.

     -k           When used with -d, only unregister the ports tree without
                  removing the files.

     -m method    When used with -c, specify which method to use to create the
                  ports tree.  Could be portsnap, git, none,
                  svn{,+http,+https,+file,+ssh}.  The default is portsnap.

     -n           When combined with -l, only display the name of the ports
                  tree.

     -p name      Specifies the name of the ports tree to use.

     -q           When used with -l, remove the header in the list view.

     -v           Show more verbose output.

   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.

     -[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)
                  repository 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
                  FreeBSD 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,
                  pkgname 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
                  dependencies did not require rebuild as well.

     -S           Don't recursively rebuild packages affected by other
                  packages 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
                  arguments 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
     infrastructure needs.

           poudriere jail -c -v 8.2-RELEASE -a amd64 -j 82amd64

     A jail will take approximately 3GB of space.

     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:

           poudriere jail -c -v 8.1-RELEASE -a i386 -j 81i386

     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.

     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 4GB 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 81i386

     [Find your packages]

     Once the bulk build is over, you can meet your shiny new packages here:

           /usr/local/poudriere/data/packages/81i386

     with 81i386 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/mybeautifulporttotest.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
     specify 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
     directories 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
     directory 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
     origins 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

     If QEMU is being used then a special qemu blacklist is also loaded.
           /usr/local/etc/poudriere.d/qemu-blacklist

   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:

           /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/<setname>-src.conf
           /usr/local/etc/poudriere.d/<jailname>-src.conf

CAVEATS
   Jailname
     -j, -z and -p are all used in the name of the jail.

     Be careful to respect the names supported by jail(8):

         "This is an arbitrary string that identifies a jail (except it
          may not contain a '.')"

     Be also careful to not begin the name of the jail by a number if you are
     not in -stable or current:

     http://svn.freebsd.org/viewvc/base?view=revision&revision=209820

BUGS
     In case of bugs, feel free to file a report:

     https://github.com/freebsd/poudriere/issues

AUTHORS
     Baptiste Daroussin <bapt@FreeBSD.org>
     Bryan Drewery <bdrewery@FreeBSD.org>

FreeBSD 11.0-PRERELEASE          June 1, 2016          FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | GLOBAL OPTIONS | COMMANDS | SUBCOMMANDS | ENVIRONMENT | FILES | EXIT STATUS | EXAMPLES | CUSTOMISATION | CAVEATS | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=poudriere&sektion=8&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help