path: root/poudriere.8

.\" Copyright (c) [year] [your name]
.\" 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 December 22, 2011
.Dt POUDRIERE 8
.Os FreeBSD
.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 package from the FreeBSD ports tree.
It can also be used to test a single port.
.Pp
Its goals are to use modern facilities present in FreeBSD (as ZFS,
jails), to be easy to use and to depend only on base.
.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 bulk builds a ready-to-export package tree from a given
list of ports.
.It jail
This command gives you control to manage the jails used by
.Nm
to provide building environment (different FreeBSD versions, different
architectures).
.It ports
This command allows you to manage different portstree which will be used
by
.Nm
(create, update and delete portstrees).
.It testport
This command, mainly targeted at FreeBSD ports developers, launches a
test on a given port (useful before submitting/commiting a port).
.El
.Sh SUBCOMMANDS
Here are the list of subcommands and associated options supported by
.Nm ,
sorted by
.Cm command
order.
.Ss bulk
.Pp
There is only one subcommand for bulk command.
.Bl -tag -width "-f conffile"
.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.
.El
.Pp
Here are the options associated with the
.Cm bulk
command.
.Bl -tag -width "-f conffile"
.It Fl k
This flags specifies to keep the previous built binary packages.
.It Fl j Ar name
If given, run the bulk build only on the jail named
.Ar name.
.It Fl p Ar tree
This flag specifies on which ports
.Ar tree
the bulk build will be done.
.El
.\" comment
.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 l
List all available jails.
.It Fl s
Starts a jail.
.It Fl k
Kills a jail (stops it).
.El
.Pp
Excepted for
.Fl l ,
all these subcommands requires
.Fl j
option (see below).
.Pp
Here are the options associated with the
.Cm jail
command.
.Bl -tag -width "-f conffile"
.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 we want in jail.
.It Fl a Ar architecture
Specifies which
.Ar architecture
of FreeBSD we want in jail. (Default: same as host)
.It Fl m Ar method
Specifies which
.Ar method
we want to create jail. Specify
.Ar NONE
if you want to use your homemade jail. (Default: FTP)
.It Fl f Ar filesystem
Specifies the
.Ar filesystem
name (${ZPOOL}/jails/filesystem).
.It Fl M Ar mountpoint
Gives an alternative
.Ar mountpoint
when creating jail.
.El
.\" PORTS
.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 u
Updates a ports tree.
.It Fl l
List all available ports trees.
.El
.Pp
Excepted for
.Fl l ,
all these subcommands requires
.Fl p
switch (see below).
.Pp
Here are the options associated with the
.Cm ports
command.
.Bl -tag -width "-f conffile"
.It Fl q
Remove the header when
.Fl l
is the specified subcommand. Otherwise, it has no effect.
.It Fl p Ar name
Specifies the
.Ar name
of the ports tree we are working on.
.It Fl F
When used with
.Fl c ,
only create the needed ZFS file systems and directories, but do not
populate them.
.It Fl f Ar filesystem
Specifies the
.Ar filesystem
name (${ZPOOL}/jails/filesystem).
.It Fl M Ar mountpoint
Gives an alternative
.Ar mountpoint
when creating jail.
.El
.\" BLABLA TEST PORT
.Ss testport
.Pp
These subcommands are mutually exclusive.
.Bl -tag -width "-f conffile"
.It Fl d Ar path
Specifies on which port we work.
.It Fl o 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 j Ar name
Runs only inside the jail named
.Ar name .
.It Fl n
Do not use custom prefix.
.It Fl p Ar tree
Specifies on wich ports
.Ar trr
we work.
.El
.Sh ENVIRONMENT
The
.Nm
command does not use any
environment variable.
.Sh FILES
.Bl -tag -width ".Pa /usr/local/etc/poudriere.conf" -compact
.It Pa /usr/local/etc/poudriere.conf
See self-documented
.Ar /usr/local/etc/poudriere.conf.sample
for example.
.It Pa /usr/local/etc/poudriere.d
This directory contains
.Ar make.conf
files for your different jails.
.El
.Sh EXIT STATUS
.Ex -std
.\".Sh EXAMPLES
.\"The following is an example of a typical usage
.\"of the
.\".Nm
.\"command:
.\".Pp
.\".Dl "example -abc -d xyzzy /dev/null"
.\".Sh DIAGNOSTICS
.\"The command may fail for one of the following reasons:
.\".Bl -diag
.\".It "example error message"
.\"An example of an error message.
.\".It "another example error message."
.\"Self explanatory.
.\".El
.Sh COMPATIBILITY
The
.Nm
command must be used on a recent version of FreeBSD, i.e. a version
which has ZFS >= v15, and a zpool.
.\".Sh SEE ALSO
.\".Xr example 3 ,
.\".Xr example 4 ,
.\".Xr mdoc 7 ,
.\".Xr example 9
.\".Rs
.\".%A "A. B. Author"
.\".%T "Example RFC Title"
.\".%O RFC0000
.\".Re
.\".Rs
.\".%A "A. B. Author"
.\".%B "Example Book Title"
.\".%O ISBN-0-000-00000-0
.\".Re
.\".Rs
.\".%A "A. B. Author"
.\".%D "January 1997"
.\".%J "Example Journal Name"
.\".%T "Example Article Title"
.\".Re
.\".Sh STANDARDS
.\"If the command conforms to some standard, such as
.\".St -p1003.2
.\"or
.\".St -isoC ,
.\"it should be noted here.
.\".Sh HISTORY
.\"The
.\".Nm
.\"manual page example first appeared in
.\".Fx 2.2 .
.\".Pp
.\"Some other common
.\".Sx HISTORY
.\"section examples are:
.\".Pp
.\"The
.\".Nm
.\"manual page example first appeared in
.\".Bx 4.4 .
.\".Pp
.\"The
.\".Nm
.\"manual page example first appeared in
.\".At v6 .
.Sh AUTHORS
.An Baptiste Darroussin Aq bapt@freebsd.org
.Sh CONTRIBUTORS
.An Philippe Audeoud Aq jadawin@tuxaco.net
.An Freddy Dissaux Aq freddy.dsx@free.fr
.An Gregoire Doumergue Aq gdoumergue@veepee.com
.An Julien Laffaye Aq jlaffaye@FreeBSD.org
.An Mathieu Launay Aq mathieu@breatheless.net
.An Romain Tartiere Aq romain@blogreen.org
.\".Sh BUGS
.\"The actual code for this command is vaporware.