portshaker/portshaker-1.0.19/portshaker.conf.5.in

.\" $Id$
.Dd September 30, 2008
.Dt PORTSHAKER.CONF 5
.Os
.Sh NAME
.Nm portshaker.conf
.Nd format of the
.Xr portshaker 8
configuration file
.Sh DESCRIPTION
The file
.Nm
contains descriptive information about which
.Ar source
ports trees
.Xr portshaker 8
has to be merged into which
.Ar target
ports trees.
.Pp
Options are set with
.Dq Ar name Ns Li = Ns Ar value
assignments that use
.Xr sh 1
syntax.
The following list provides a name and short description for each
variable that can be set in the
.Nm
file:
.Bl -tag -width mirror_base_dir
.It Va mirror_base_dir
.Pq Vt str
Base directory where
.Xr portshaker 8
will fetch
.Ar source
ports trees.
.It Va ports_trees
.Pq Vt str
Set to the list of
.Ar target
ports trees to maintain.
.Pp
A
.Ao Ar target Ac Ns Va _ports_tree
or a
.Ao Ar target Ac Ns Va _poudriere_tree
variable must be set to tell
.Xr portshaker 8
where the ports trees has to be merged to and a
.Ao Ar target Ac Ns Va _merge_from
variable must be set to the list of
.Ar source
ports trees to merge from.
.Pp
When specifying a
.Ao Ar target Ac Ns Va _ports_tree ,
it should be set to the full path of the directory where the
.Ar target
ports tree is located.
.Pp
When specifying a
.Ao Ar target Ac Ns Va _poudriere_tree ,
it should be set to the
.Ar name
of the ports tree that will be later-on used with
.Xr poudriere 8 .
.Pp
.Ao Ar target Ac Ns Va _ports_tree
and
.Ao Ar target Ac Ns Va _poudriere_tree
are mutually exclusive.
.Pp
If the
.Ar source
ports tree name contains colons, they are replaced by spaces and
.Xr portshaker 8
will pass these extra argument to the script named by the first component. This
allowing some kind of factorisation for multiple sources in a single
repository.
.Pp
If a
.Ar source
ports tree is known to provide ports that are already provided in another ports
tree, and while both ports provide the same version of a software package they
do not contain the same files,
.Xr portshaker 8
can be told to automatically install the updated ports without prompting the
user by appending an exclamation mark after the
.Ar source
ports tree name.
.Pp
Alternatively, appending a plus sign after the
.Ar source
ports tree name will, regardless of version, install or replace matching files
in the
.Ar target
port tree whilst preserving any pre-existing non matching port files. This is
useful when the
.Ar source
ports tree contains an incomplete subset of files for instance only local
patches.
.It Va fail_on_conflict
.Pq Vt bool
Fail if a merge conflict is encountered.
.It Va poudriere_dataset
.Pq Vt string
The ZFS filesystem
.Xr poudriere 8
is configured to use.
.It Va poudriere_ports_mountpoint
.Pq string
The directory where
.Xr poudriere 8
ports directory are mounted, usually
.Ar @@PREFIX@@/poudriere/ports .
.It Va source_zfs_compression
.Pq Vt string
ZFS compression to use when creating a
.Ar source
ports tree (require
.Ar use_zfs
to be set).  Defaults to
.Ar lz4 .
.It Va target_zfs_compression
.Pq Vt string
ZFS compression to use when creating a
.Ar target
ports tree (require
.Ar use_zfs
to be set).  Defaults to
.Ar off .
.It Va use_zfs
.Pq Vt bool
Whether to use ZFS for cloning the first
.Ar source
ports tree to the
.Ar target
ports tree.
.Pp
When set, the
.Ar mirror_base_dir
directory should be a ZFS filesystem for
.Xr portshaker 8
to create new ZFS filesystems automatically (one per
.Ar source
ports tree); otherwise the ZFS filesystem shall be created by the user before
running
.Xr portshaker 8
for the first time.
.Pp
A
.Ao Ar target Ac Ns Va _zfs_dataset
variable can be used to control the ZFS dataset used for the filesystem. By default, a dataset with the name of the
.Ar target
ports tree is created as a child of the dataset of the
.Ar target
ports tree's parent directory's dataset (i.e. if the
.Ar /usr
filesystem's dataset is
.Ar data/foo ,
then the dataset for the
.Ar /usr/ports
directory will be
.Ar data/foo/ports ) .
This requires the
.Ar target
ports tree's parent directory to be a ZFS filesystem.
.Pp
When using this option, you may want to set
.Ar DISTDIR
and
.Ar PACKAGES
in
.Ar /etc/make.conf
in order to avoid lossing distfiles and packages each time you merge your
.Ar target
ports tree.
.It Va verbose
.Pq Vt int
Default verbosity level,
.Vt 0
if unspecified.
.El
.Ss Hooking
Hooks for
.Xr portshaker 8
can be defined in
.Nm
as functions named
.Ao Ar port_tree Ac Ns Ar _pre Ns Ao Ar action Ac Ns ()
and
.Ao Ar port_tree Ac Ns Ar _post Ns Ao Ar action Ac Ns ()
where
.Va action
is one of
.Vt update
or
.Vt merge .
.Sh EXAMPLES
To maintain a single ports tree with BSD# ports:
.Bd -literal
ports_trees="main"
main_ports_tree="/usr/ports"
main_merge_from="ports bsd_sharp"
.Ed
.Pp
To configure a tinderbox with official ports tree (tb_official), a second one with BSD# ports tree (tb_bsd_sharp), a third one with GNOME-devel ports tree (tb_gnome) and a last one with both upcomming BSD# and GNOME (tb_bsd_sharp_gnome):
.Bd -literal
ports_trees="tb_official tb_bsd_sharp tb_gnome tb_bsd_sharp_gnome"

tb="@@PREFIX@@/tinderbox/"
tb_official_ports_tree="${tb}/portstrees/FreeBSD/ports"
tb_official_merge_from="ports"

tb_bsd_sharp_ports_tree="${tb}/portstrees/BSD-sharp/ports"
tb_bsd_sharp_merge_from="ports bsd_sharp"

tb_gnome_ports_tree="${tb}/portstrees/GNOME/ports"
tb_gnome_merge_from="ports gnomedevel"

tb_bsd_sharp_gnome_ports_tree="${tb}/portstrees/BSD-sharp-gnome/ports"
tb_bsd_sharp_gnome_merge_from="ports bsd_sharp gnomedevel"
.Ed
.Pp
To merge multiples redports sources in a single target ports tree:
.Bd -literal
ports_trees="main"
main_ports_tree="/usr/ports"
main_merge_from="ports redports:foo redports:bar"
.Ed
.Sh SEE ALSO
.Xr make.conf 5 ,
.Xr portshaker.d 5 ,
.Xr portshaker 8 ,
.Xr poudriere 8
.Sh AUTHORS
.An Romain Tarti�re Aq romain@blogreen.org