portshaker.d.5.in

.\" $Id$
.Dd September 30, 2008
.Dt PORTSHAKER.D 5
.Os
.Sh NAME
.Nm portshaker.d/
.Nd format of
.Xr portshaker 8
sources update scripts
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
The
.Nm
directory contains shell scripts used to maintain
.Xr portshaker 8
.Ar target
ports trees.  Each script correspond to a
.Ar source
ports tree, and provide the required functions required by
.Xr portshaker 8
to merge to
.Ar target
ports trees.
.Ss Syntax
In order to ease development,
.Xr portshaker 8
provides the
.Ar portshaker.subr
scripts that contains all the logic for managing
.Ar source
ports trees. In order to configure a
.Ar source
ports tree, you have to source that file, specify how the
ports tree has to be fetched (see bellow), and run the
.Ar run_portshaker_command()
function as detailed in the EXAMPLES section.
.Pp
The script is in charge of consuming any argument up to (and including) the first --. These arguments are separated by a column in
.Xr portshaker.conf 5
(e.g.
.Va github:account:project ) .
.Pp
The following variable are available to configure how the
.Ar source
ports tree has to be fetched:
.Bl -tag -width svn_checkout_subtrees
.It Ar method
.Pq Vt str
Update method. Should be one of
.Va csup ,
.Va cvs ,
.Va portsnap ,
.Va git ,
.Va hg
(mercurial),
.Va rsync ,
.Va svn ,
or
.Va svn+subtrees .
.It Ar csup_supfile
.Pq Vt str
supfile to provide to
.Xr csup 1
when
.Dq Ar method Ns Li = Ns Vt csup .
.It Ar cvs_root
.Pq Vt str
CVSROOT string to use for checking-out the ports tree when
.Dq Ar method Ns Li = Ns Va cvs .
.It Ar cvs_module
.Pq Vt str
cvs module to checkout when
.Dq Ar method Ns Li = Ns Va cvs .
.It Ar git_clone_uri
.Pq Vt str
git URI to clone when
.Dq Ar method Ns Li = Ns Vt git .
.It Ar git_branch
.Pq Vt str
branch to track when
.Dq Ar method Ns Li = Ns Vt git .
.It Ar git_submodules
.Pq Vt str
fetch submodules when
.Dq Ar method Ns Li = Ns Vt git .
.It Ar git_submodules_branch
.Pq Vt str
submodule branch to track when
.Dq Ar method Ns Li = Ns Vt git .
.It Ar hg_clone_uri
.Pq Vt str
mercurial URI to clone when
.Dq Ar method Ns Li = Ns Vt hg .
.It Ar rsync_source_path
.Pq Vt str
path to copy data from when
.Dq Ar method Ns Li = Ns Va rsync .
.It Ar rsync_extra_args
.Pq Vt str
extra arguments to pass to
.Xr rsync 1
when
.Dq Ar method Ns Li = Ns Va rsync .
.It Ar svn_checkout_path
.Pq Vt str
URI to checkout the ports tree from when
.Dq Ar method Ns Li = Ns Vt svn
or
.Dq Ar method Ns Li = Ns Vt svn+subtrees .
.It Ar svn_checkout_subtrees
.Pq Vt str
Whitespace separated list of subdirectories
.Ar path[@rev]
beneath the
.Ar svn_checkout_path
which will be checked out when
.Dq Ar method Ns Li = Ns Vt svn+subtrees .
.El
.Ss Special consideration when Dq Ar method Ns Li = Ns Vt csup
When updating a
.Ar source
ports tree using the
.Ar csup
method, the
.Ar source
ports tree name has to be
.Ar ports
because the remote collection is named likely.
.Xr portshaker 8
will ensure this condition is met before attempting to perform any update.
.Ss Hooking
An update script may define the
.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 ()
function hooks, where
.Va action
is one of
.Vt update , Vt clone_to , Vt copy_to Li or Vt merge_to .
.Sh EXAMPLES
To configure the official FreeBSD ports tree as a
.Ar source
ports tree, create a
.Ar @@PREFIX@@/etc/portshaker.d/ports
shell script containing:
.Bd -literal
#!/bin/sh
\&. @@PREFIX@@/share/portshaker/portshaker.subr
if [ "$1" != '--' ]; then
	err 1 "Extra arguments"
fi
shift
method="portsnap"
run_portshaker_command "$@"
.Ed
.Pp
To configure the BSD# ports tree as a
.Ar source
ports tree, create a
.Ar @@PREFIX@@/etc/portshaker.d/bsd_sharp
shell script containing:
.Bd -literal
#!/bin/sh
\&. @@PREFIX@@/share/portshaker/portshaker.subr
if [ "$1" != '--' ]; then
	err 1 "Extra arguments"
fi
shift
method="svn"
svn_checkout_path="http://bsd-sharp.googlecode.com/svn/trunk/"
run_portshaker_command "$@"
.Ed
.Pp
If you want only a subset of ports from the (huge) FreeBSD tree as a
.Ar source
ports tree (probably to merge with some other tree), create a
.Ar @@PREFIX@@/etc/portshaker.d/freebsd_subset
shell script containing:
.Bd -literal
#!/bin/sh
\&. @@PREFIX@@/share/portshaker/portshaker.subr
if [ "$1" != '--' ]; then
	err 1 "Extra arguments"
fi
shift
method="svn+subtrees"
svn_checkout_path="svn://svn.freebsd.org/ports/head"
svn_checkout_subtrees="
  emulators/mame
  net/samba34@319916
"
run_portshaker_command "$@"
.Ed
.Pp
To setup a dynamic redports
.Ar source
ports tree, create a
.Ar @@PREFIX@@/etc/portshaker.d/redports
shell script containing:
.Bd -literal
#!/bin/sh
\&. /usr/local/share/portshaker/portshaker.subr
if [ "$1" != '--' ]; then
	err 1 "Extra arguments"
fi
shift
username="$1"
extra_info=":${username}"
shift
method="svn"
svn_checkout_path="http://svn.redports.org/${username}"
run_portshaker_command "$@"
.Ed
.Pp
You can then specify the
.Ar foo
and
.Ar bar
ports tree at redports specifying the
.Ar redports:foo
and
.Ar redports:bar
.Ar source
ports tree in your
.Ar portshaker.conf
configuration file.
.Pp
To use git as the
.Ar source
ports tree using submodules, create a
.Ar @@PREFIX@@/etc/portshaker.d/git_ports
shell script containing:
.Bd -literal
#!/bin/sh
\&. /usr/local/share/portshaker/portshaker.subr
if [ "$1" != '--' ]; then
	err 1 "Extra arguments"
fi
shift
method="git"
git_clone_uri="git@github.com:freebsd/freebsd-ports.git"
git_branch="master"
git_submodules="yes"
git_submodules_branch="development"
run_portshaker_command "$@"
.Sh SEE ALSO
.Xr csup 1 ,
.Xr portshaker 8 ,
.Xr portshaker.conf 5
.Sh AUTHORS
.An Romain Tartière Aq romain@blogreen.org