From e7bbd6523fbb68ce69be1be7ebbd231ab9f6ea36 Mon Sep 17 00:00:00 2001 From: Guido Günther Date: Fri, 4 Aug 2017 19:44:48 -0300 Subject: gbp-buildpackage: Group manpage options Closes: #824801 --- docs/manpages/gbp-buildpackage.sgml | 1213 ++++++++++++++++++----------------- 1 file changed, 638 insertions(+), 575 deletions(-) diff --git a/docs/manpages/gbp-buildpackage.sgml b/docs/manpages/gbp-buildpackage.sgml index 63b285ef..8a9c33ab 100644 --- a/docs/manpages/gbp-buildpackage.sgml +++ b/docs/manpages/gbp-buildpackage.sgml @@ -44,8 +44,8 @@ COMMAND tag-format - tag-format tag-msg-format + tag-format [TAG|BRANCH|TREEISH] @@ -58,7 +58,6 @@ - @@ -67,27 +66,27 @@ DESCRIPTION - &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. - &gbp-buildpackage; will, in order: + &gbp-buildpackage; will, in order: - Verify that it is being executed from the proper location. + Verify that it is being executed from the proper location. - Verify that the repository doesn't contain any uncommitted source - changes. + Verify that the repository doesn't contain any uncommitted source + changes. - Verify that it is being executed from the correct branch. + Verify that it is being executed from the correct branch. @@ -98,12 +97,12 @@ - (Optionally) export the source tree to a separate build area. + (Optionally) export the source tree to a separate build area. - Build an orig tarball if it doesn't exist. Optionally using &pristine-tar;. + Build an orig tarball if it doesn't exist. Optionally using &pristine-tar;. @@ -122,18 +121,18 @@ - (Optionally) tag the current commit after a successful build. + (Optionally) tag the current commit after a successful build. - (Optionally) call a post build hook - e.g. to run &lintian;. + (Optionally) call a post build hook - e.g. to run &lintian;. - (Optionally) call a post tag hook - e.g. to push the results to a - remote repository after creating the tag. + (Optionally) call a post tag hook - e.g. to push the results to a + remote repository after creating the tag. @@ -145,561 +144,621 @@ distinguish options for &gbp-buildpackage; from options passed to the BUILD_CMD: - - - - - - - Don't abort if there are uncommitted changes in the source tree or - the current branch doesn't match the - DEBIAN-BRANCH. - - - - - - - - - Add a git tag after a successful build. It tags the - currently checked out commmit except when you're on a - patch-queue branch. In that case the corresponding debian - branch is tagged. - - - This is a command line only option that cannot be - specified via &gbp.conf;. - - - - - - - - - Use BUILD_CMD instead of - debuild -i -I. - - - - - - - - - Use CLEAN_CMD to clean the - source tree before the build. The default - is /bin/true. - - - - - - - - - Build package using git-pbuilder (which - uses cowbuilder by default). Note that this overwrites - any and - options. - - - - - - - - - Build package using git-pbuilder with - qemubuilder. Note that this overwrites any - and - options. - - - - - - - - - Build for distribution DIST - when using &git-pbuilder; (either - via , - or the corresponding configuration file options). If - unset build for the unstable distribution. The special - value DEP14 will set the distribution to - build for from the branch name. I.e. if you're starting - the build from a branch named - debian/wheezy-backports the - distribution is set - to wheezy-backports. If the - branch is named downstream/sid - the distribution would be set - to downstream_sid. - - - - - - - - - Build for architecture ARCH - when using &git-pbuilder; (either - via , - or the corresponding configuration file options). If - unset no architecture is passed - to git-pbuilder. - - - - - - - - - Whether to try to autoconfigure &git-pbuilder; or to rely on - the settings in .pbuilderrc. See the &git-pbuilder; manpage - for details. Only takes effect when using &git-pbuilder; - (either via , - or the corresponding configuration file options). - - - - - - - - - Options to pass to pbuilder when building via &git-pbuilder; (either - via , - or the corresponding configuration file options). - - - - - - - - - verbose execution - - - - - [auto|on|off] - - - - Whether to use colored output. - - - - - [auto|on|off] - - - - Whether to send a desktop notification after the build. - - - - - =COLOR_SCHEME - - - - Colors to use in output (when color is enabled). The format for - COLOR_SCHEME is - '<debug>:<info>:<warning>:<error>'. - Numerical values and color names are accepted, empty fields imply - the default color. For example --git-color-scheme='cyan:34::' would - show debug messages in cyan, info messages in blue and other messages - in default (i.e. warning and error messages in red). - - - - - =BRANCH_NAME - - - - Branch to build the orig tarball from if - is set to - BRANCH. Default is - upstream. - - - - - =BRANCH_NAME - - - - If you're not on this branch when invoking &gbp-buildpackage; it will - fail. Default is master. 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 - . - - - - - - - - - Don't check if the current branch matches - DEBIAN-BRANCH. - - - - - - - - - GPG sign all created tags. - - - - - - - - - Include git submodules in the orig tarball. - - - - - GPG-KEYID - - - - Use this keyid for gpg signing tags. - - - - - COMMAND - - - - Execute COMMAND after tagging a new - version. - - - Exported environment variables are: GBP_TAG (the name - of the generated tag), GBP_BRANCH (the branch the - package was build from) and GBP_SHA1 (the sha1 of the - commit the tag was created at). - - - - - COMMAND - - - - Execute COMMAND after successful - build. - - - Exported environment variables are: GBP_CHANGES_FILE - (the name of the generated changes file), - GBP_BUILD_DIR (the build dir). - - - - - COMMAND - - - - Execute COMMAND after exporting the source - tree - valid only if --git-export-dir has been specified. - - - Exported environment variables are: GBP_GIT_DIR (the - repository the package is being built from), - GBP_TMP_DIR (the temporary directory where the sources - have been initially exported). - - - - - COMMAND - - - - Execute COMMAND from the build directory - before calling debuild or the application - specified via . - - - Exported environment variables are: GBP_GIT_DIR (the - repository the package is being built from), - GBP_BUILD_DIR (the build dir). - - - - - - - - - Enable running all (cleaner, postexport, prebuild, postbuild, and - posttag) hooks. Note: the command is - not affected by this option. - - - - - TAG-FORMAT - - - - Use this tag format when tagging &debian; versions, default is - debian/%(version)s. - - - - - TAG-FORMAT - - - - Use this tag format when looking for tags of upstream versions, - default is upstream/%(version)s. - - - - - tag-msg-format - - - Use this tag message format when signing &debian; versions, - default is %(pkg)s Debian release %(version)s - - - - - - - - Force creation of an orig tarball (overwriting a pre-existing one if - present). - - - - - - - - - Don't try to create any orig tarball. - - - - - - - - - Extract orig tarball from when - using the option (in analogy to - mergeWithUpstream in svn-bp). Also remove debian/ if - contained in the upstream tarball in case of 2.0 and 3.0 - source formats. - - - - - DIRECTORY - - - - Export the current branch head (or the treeish object given via - to DIRECTORY - before building. - - - - - TREEISH - - - - Instead of exporting the current branch head, export the treeish - object TREEISH. The special name - INDEX exports the current index whereas - the special name WC exports the current - working copy as is. - - - Note that using WC enables the - - and options as well - since when exporting the working copy there's no point in - enforcing any branch or modification checks. - - - - - [BRANCH|SLOPPY|TAG|TREEISH] - - - - How to find the upstream sources used to generate the tarball. - TAG (the default) looks at a tag corresponding to the - version in the changelog. BRANCH looks at - the upstream branch given via the - option. The SLOPPY - option looks at the debian branch given via - the and drops - the debian/ dir. - - - Other values are interpreted as treeishs. - - - This doesn't have any effect if - is being used. - - - - - DIRECTORY - - - - Search for original tarballs in DIRECTORY - instead of generating them. - - - - - TYPE - - - - Specifies the upstream tarball compression type. This will be used to - locate and build the upstream tarball if necessary. The default is - auto which derives the compression type - from the pristine-tar branch if available and falls back to gzip - otherwise. Other options are gzip, - bzip2, lzma and - xz. - - - - - LEVEL - - - - Specifies the upstream tarball compression level if an upstream - tarball needs to be built. - - - - - COMPONENT - - - - When generating tarballs create an additional original - tarball of directory COMPONENT - in the source tree. Using additional original tarballs is - a feature of the 3.0 (quilt) source format. See - the dpkg-source manpage for details. Note that the - --git-pristine-tar-commit - option is currently incompatible with this option. + + Upstream tarball creation options + When &gbp-buildpackage; doesn't find a suitable upstream + tarball it will create one either using &pristine-tar; + or git archive. These options determine how the tarball is created: + + + + + + + + Use pristine-tar when generating the upstream tarball if + it doesn't exist. If this mode is enabled + the , + options have no effect. + + + + + TAG-FORMAT + + + + Use this tag format when looking for tags of upstream + versions to build the upstream tarballs. Default + is upstream/%(version)s. This + must be set correctly if you don't want to pass any + other options. The default matches what + &gbp-import-orig; uses to create tags. + + + + + [BRANCH|SLOPPY|TAG|TREEISH] + + + + How to find the upstream sources used to generate the tarball. + TAG (the default) looks at a tag corresponding to the + version in the changelog. BRANCH looks at + the upstream branch given via the + option. The SLOPPY + option looks at the debian branch given via + the and drops + the debian/ dir. + + + Other values are interpreted as treeishs. + + + This doesn't have any effect if + is being used. + + + + + =BRANCH_NAME + + + + Branch to build the orig tarball from if + is set to + BRANCH. Default is + upstream. + + + + + DIRECTORY + + + + Search for upstream tarballs in DIRECTORY + instead of generating them. If a tarball is not found here it + will be generated nevertheless. + + + + + COMPONENT + + + + When generating tarballs create an additional upstream + tarball of directory COMPONENT + in the source tree. Using additional upstream tarballs is + a feature of the 3.0 (quilt) source format. See + the dpkg-source manpage for details. Note that the + --git-pristine-tar-commit + option is currently incompatible with this option. This is considered an experimental feature and might change incompatibly. - - - - - - - - Purge (remove) temporary build directory after build. - - - - - - - - - Deprecated, use --git-no-purge instead. This is a command line only option - that cannot be specified via &gbp.conf;. - - - - - - - - - Don't build, only tag and run post-tag hooks. This is a - command line only option that cannot be specified via - &gbp.conf;. - - - - - - - - - Don't fail tag operations if a tag with the same version - already exists. This is a command line only option that - cannot be specified via &gbp.conf;. - - - - - - - - - Use pristine-tar when generating the upstream tarball if it doesn't - exist. - - - - - - - - - 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. - - - - + + + + + + + + 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. + + + + + + + + + Force creation of an upstream tarball (overwriting a pre-existing one if + present). + + + + + + + + + Don't try to create any upstream tarballs. + + + + + + + + + Include &git; submodules in the orig tarball if present. + + + + + TYPE + + + + Specifies the upstream tarball compression type. This will be used to + locate and build the upstream tarball if necessary. The default is + auto which derives the compression type + from the pristine-tar branch if available and falls back to gzip + otherwise. Other options are gzip, + bzip2, lzma and + xz. + + + + + LEVEL + + + + Specifies the upstream tarball compression level if an upstream + tarball needs to be built. + + + + + + + Package build options + &gbp-buildpackage; can invoke different types of builders + to produce the source and binary packages. These options + determine which builder is invoked and how. + + + + + + + + Use BUILD_CMD instead of + debuild -i -I. If you want to use + &cowbuilder; or &pbuilder; see + the . + + + + + + + + + Use CLEAN_CMD to clean the + source tree before the build. The default + is /bin/true (no cleaning). + + + + + + + + + Build the package using git-pbuilder (which + uses cowbuilder by default). Note that this overwrites + any and + options. + + + + + + + + + Build package using git-pbuilder with + qemubuilder. Note that this overwrites any + and + options. + + + + + + + + + Build for distribution DIST + when using &git-pbuilder; (either + via , + or the corresponding configuration file options). If + unset build for the unstable distribution. The special + value DEP14 will set the distribution to + build for from the branch name. I.e. if you're starting + the build from a branch named + debian/wheezy-backports the + distribution is set + to wheezy-backports. If the + branch is named downstream/sid + the distribution is set + to downstream_sid. + + + + + + + + + Build for architecture ARCH + when using &git-pbuilder; (either + via , + or the corresponding configuration file options). If + unset no architecture is passed + to git-pbuilder. + + + + + + + + + Whether to try to autoconfigure &git-pbuilder; or to rely on + the settings in .pbuilderrc. See the &git-pbuilder; manpage + for details. Only takes effect when using &git-pbuilder; + (either via , + or the corresponding configuration file options). + + + + + + + + + Options to pass to pbuilder when building via &git-pbuilder; (either + via , + or the corresponding configuration file options). + + + + + [auto|on|off] + + + + Whether to send a desktop notification after the + build. This needs python3-notify2 installed. + + + + + + + Hook options + + Hooks allow to run arbitrary commands at different stages of the + build. These options configure what will be run: + + + + COMMAND + + + + Execute COMMAND after tagging a new + version. + + + Exported environment variables are: GBP_TAG (the name + of the generated tag), GBP_BRANCH (the branch the + package was build from) and GBP_SHA1 (the sha1 of the + commit the tag was created at). + + + + + COMMAND + + + + Execute COMMAND after successful + build. + + + Exported environment variables are: GBP_CHANGES_FILE + (the name of the generated changes file), + GBP_BUILD_DIR (the build dir). + + + + + COMMAND + + + + Execute COMMAND after exporting the source + tree - valid only if --git-export-dir has been specified. + + + Exported environment variables are: GBP_GIT_DIR (the + repository the package is being built from), + GBP_TMP_DIR (the temporary directory where the sources + have been initially exported). + + + + + COMMAND + + + + Execute COMMAND from the build directory + before calling debuild or the application + specified via . + + + Exported environment variables are: GBP_GIT_DIR (the + repository the package is being built from), + GBP_BUILD_DIR (the build dir). + + + + + + + + + Enable running all (cleaner, postexport, prebuild, postbuild, and + posttag) hooks. Note: the command is + not affected by this option. + + + + + + + Tagging options + + + + + + + Add a git tag after a successful build. It tags the + currently checked out commit except when you're on a + patch-queue branch. In that case the corresponding debian + branch is tagged. + + + This is a command line only option that cannot be + specified via &gbp.conf;. + + + + + + + + + GPG sign all created tags. + + + + + GPG-KEYID + + + + Use this keyid for gpg signing tags. + + + + + TAG-FORMAT + + + + Use this tag format when tagging &debian; versions, default is + debian/%(version)s. + + + + + tag-msg-format + + + Use this tag message format when signing &debian; versions, + default is %(pkg)s Debian release %(version)s + + + + + + + + Don't fail tag operations if a tag with the same version + already exists. This is a command line only option that + cannot be specified via &gbp.conf;. + + + + + + + + + Don't build, only tag and run post-tag hooks. This is a + command line only option that cannot be specified via + &gbp.conf;. + + + + + + Build area options + + &gbp-buildpackage can export the source tree to a different + build-area before performing the build. This options specify + if and how this is done: + + + + DIRECTORY + + + + Export the current branch head (or the treeish object given via + to DIRECTORY + before building. If unset the source will not be + exported before starting the build. + + + + + TREEISH + + + + Instead of exporting the current branch head, export the treeish + object TREEISH. The special name + INDEX exports the current index whereas + the special name WC exports the current + working copy as is. + + + Note that using WC enables the + + and options as well + since when exporting the working copy there's no point in + enforcing any branch or modification checks. + + + + + + + + + Purge (remove) temporary build area after build. This is + the default but it can be turned off for e.g. debugging + purposes. + + + + + + + + + Extract upstream tarball from when + using the option (in analogy to + mergeWithUpstream in svn-bp). Also remove debian/ if + contained in the upstream tarball in case of 2.0 and 3.0 + source formats. + + + This optios allows to keep only the debian/ dir in the version + control system. + + + + + + + Safety options + + In order to make sure what you build is what you upload + &gbp-buildpackage; performs several safety checks. These options allow to configure and disable them: + + + + =BRANCH_NAME + + + + If you're not on this branch when invoking &gbp-buildpackage; it will + fail. Default is master. 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 + . + + + + + + + + + Don't check if the current branch matches + DEBIAN-BRANCH. + + + + + + + + + Don't abort if there are uncommitted changes in the source tree or + the current branch doesn't match the + DEBIAN-BRANCH. + + + + + + + Color and verbosity options + + + + + + + Verbose execution. Useful for debugging and bug reports. + + + + + [auto|on|off] + + + + Whether to use colored output. + + + + + =COLOR_SCHEME + + + + Colors to use in output (when color is enabled). The format for + COLOR_SCHEME is + '<debug>:<info>:<warning>:<error>'. + Numerical values and color names are accepted, empty fields imply + the default color. For example --git-color-scheme='cyan:34::' would + show debug messages in cyan, info messages in blue and other messages + in default (i.e. warning and error messages in red). + + + + + EXAMPLES - Build a &debian; package using &git-pbuilder; which in turn invokes - &cowbuildercmd;. Instruct cowbuilder to build within a Wheezy chroot for - i386. + Build a &debian; package using &git-pbuilder; which in turn invokes + &cowbuildercmd;. Instruct cowbuilder to build within a Wheezy chroot for + i386. &gbp-buildpackage; --git-pbuilder --git-arch=i386 --git-dist=wheezy - 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: DIST=wheezy ARCH=i386 &git-pbuilder; create @@ -721,30 +780,34 @@ SEE ALSO - , - , - , - , - - git-pbuilder - 1 - , - - cowbuilder - 8 - , - - dpkg-source - 1 - , - , - &man.seealso.common; + , + , + , + , + + git-pbuilder + 1 + , + + cowbuilder + 8 + , + + dpkg-source + 1 + , + + git-submodule + 1 + , + , + &man.seealso.common; AUTHOR - &dhusername; &dhemail; + &dhusername; &dhemail; -- cgit v1.2.3