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

FreeBSD Manual Pages

  
 
  

home | help
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 FreeBSD ports tree.
     It	can also be used to test a single port.

     Its goals are to use modern facilities present in FreeBSD (as ZFS,
     jails), to	be easy	to use and to depend only on base.

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.

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 gives you control to manage the jails used by
		  poudriere to provide building	environment (different FreeBSD
		  versions, different architectures).

     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 FreeBSD ports developers,
		  launches a test on a given port (useful before submit-
		  ting/committing a port).

     options	  This command allows to configure the options for a given
		  port

     distclean	  This command will cleanup old	distfiles

     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.

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

     The list of ports can also	be provided by command line arguments.

     Here are the options associated with the bulk command.

     -a		  Build	all ports in the tree.

     -B	name	  Specify which	buildname to use.  By default
		  YYYY-MM-DD_HH:MM:SS will be used.  This can be used to re-
		  sume a previous build	and use	the same log and URL paths.

     -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	  If given, run	the bulk build only on the jail	named name.

     -J	number	  This argument	specifies how many number jobs will run	in
		  parallel for a bulk build.

     -N		  Do not build package repository or INDEX when	build is com-
		  pleted.

     -p	tree	  This flag specifies on which ports tree the bulk build will
		  be done.

     -s		  Skip sanity tests.  Sanity tests are made to check if	the
		  ports	exists,	does not have an increased version number, and
		  if the compiled options match	the current options from the
		  make.conf files and /var/db/options.

     -t		  Add some testing to the specific ports.  Currently unin-
		  stalls the port, and disable parallel	jobs for make.

     -r		  Recrusively test all dependencies as well.

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

     -l		  List all available jails.

     -s		  Starts a jail.

     -k		  Kills	a jail (stops it).

     -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 csup then the
		  version should be in the form	of cvs branches: RELENG_9 or .
		  for current.	If you are using method	svn then the version
		  should be in the form	of svn branches: stable/9 or head for
		  current.

     -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.  Can be
		  csup,	svn{,+http,+https,+file,+ssh), ftp, allbsd, or url=
		  (Default: ftp).  When	using url=, specify the	URL to the
		  distributions.  Any URL supported by fetch(1)	can be used;
		  for example:
			poudriere jail -c -j 100amd64 -a amd64 -v 10.0 -m
			url=file:///mirror/10.0

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

     -M	mountpoint
		  Gives	an alternative mountpoint when creating	jail.

     -p	name	  This specifies which port tree to start/stop the jail	with.

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

   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.

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

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

     -M	mountpoint
		  Gives	an alternative mountpoint when creating	ports tree.

     -m	method	  Specifies which method to use	to create the ports tree.
		  Could	be portsnap, git, svn{,+http,+https,+file,+ssh}	(De-
		  fault: portsnap).

     -v		  Show more verbose output.

     -B	branch	  Specifies which branch to checkout when using	the svn
		  method.  (Default: head)

   testport
     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.  The	PACKAGESITE environ-
		  ment variable	will be	set so that pkg(8) will	be able	to be
		  used with any	existing packages built	for the	jail.

     -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

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

     -n		  Do not use custom prefix.

     -p	tree	  Specifies which ports	tree to	use.

     -s		  Skip sanity tests.  Sanity tests are made to check if	the
		  ports	exists,	does not have an increased version number, and
		  if the compiled options match	the current options from the
		  make.conf files and /var/db/options.

     -v		  This will show more information during the build.  Specify
		  twice	to enable debug	output.

     -z	set	  This specifies whith 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.

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

   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.

     The list of ports can also	be provided by command line arguments.

     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	de-
		  fault	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 whith 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
     thought 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
     This command accepts the following	options:

     -j	name	  Specifies the	name of	the jail to view the status of.

     -p	tree	  This flag specifies which ports tree the build is running on
		  when using -j

     -z	set	  This specifies which SET the build is	running	on when	using
		  -j

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	   This	directory contains make.conf files for
				   your	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	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 ver-
     sion you are running.  amd64 users	can choose i386	arch like in this ex-
     ample:

	   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/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 op-
     tion files	if available.  poudriere will check for	any of these directo-
     ries 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/lo-
     cal/etc/poudriere.d/options.

   Create optional make.conf
     You can also specify a global make.conf which will	be used	for all	the
     jails, and	also add a per-jail, per-set, or per-jail-set make.conf.  They
     will all be used in the jail, 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

COMPATIBILITY
     The poudriere command must	be used	on a recent version of FreeBSD,	i.e. a
     version which has ZFS >= v15, and a zpool.

CAVEATS
   Jailname
     -j	is the name of the jail	which will also	be the name of the zfs
     filesystem.

     Be	careful	to respects 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 fill

     http://fossil.etoilebsd.net/poudriere/reportlist

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

FreeBSD				 June 28, 2013			       FreeBSD

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

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

home | help