Adding upstream version 2.23.7.upstream/2.23.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 388 insertions, 0 deletions

diff --git a/scripts/cowpoke.1 b/scripts/cowpoke.1
new file mode 100644
index 0000000..7d5177b
--- /dev/null
+++ b/scripts/cowpoke.1
@@ -0,0 +1,388 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH COWPOKE 1 "April 28, 2008"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+cowpoke \- Build a Debian source package in a remote cowbuilder instance
+.SH SYNOPSIS
+.B cowpoke
+.RI [ options ] " packagename.dsc"
+
+.SH DESCRIPTION
+Uploads a Debian source package to a \fBcowbuilder\fR host and builds it,
+optionally also signing and uploading the result to an incoming queue.
+
+
+.SH OPTIONS
+The following options are available:
+
+.TP
+.BI \-\-arch= architecture
+Specify the Debian architecture(s) to build for.  A space separated list of
+architectures may be used to build for all of them in a single pass.  Valid
+arch names are those returned by \fBdpkg-architecture\fP(1) for
+\fBDEB_BUILD_ARCH\fP.
+
+.TP
+.BI \-\-dist= distribution
+Specify the Debian distribution(s) to build for.  A space separated list of
+distributions may be used to build for all of them in a single pass.  Either
+codenames (such as \fBsid\fP, or \fBsqueeze\fP) or distribution names (such as
+\fBunstable\fP, or \fBexperimental\fP) may be used, but you should usually stick
+to using one or the other consistently as this name may be used in file paths
+and to locate old packages for comparison reporting.
+
+It is now also possible to use locally defined names with this option, when
+used in conjunction with the \fBBASE_DIST\fP option in a configuration file.
+This permits the maintenance and use of specially configured build chroots,
+which can source package dependencies from the backports archives or a local
+repository, or have other unusual configuration options set, without polluting
+the chroots you use for clean package builds intended for upload to the main
+repositories.  See the description of \fBBASE_DIST\fP below.
+
+.TP
+.BI \-\-buildd= host
+Specify the remote host to build on.
+
+.TP
+.BI \-\-buildd\-user= name
+Specify the remote user to build as.
+
+.TP
+.B \-\-create
+Create the remote \fBcowbuilder\fR root if it does not already exist.  If this option
+is not passed it is an error for the specified \fB\-\-dist\fP or \fB\-\-arch\fP
+to not have an existing \fBcowbuilder\fR root in the expected location.
+
+The \fB\-\-buildd\-user\fP must have permission to create the \fBRESULT_DIR\fP
+on the build host, or an admin with the necessary permission must first create
+it and give that user (or some group they are in) write access to it, for this
+option to succeed.
+
+.TP
+.BR \-\-return= [ \fIpath ]
+Copy results of the build to \fIpath\fP.  If \fIpath\fP is not specified, then return
+them to the current directory. The given \fIpath\fP must exist, it will not be created.
+
+.TP
+.B \-\-no\-return
+Do not copy results of the build to \fBRETURN_DIR\fP (overriding a path set for
+it in the configuration files).
+
+.TP
+.BI \-\-dpkg\-opts= "'opt1 opt2 ...'"
+Specify additional options to be passed to \fBdpkg-buildpackage\fP(1).  Multiple
+options are delimited with spaces.  This will override any options specified in
+\fBDEBBUILDOPTS\fP in the build host's \fIpbuilderrc\fP.
+
+.TP
+.BI \-\-create\-opts= "'cowbuilder option'"
+Specify additional arguments to be passed verbatim to \fBcowbuilder\fR when a
+chroot is first created (using the \fB\-\-create\fP option above). If multiple
+arguments need to be passed, this option should be specified separately for
+each of them.
+
+E.g., \fB\-\-create\-opts "\-\-othermirror" \-\-create\-opts "deb http:// ..."\fP
+
+This option will override any \fBCREATE_OPTS\fP specified for a chroot in the
+cowpoke configuration files.
+
+.TP
+.BI \-\-update\-opts= "'cowbuilder option'"
+Specify additional arguments to be passed verbatim to \fBcowbuilder\fR if the
+base of the chroot is updated.  If multiple arguments need to be passed, this
+option should be specified separately for each of them.
+
+This option will override any \fBUPDATE_OPTS\fP specified for a chroot in the
+cowpoke configuration files.
+
+.TP
+.BI \-\-build\-opts= "'cowbuilder option'"
+Specify additional arguments to be passed verbatim to \fBcowbuilder\fR when
+a package build is performed.  If multiple arguments need to be passed, this
+option should be specified separately for each of them.
+
+This option will override any \fBBUILD_OPTS\fP specified for a chroot in the
+cowpoke configuration files.
+
+.TP
+.BI \-\-sign= keyid
+Specify the key to sign packages with.  This will override any \fBSIGN_KEYID\fP
+specified for a chroot in the cowpoke configuration files.
+
+.TP
+.BI \-\-upload= queue
+Specify the dput queue to upload signed packages to.  This will override any
+\fBUPLOAD_QUEUE\fP specified for a chroot in the cowpoke configuration files.
+
+.TP
+.B \-\-help
+Display a brief summary of the available options and current configuration.
+
+.TP
+.B \-\-version
+Display the current version information.
+
+
+.SH CONFIGURATION OPTIONS
+When \fBcowpoke\fP is run the following configuration options are read from
+global, per\-user, and per\-project configuration files if present.  File paths
+may be absolute or relative, the latter being relative to the \fBBUILDD_USER\fR's
+home directory.  Since the paths are typically quoted when used, tilde expansion
+will \fBnot\fP be performed on them.
+
+.SS Global defaults
+These apply to every \fIarch\fP and \fIdist\fP in a single cowpoke invocation.
+
+.TP
+.B BUILDD_HOST
+The network address or fqdn of the build machine where \fBcowbuilder\fR is configured.
+This may be overridden by the \fB\-\-buildd\fP command line option.
+.TP
+.B BUILDD_USER
+The unprivileged user name for operations on the build machine.  This defaults
+to the local name of the user executing \fBcowpoke\fP (or to a username that is
+specified in your SSH configuration for \fBBUILDD_HOST\fR), and may be overridden by the
+\fB\-\-buildd\-user\fP command line option.
+.TP
+.B BUILDD_ARCH
+The Debian architecture(s) to build for.  This must match the \fBDEB_BUILD_ARCH\fP
+of the build chroot being used.  It defaults to the local machine architecture where
+\fBcowpoke\fP is executed, and may be overridden by the \fB\-\-arch\fP command line
+option.  A (quoted) space separated list of architectures may be used here to build
+for all of them in a single pass.
+.TP
+.B BUILDD_DIST
+The Debian distribution(s) to build for.  A (quoted) space separated list of
+distributions may be used to build for all of them in a single pass.  This may
+be overridden by the \fB\-\-dist\fP command line option.
+
+.TP
+.B INCOMING_DIR
+The directory path on the build machine where the source package will initially
+be placed.  This must be writable by the \fBBUILDD_USER\fP.
+.TP
+.B PBUILDER_BASE
+The filesystem root for all pbuilder CoW and result files.  \fIArch\fP and \fIdist\fP
+specific subdirectories will normally be created under this.  The apt cache
+and temporary build directory will also be located under this path.
+
+.TP
+.B SIGN_KEYID
+If this option is set, it is expected to contain the gpg key ID to pass to
+\fBdebsign\fP(1) if the packages are to be remotely signed.  You will be prompted
+to confirm whether you wish to sign the packages after all builds are complete.
+If this option is unset or an empty string, no attempt to sign packages will be
+made.  It may be overridden on an \fIarch\fP and \fIdist\fP specific basis using
+the
+.IB arch _ dist _SIGN_KEYID
+option described below, or per-invocation with the \fB\-\-sign\fP command line
+option.
+
+.TP
+.B UPLOAD_QUEUE
+If this option is set, it is expected to contain a 'host' specification for
+\fBdput\fP(1) which will be used to upload them after they are signed.  You will
+be prompted to confirm whether you wish to upload the packages after they are
+signed.  If this option is unset or an empty string, no attempt to upload packages
+will be made.  If \fBSIGN_KEYID\fP is not set, this option will be ignored entirely.
+It may be overridden on an \fIarch\fP and \fIdist\fP specific basis using the
+.IB arch _ dist _UPLOAD_QUEUE
+option described below, or per-invocation with the \fB\-\-upload\fP command line
+option.
+
+
+.TP
+.B BUILDD_ROOTCMD
+The command to use to gain root privileges on the remote build machine.  If
+unset the default is \fBsudo\fP(8).  This is only required to invoke \fBcowbuilder\fR
+and allow it to enter its chroot, so you may restrict this user to only being
+able to run that command with escalated privileges.  Something like this in
+sudoers will enable invoking \fBcowbuilder\fR without an additional password entry
+required:
+.TP
+.B " "
+.RS 1.5i
+youruser ALL = NOPASSWD: /usr/sbin/cowbuilder
+.RE
+.TP
+.B " "
+Alternatively you could use SSH with a forwarded key, or whatever other
+mechanism suits your local access policy.  Using \fBsu \-c\fR isn't really
+suitable here due to its quoting requirements being somewhat different to
+the rest.
+
+.TP
+.B DEBOOTSTRAP
+The utility to use when creating a new build root.  Alternatives are
+.BR debootstrap " or " cdebootstrap .
+
+.TP
+.B RETURN_DIR
+If set, package files resulting from the build will be copied to the path
+(local or remote) that this is set to, after the build completes.  The path
+must exist, it will not be created.  This option is unset by default and can
+be overridden with \fB\-\-return\fR or \fB\-\-no-return\fR.
+
+
+.SS Arch and dist specific options
+These are variables of the form: $arch_$dist\fB_VAR\fR which apply only for a
+particular target arch/dist build.
+
+.TP
+.IB arch _ dist _RESULT_DIR
+The directory path on the build machine where the resulting packages (source and
+binary) will be found, and where older versions of the package that were built
+previously may be found.  If any such older packages exist, \fBdebdiff\fP will
+be used to compare the new package with the previous version after the build is
+complete, and the result will be included in the build log.  Files in it must be
+readable by the \fBBUILDD_USER\fP for sanity checking with \fBlintian\fP(1) and
+\fBdebdiff\fP(1), and for upload with \fBdput\fP(1).  If this option is not
+specified for some arch and dist combination then it will default to
+.I $PBUILDER_BASE/$arch/$dist/result
+
+.TP
+.IB arch _ dist _BASE_PATH
+The directory where the CoW master files are to be found (or created if the
+\fB\-\-create\fP command line option was passed).  If this option is not specified
+for some arch or dist then it will default to
+.I $PBUILDER_BASE/$arch/$dist/base.cow
+
+.TP
+.IB arch _ dist _BASE_DIST
+The code name to pass as the \fB\-\-distribution\fP option for cowbuilder instead
+of \fIdist\fP.  This is necessary when \fIdist\fP is a locally significant name
+assigned to some specially configured build chroot, such as 'wheezy_backports',
+and not the formal suite name of a distro release known to debootstrap.  This
+option cannot be overridden on the command line, since it would rarely, if ever,
+make any sense to change it for individual invocations of \fBcowpoke\fP. If this
+option is not specified for an arch and dist combination then it will default to
+.IR dist .
+
+.TP
+.IB arch _ dist _CREATE_OPTS
+A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
+when this chroot is created for the first time (using the \fB\-\-create\fP option).
+This is useful when options like \fB\-\-othermirror\fP are wanted to create
+specialised chroot configurations such as 'wheezy_backports'.  By default this
+is unset.  All values set in it will be overridden if the \fB\-\-create\-opts\fP
+option is passed on the command line.
+
+Each element in this array corresponds to a single argument (in the ARGV sense)
+that will be passed to cowbuilder.  This ensures that arguments which may contain
+whitespace or have strange quoting requirements or other special characters will
+not be mangled before they get to cowbuilder.
+
+Bash arrays are initialised using the following form:
+
+    OPTS=( "arg1" "arg 2" "\-\-option" "value" "\-\-opt=val" "etc. etc." )
+
+.TP
+.IB arch _ dist _UPDATE_OPTS
+A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
+each time the base of this chroot is updated.  It behaves similarly to the
+\fBCREATE_OPTS\fP option above, except for acting when the chroot is updated.
+
+.TP
+.IB arch _ dist _BUILD_OPTS
+A bash array containing additional options to pass verbatim to \fBcowbuilder\fP
+each time a package build is performed in this chroot.  This is useful when you
+want to use some option like \fB\-\-twice\fP which cowpoke does not directly
+need to care about.  It otherwise behaves similarly to \fBUPDATE_OPTS\fP above
+except that it acts during the build phase of \fBcowbuilder\fP.
+
+.TP
+.IB arch _ dist _SIGN_KEYID
+An optional arch and dist specific override for the global \fBSIGN_KEYID\fP
+option.
+
+.TP
+.IB arch _ dist _UPLOAD_QUEUE
+An optional arch and dist specific override for the global \fBUPLOAD_QUEUE\fP
+option.
+
+
+.SH CONFIGURATION FILES
+.TP
+.I /etc/cowpoke.conf
+Global configuration options.  Will override hardcoded defaults.
+.TP
+.I ~/.cowpoke
+Per\-user configuration options.  Will override any global configuration.
+.TP
+.I .cowpoke
+Per\-project configuration options.  Will override any per-user or global
+configuration if \fBcowpoke\fP is called from the directory where they exist.
+
+If the environment variable \fBCOWPOKE_CONF\fP is set, it specifies an additional
+configuration file which will override all of those above.  Options specified
+explicitly on the command line override all configuration files.
+
+
+.SH COWBUILDER CONFIGURATION
+There is nothing particularly special required to configure a \fBcowbuilder\fR instance
+for use with \fBcowpoke\fP.  Simply create them in the flavour you require with
+`\fBcowbuilder \-\-create\fP` according to the \fBcowbuilder\fR documentation, then
+configure \fBcowpoke\fP with the user, arch, and path information required to
+access it, on the machines you wish to invoke it from (or alternatively configure
+\fBcowpoke\fP with the path, arch and distribution information and pass the
+\fB\-\-create\fP option to it on the first invocation).  The build host running
+\fBcowbuilder\fR does not require \fBcowpoke\fP installed locally.
+
+The build machine should have the \fBlintian\fP and \fBdevscripts\fR packages
+installed for post-build sanity checking.  Upon completion, the build log and
+the results of automated checks will be recorded in the \fBINCOMING_DIR\fP.
+If you wish to upload signed packages the build machine will also need
+\fBdput\fP(1) installed and configured to use the '\fIhost\fP' alias specified
+by \fBUPLOAD_QUEUE\fP.  If \fBrsync\fP(1) is available on both the local and
+build machine, then it will be used to transfer the source package (this may
+save on some transfers of the \fIorig.tar.*\fP when building subsequent Debian
+revisions).
+
+The user executing \fBcowpoke\fP must have SSH access to the build machine as
+the \fBBUILDD_USER\fP.  That user must be able to invoke \fBcowbuilder\fR as root by
+using the \fBBUILDD_ROOTCMD\fP.  Signing keys are not required to be installed
+on the build machine (and will be ignored there if they are).  If the package
+is signed, keys will be expected on the machine that executes \fBcowpoke\fP.
+
+When \fBcowpoke\fP is invoked, it will first attempt to update the \fBcowbuilder\fR
+image if that has not already been done on the same day.  This is checked by
+the presence or absence of a \fIcowbuilder-$arch-$dist-update-log-$date\fP file
+in the \fBINCOMING_DIR\fP.  You may move, remove, or touch this file if you wish
+the image to be updated more or less often than that.  Its contents log the
+output of \fBcowbuilder\fR during the update (or creation) of the build root.
+
+
+.SH NOTES
+Since \fBcowbuilder\fP creates a chroot, and to do that you need root, \fBcowpoke\fP
+also requires some degree of root access.  So all the horrible things that can
+go wrong with that may well one day rain down upon you.  \fBcowbuilder\fR has been
+known to accidentally wipe out bind-mounted filesystems outside the chroot, and
+worse than that can easily happen.  So be careful, keep good backups of things
+you don't want to lose on your build machine, and use \fBcowpoke\fP to keep all
+that on a machine that isn't your bleeding edge dev box with your last few hours
+of uncommitted work.
+
+.SH SEE ALSO
+.BR cowbuilder (1),
+.BR pbuilder (1),
+.BR ssh-agent (1),
+.BR sudoers (5)
+
+.SH AUTHOR
+.B cowpoke
+was written by Ron <\fIron@debian.org\fP>.
+