diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/manpages/gbp-buildpackage.sgml | 482 |
1 files changed, 306 insertions, 176 deletions
diff --git a/docs/manpages/gbp-buildpackage.sgml b/docs/manpages/gbp-buildpackage.sgml index f382634f..d099e415 100644 --- a/docs/manpages/gbp-buildpackage.sgml +++ b/docs/manpages/gbp-buildpackage.sgml @@ -8,8 +8,7 @@ &dhsurname; </author> </refentryinfo> - <refmeta> - <refentrytitle>gbp-buildpackage</refentrytitle> + <refmeta><refentrytitle>gbp-buildpackage</refentrytitle> &dhsection; </refmeta> <refnamediv> @@ -66,147 +65,203 @@ <refsect1> <title>DESCRIPTION</title> <para> - &gbp-buildpackage; is used to build Debian source and .deb packages from a &git; repository. + &gbp-buildpackage; is used to build Debian source and .deb packages from + a &git; repository. </para> <para> - &gbp-buildpackage; will, in order: - </para> + &gbp-buildpackage; will, in order: + </para> <itemizedlist> - <listitem><para>Verify that it is being executed from the - proper location.</para> - </listitem> - <listitem><para>Verify that the repository doesn't contain any - uncommitted source changes.</para> - </listitem> - <listitem><para>Verify that it is being executed from the - correct branch.</para> - </listitem> - <listitem><para> - (Optionally) export the source tree to a separate build area - </para></listitem> - <listitem><para>Build an orig tarball if it doesn't exist.</para> - </listitem> - <listitem><para>Call <application>debuild</application>(1) - (or the application specified via <option>--git-builder</option>) - with arguments instructing it to ignore &git; meta-data in - the diff.gz, passing along all arguments given to - &gbp-buildpackage; that don't start with --git-. - </para> - </listitem> - <listitem><para> - (Optionally) tag the tree after a successful build - </para></listitem> - <listitem><para> - (Optionally) call a post build hook - e.g. to run &lintian; - </para></listitem> - <listitem><para> - (Optionally) call a post tag hook - e.g. to push the results to a remote - repository after creating the tag - </para></listitem> + <listitem> + <para> + Verify that it is being executed from the proper location. + </para> + </listitem> + <listitem> + <para> + Verify that the repository doesn't contain any uncommitted source + changes. + </para> + </listitem> + <listitem> + <para> + Verify that it is being executed from the correct branch. + </para> + </listitem> + <listitem> + <para> + (Optionally) export the source tree to a separate build area + </para> + </listitem> + <listitem> + <para> + Build an orig tarball if it doesn't exist. + </para> + </listitem> + <listitem> + <para> + Call <application>debuild</application>(1) (or the application + specified via <option>--git-builder</option>) with arguments + instructing it to ignore &git; meta-data in the diff.gz, passing along + all arguments given to &gbp-buildpackage; that don't start with --git-. + </para> + </listitem> + <listitem> + <para> + (Optionally) tag the tree after a successful build + </para> + </listitem> + <listitem> + <para> + (Optionally) call a post build hook - e.g. to run &lintian; + </para> + </listitem> + <listitem> + <para> + (Optionally) call a post tag hook - e.g. to push the results to a + remote repository after creating the tag + </para> + </listitem> </itemizedlist> </refsect1> <refsect1> <title>OPTIONS</title> - <variablelist> <varlistentry> <term><option>--git-[no-]ignore-new</option> </term> <listitem> - <para>Don't abort if there are uncommitted changes in the source tree - or the current branch doesn't match the - <replaceable>debian-branch</replaceable>.</para> + <para> + Don't abort if there are uncommitted changes in the source tree or + the current branch doesn't match the + <replaceable>debian-branch</replaceable>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-tag</option> </term> <listitem> - <para>Add a git tag after a successful build.</para> + <para> + Add a git tag after a successful build. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option></term> + <term><option>--git-builder=<replaceable>BUILD_CMD</replaceable></option> + </term> <listitem> - <para>Use <replaceable>BUILD_CMD</replaceable> instead of <command>debuild -i -I</command></para> + <para> + Use <replaceable>BUILD_CMD</replaceable> instead of + <command>debuild -i -I</command> + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-cleaner=<replaceable>CLEAN_CMD</replaceable></option></term> + <term><option>--git-cleaner=<replaceable>CLEAN_CMD</replaceable></option> + </term> <listitem> - <para>Use <replaceable>CLEAN_CMD</replaceable> instead of <command>debuild clean</command></para> + <para> + Use <replaceable>CLEAN_CMD</replaceable> instead of + <command>debuild clean</command> + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-pbuilder</option></term> + <term><option>--git-pbuilder</option> + </term> <listitem> - <para>Build package using <command>git-pbuilder</command>. Note that - this overwrites any <option>--git-builder</option> and - <option>--git-cleaner</option> options.</para> + <para> + Build package using <command>git-pbuilder</command>. Note that this + overwrites any <option>--git-builder</option> and + <option>--git-cleaner</option> options. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-qemubuilder</option></term> + <term><option>--git-qemubuilder</option> + </term> <listitem> - <para>Build package using <command>git-pbuilder</command> with - <command>qemubuilder</command>. Note that this overwrites any - <option>--git-builder</option> and <option>--git-cleaner</option> - options.</para> + <para> + Build package using <command>git-pbuilder</command> with + <command>qemubuilder</command>. Note that this overwrites any + <option>--git-builder</option> and <option>--git-cleaner</option> + options. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-dist=<replaceable>DIST</replaceable></option></term> + <term><option>--git-dist=<replaceable>DIST</replaceable></option> + </term> <listitem> - <para>Build for distribution <replaceable>DIST</replaceable> when - using <command>--git-pbuilder</command>. If unset build for the - unstable distribution.</para> + <para> + Build for distribution <replaceable>DIST</replaceable> when using + <command>--git-pbuilder</command>. If unset build for the unstable + distribution. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-arch=<replaceable>ARCH</replaceable></option></term> + <term><option>--git-arch=<replaceable>ARCH</replaceable></option> + </term> <listitem> - <para>Build for architecture <replaceable>ARCH</replaceable> when - using <command>--git-pbuilder</command>. If unset no architecture is - passed to <command>git-pbuilder</command>.</para> + <para> + Build for architecture <replaceable>ARCH</replaceable> when using + <command>--git-pbuilder</command>. If unset no architecture is passed + to <command>git-pbuilder</command>. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-pbuilder-autoconf</option></term> + <term><option>--git-pbuilder-autoconf</option> + </term> <listitem> - <para>Whether to try to autoconfigure - <command>git-pbuilder</command> or to rely on the settings in - .pbuilderrc. See the <command>git-pbuilder</command> - manpage for details.</para></listitem> + <para> + Whether to try to autoconfigure <command>git-pbuilder</command> or to + rely on the settings in .pbuilderrc. See the + <command>git-pbuilder</command> manpage for details. + </para> + </listitem> </varlistentry> <varlistentry> - <term><option>--git-pbuilder-options</option></term> + <term><option>--git-pbuilder-options</option> + </term> <listitem> - <para>Options to pass to pbuilder</para> + <para> + Options to pass to pbuilder + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-verbose</option> </term> <listitem> - <para>verbose execution</para> + <para> + verbose execution + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-color=</option><replaceable>[auto|on|off]</replaceable> </term> <listitem> - <para>Whether to use colored output.</para> + <para> + Whether to use colored output. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-notify=</option><replaceable>[auto|on|off]</replaceable> </term> <listitem> - <para>Whether to send a desktop notification after the build.</para> + <para> + Whether to send a desktop notification after the build. + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable></term> + <term><option>--git-color-scheme</option>=<replaceable>COLOR_SCHEME</replaceable> + </term> <listitem> <para> Colors to use in output (when color is enabled). The format for @@ -223,36 +278,44 @@ <term><option>--git-upstream-branch</option>=<replaceable>branch_name</replaceable> </term> <listitem> - <para>Branch to build the orig tarball from if <option>--git-upstream-tree</option> - is set to <replaceable>BRANCH</replaceable>. Default is - <replaceable>upstream</replaceable>.</para> + <para> + Branch to build the orig tarball from if + <option>--git-upstream-tree</option> is set to + <replaceable>BRANCH</replaceable>. Default is + <replaceable>upstream</replaceable>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-debian-branch</option>=<replaceable>branch_name</replaceable> </term> <listitem> - <para>If you're not on this branch when invoking &gbp-buildpackage; - it will fail. Default is <replaceable>master</replaceable>. This is - done to make sure you don't accidentally release from a topic branch. - Not being on this branch will be ignored when using - <option>--git-ignore-new</option>. - </para> + <para> + If you're not on this branch when invoking &gbp-buildpackage; it will + fail. Default is <replaceable>master</replaceable>. This is done to + make sure you don't accidentally release from a topic branch. Not + being on this branch will be ignored when using + <option>--git-ignore-new</option>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-ignore-branch</option> </term> <listitem> - <para>Don't check if the current branch matches - <replaceable>debian-branch</replaceable>.</para> + <para> + Don't check if the current branch matches + <replaceable>debian-branch</replaceable>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-[no-]sign-tags</option> </term> <listitem> - <para>GPG sign all created tags</para> + <para> + GPG sign all created tags + </para> </listitem> </varlistentry> <varlistentry> @@ -268,218 +331,283 @@ <term><option>--git-keyid=</option><replaceable>gpg-keyid</replaceable> </term> <listitem> - <para>use this keyid for gpg signing tags</para> + <para> + use this keyid for gpg signing tags + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-posttag=</option><replaceable>command</replaceable> </term> <listitem> - <para>excecute <replaceable>command</replaceable> after tagging a new - version.</para><para>Exported environment variables are: - <envar>GBP_TAG</envar> (the name of the generated tag), - <envar>GBP_BRANCH</envar> (the branch the package was build from) and - <envar>GBP_SHA1</envar> (the sha1 of the commit the tag was created - at).</para> + <para> + excecute <replaceable>command</replaceable> after tagging a new + version. + </para> + <para> + Exported environment variables are: <envar>GBP_TAG</envar> (the name + of the generated tag), <envar>GBP_BRANCH</envar> (the branch the + package was build from) and <envar>GBP_SHA1</envar> (the sha1 of the + commit the tag was created at). + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-postbuild=</option><replaceable>command</replaceable> </term> <listitem> - <para>execute <replaceable>command</replaceable> after successful - build.</para><para> Exported environment variables are: - <envar>GBP_CHANGES_FILE</envar> (the name of the generated changes - file), <envar>GBP_BUILD_DIR</envar> (the build dir).</para> + <para> + execute <replaceable>command</replaceable> after successful + build. + </para> + <para> + Exported environment variables are: <envar>GBP_CHANGES_FILE</envar> + (the name of the generated changes file), + <envar>GBP_BUILD_DIR</envar> (the build dir). + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-postexport=</option><replaceable>command</replaceable> </term> <listitem> - <para>execute <replaceable>command</replaceable> after exporting the source - tree - valid only if --git-export-dir has been specified.</para> - <para> Exported environment variables are: - <envar>GBP_GIT_DIR</envar> (the repository the package is being built - from), <envar>GBP_TMP_DIR</envar> (the temporary directory where the - sources have been initially exported).</para> + <para> + execute <replaceable>command</replaceable> after exporting the source + tree - valid only if --git-export-dir has been specified. + </para> + <para> + Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the + repository the package is being built from), + <envar>GBP_TMP_DIR</envar> (the temporary directory where the sources + have been initially exported). + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-prebuild=</option><replaceable>command</replaceable> </term> <listitem> - <para>execute <replaceable>command</replaceable> from the build - directory before calling <application>debuild</application> - or the application specified via <option>--git-builder</option>.</para> - <para>Exported environment variables are: - <envar>GBP_GIT_DIR</envar> (the repository the package is being built from), - <envar>GBP_BUILD_DIR</envar> (the build dir).</para> + <para> + execute <replaceable>command</replaceable> from the build directory + before calling <application>debuild</application> or the application + specified via <option>--git-builder</option>. + </para> + <para> + Exported environment variables are: <envar>GBP_GIT_DIR</envar> (the + repository the package is being built from), + <envar>GBP_BUILD_DIR</envar> (the build dir). + </para> </listitem> </varlistentry> <varlistentry> - <term><option>--git-[no-]hooks</option></term> + <term><option>--git-[no-]hooks</option> + </term> <listitem> - <para>Enable running all (cleaner, postexport, prebuild, postbuild, - and posttag) hooks. Note: the <option>--git-builder</option> command is - not affected by this option.</para> + <para> + Enable running all (cleaner, postexport, prebuild, postbuild, and + posttag) hooks. Note: the <option>--git-builder</option> command is + not affected by this option. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-debian-tag=</option><replaceable>tag-format</replaceable> </term> <listitem> - <para>use this tag format when tagging Debian versions, - default is <replaceable>debian/%(version)s</replaceable></para> + <para> + use this tag format when tagging Debian versions, default is + <replaceable>debian/%(version)s</replaceable> + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-upstream-tag=</option><replaceable>tag-format</replaceable> </term> <listitem> - <para>use this tag format when looking for tags of upstream versions, - default is <replaceable>upstream/%(version)s</replaceable>.</para> + <para> + use this tag format when looking for tags of upstream versions, + default is <replaceable>upstream/%(version)s</replaceable>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-force-create</option> </term> <listitem> - <para>Force creation of an orig tarball (overwriting a pre-existing one if present)</para> + <para> + Force creation of an orig tarball (overwriting a pre-existing one if + present) + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-no-create-orig</option> </term> <listitem> - <para>Don't try to create any orig tarball</para> + <para> + Don't try to create any orig tarball + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-overlay</option> </term> <listitem> - <para>Extract orig tarball when using export-dir option (analog to mergeWithUpstream in svn-bp)</para> + <para> + Extract orig tarball when using export-dir option (analog to + mergeWithUpstream in svn-bp) + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-export-dir=</option><replaceable>directory</replaceable> </term> <listitem> - <para>Export the current branch head (or the treeish object given via - <option>--git-export</option> to <replaceable>directory</replaceable> - before building.</para> + <para> + Export the current branch head (or the treeish object given via + <option>--git-export</option> to <replaceable>directory</replaceable> + before building. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-export=</option><replaceable>treeish</replaceable> </term> - <listitem> - <para>Instead of exporting the current branch head, export the - treeish object <replaceable>treeish</replaceable>. The special name - <replaceable>INDEX</replaceable> exports the current index whereas - the special name <replaceable>WC</replaceable> exports the current working - copy as is.</para> + <listitem> + <para> + Instead of exporting the current branch head, export the treeish + object <replaceable>treeish</replaceable>. The special name + <replaceable>INDEX</replaceable> exports the current index whereas + the special name <replaceable>WC</replaceable> exports the current + working copy as is. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-upstream-tree=</option><replaceable>[tag|branch]</replaceable> </term> <listitem> - <para>How to find the upstream sources used to generate the tarball. - <replaceable>TAG</replaceable> looks at a tag corresponding to the - version in the changelog. <replaceable>BRANCH</replaceable> looks at - the upstream branch given via the <option>--git-upstream-branch</option> - option. Other values are interpreted as treeishs. - </para><para> - This doesn't have any effect if <option>--git-pristine-tar</option> - is being used. - </para> + <para> + How to find the upstream sources used to generate the tarball. + <replaceable>TAG</replaceable> looks at a tag corresponding to the + version in the changelog. <replaceable>BRANCH</replaceable> looks at + the upstream branch given via the + <option>--git-upstream-branch</option> option. Other values are + interpreted as treeishs. + </para> + <para> + This doesn't have any effect if <option>--git-pristine-tar</option> + is being used. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-tarball-dir=</option><replaceable>directory</replaceable> </term> <listitem> - <para>Search for original tarballs in <replaceable>directory</replaceable> instead of generating them</para> + <para> + Search for original tarballs in <replaceable>directory</replaceable> + instead of generating them + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-compression=</option><replaceable>type</replaceable> </term> <listitem> - <para>Specifies the upstream tarball compression type. This will be - used to locate and build the upstream tarball if necessary. The - default is <replaceable>auto</replaceable> which derives the - compression type from the pristine-tar branch if available and falls - back to gzip otherwise. Other options are - <replaceable>gzip</replaceable>, <replaceable>bzip2</replaceable>, - <replaceable>lzma</replaceable> and <replaceable>xz</replaceable>. - </para> + <para> + Specifies the upstream tarball compression type. This will be used to + locate and build the upstream tarball if necessary. The default is + <replaceable>auto</replaceable> which derives the compression type + from the pristine-tar branch if available and falls back to gzip + otherwise. Other options are <replaceable>gzip</replaceable>, + <replaceable>bzip2</replaceable>, <replaceable>lzma</replaceable> and + <replaceable>xz</replaceable>. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-compression-level=</option><replaceable>level</replaceable> </term> <listitem> - <para>Specifies the upstream tarball compression level if an upstream tarball needs to be built.</para> + <para> + Specifies the upstream tarball compression level if an upstream + tarball needs to be built. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git[-no]-purge</option> </term> <listitem> - <para>Purge (remove) temporary build directory after build</para> + <para> + Purge (remove) temporary build directory after build + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-dont-purge</option> </term> <listitem> - <para>Deprecated, use --git-no-purge instead.</para> + <para> + Deprecated, use --git-no-purge instead. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-tag-only</option> </term> <listitem> - <para>don't build, only tag and run post-tag hooks</para> + <para> + don't build, only tag and run post-tag hooks + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-retag</option> </term> <listitem> - <para>don't fail tag operations if a tag with the same version - already exists</para> + <para> + don't fail tag operations if a tag with the same version already + exists + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-pristine-tar</option> </term> <listitem> - <para>Use pristine-tar when generating the upstream tarball if it doesn't exist.</para> + <para> + Use pristine-tar when generating the upstream tarball if it doesn't + exist. + </para> </listitem> </varlistentry> <varlistentry> <term><option>--git-pristine-tar-commit</option> </term> <listitem> - <para>Commit the pristine-tar delta to the pristine-tar branch if a new tarball was - generated and the pristine-tar data isn't already there.</para> + <para> + Commit the pristine-tar delta to the pristine-tar branch if a new + tarball was generated and the pristine-tar data isn't already there. + </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>EXAMPLES</title> - <para>Build a Debian package using &git-pbuilder; which in turn invokes &cowbuildercmd;. - Instruct cowbuilder to build within a Wheezy chroot for i386.</para> + <para> + Build a Debian package using &git-pbuilder; which in turn invokes + &cowbuildercmd;. Instruct cowbuilder to build within a Wheezy chroot for + i386. + </para> <screen> &gbp-buildpackage; --git-pbuilder --git-arch=i386 --git-dist=wheezy </screen> <para> - Note that the above needs a &cowbuildercmd; chroot already. This can be created using: + Note that the above needs a &cowbuildercmd; chroot already. This can be + created using: </para> <screen> DIST=wheezy ARCH=i386 &git-pbuilder; create @@ -487,31 +615,33 @@ </refsect1> <refsect1> &man.gbp.config-files; - <para>All options in the config files are specified without the 'git-' prefix.</para> + <para> + All options in the config files are specified without the 'git-' prefix. + </para> </refsect1> <refsect1> <title>SEE ALSO</title> <para> - <xref linkend="man.gbp.import.dsc">, - <xref linkend="man.gbp.import.dscs">, - <xref linkend="man.gbp.import.orig">, - <xref linkend="man.gbp.dch">, - <citerefentry> - <refentrytitle>git-pbuilder</refentrytitle> - <manvolnum>1</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>cowbuilder</refentrytitle> - <manvolnum>8</manvolnum> - </citerefentry>, - <xref linkend="man.gbp.conf">, - &man.seealso.common; + <xref linkend="man.gbp.import.dsc">, + <xref linkend="man.gbp.import.dscs">, + <xref linkend="man.gbp.import.orig">, + <xref linkend="man.gbp.dch">, + <citerefentry> + <refentrytitle>git-pbuilder</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>cowbuilder</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, + <xref linkend="man.gbp.conf">, + &man.seealso.common; </para> </refsect1> <refsect1> <title>AUTHOR</title> - - <para>&dhusername; &dhemail;</para> - + <para> + &dhusername; &dhemail; + </para> </refsect1> </refentry> |