Control: tags -1 + patch Hi,
I converted the manual pages into Pod::Man format. Luckily I found a man2pod script which did most of the leavy lifting, and then I just did some cosmetic changes and fixed a few syntax errors where the script got confused. I also opened a merge request in Salsa, which might be more convenient than the attached patch. Cheers Timo
From 0ae825dc571d0918809f253eb357f65a7975dded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timo=20R=C3=B6hling?= <t...@gaussglocke.de> Date: Sat, 13 Mar 2021 21:46:30 +0100 Subject: [PATCH] Convert manpages to POD format I went with the Pod::Man format because IMHO it strikes a nice balance between readability and expressiveness. pod2man conversion happens in the Makefile. I also modified the syntax checking code to run podchecker on the pod sources. Closes: #820004 --- Makefile | 7 +- debuild-pbuilder.1 | 43 -- debuild-pbuilder.1.pod | 51 +++ pbuilder.8 | 861 ----------------------------------------- pbuilder.8.pod | 651 +++++++++++++++++++++++++++++++ pbuilderrc.5 | 590 ---------------------------- pbuilderrc.5.pod | 484 +++++++++++++++++++++++ pdebuild.1 | 205 ---------- pdebuild.1.pod | 187 +++++++++ 9 files changed, 1379 insertions(+), 1700 deletions(-) delete mode 100644 debuild-pbuilder.1 create mode 100644 debuild-pbuilder.1.pod delete mode 100644 pbuilder.8 create mode 100644 pbuilder.8.pod delete mode 100644 pbuilderrc.5 create mode 100644 pbuilderrc.5.pod delete mode 100644 pdebuild.1 create mode 100644 pdebuild.1.pod diff --git a/Makefile b/Makefile index 2e4d158d..55c7bb8c 100644 --- a/Makefile +++ b/Makefile @@ -155,12 +155,13 @@ CHECK_SCRIPTS += $(foreach d,$(ALLDIRS),$($(d)_SCRIPTS)) all: $(MAKE) -C pbuildd $@ $(MAKE) -C Documentation $@ + $(MAKE) $(NOINST_MANPAGES) check: export PBUILDER_CHECKOUT := $(CURDIR) check: # syntax check. $(foreach script,$(CHECK_SCRIPTS),bash -n $(script)$(newline)) - $(foreach mp,$(CHECK_MANPAGES),LANG=C MANWIDTH=80 man --warnings -l $(mp) >/dev/null$(newline)) + $(foreach mp,$(CHECK_MANPAGES),podchecker $(mp).pod$(newline)) # unit tests. $(foreach test,$(wildcard ./t/test_*),$(test)$(newline)) @@ -174,12 +175,16 @@ clean: testsuite/testbuild \ testsuite/testbuild2 \ testsuite/regression/work + rm -f $(NOINST_MANPAGES) $(MAKE) -C pbuildd $@ $(MAKE) -C Documentation $@ TAGS: etags pbuilder-* pbuilder +$(NOINST_MANPAGES): %: %.pod + pod2man -s$(subst .,,$(suffix $(notdir $@))) -n"$(shell echo $(basename $(notdir $@)) | tr a-z A-Z)" -cpbuilder -dDebian -r"$(shell LC_TIME=C.UTF-8 date +"%B %Y" -r$<)" $< $@ + define install_dir_impl $(INSTALL_DIRECTORY) $($(1)DIR)$(newline) $(foreach file,$($(1)_DATA),$(INSTALL_FILE) $(file) $($(1)DIR)$(newline)) diff --git a/debuild-pbuilder.1 b/debuild-pbuilder.1 deleted file mode 100644 index b2cbb7d7..00000000 --- a/debuild-pbuilder.1 +++ /dev/null @@ -1,43 +0,0 @@ -.TH "debuild-pbuilder" 1 "2002 Sep 25" "Debian" "pbuilder" -.SH "NAME" -debuild-pbuilder \- A "debuild" wrapper to satisfy build-dependency before debuild -.SH SYNOPSIS -.BI "debuild-pbuilder" - -.SH "DESCRIPTION" -A wrapper to "debuild" program that -does Build-Dependency satisfaction. - -.SH "OPTIONS" - -See debuild manpage for details. - -.SH "EXAMPLES" - -.TP -.B "debuild-pbuilder" -Satisfy build-dependency and run debuild. - -.nf -$ debuild-pbuilder - -> Attempting to satisfy build-dependencies - -> Creating pbuilder-satisfydepends-dummy package -Package: pbuilder-satisfydepends-dummy -Version: 0.invalid.0 - . - . -.hy - - - -.SH "AUTHOR" -Initial coding, and main maintenance is done by -Junichi Uekawa <dan...@debian.org>. - -The homepage is available at -.B "\%http://pbuilder.alioth.debian.org"; - -.SH "SEE ALSO" -.BR "/usr/share/doc/pbuilder/pbuilder-doc.html" ", " -.BR "debuild" "(1)" - diff --git a/debuild-pbuilder.1.pod b/debuild-pbuilder.1.pod new file mode 100644 index 00000000..8be852e4 --- /dev/null +++ b/debuild-pbuilder.1.pod @@ -0,0 +1,51 @@ +.TH "debuild-pbuilder" 1 "2002 Sep 25" "Debian" "pbuilder" + +=pod + +=head1 NAME + +debuild-pbuilder - A "debuild" wrapper to satisfy build-dependency before debuild + +=head1 SYNOPSIS + +B<debuild-pbuilder> + +=head1 DESCRIPTION + +A wrapper to "debuild" program that does Build-Dependency satisfaction. + +=head1 OPTIONS + +See debuild manpage for details. + +=head1 EXAMPLES + +=over + +=item B<debuild-pbuilder> + +Satisfy build-dependency and run debuild. + + $ debuild-pbuilder + -> Attempting to satisfy build-dependencies + -> Creating pbuilder-satisfydepends-dummy package + Package: pbuilder-satisfydepends-dummy + Version: 0.invalid.0 + . + . + +=back + +=head1 AUTHOR + +Initial coding, and main maintenance is done by +Junichi Uekawa <dan...@debian.org>. + +The homepage is available at +L<http://pbuilder.alioth.debian.org> + +=head1 SEE ALSO + +F</usr/share/doc/pbuilder/pbuilder-doc.html>, +L<debuild(1)> + diff --git a/pbuilder.8 b/pbuilder.8 deleted file mode 100644 index e59e207e..00000000 --- a/pbuilder.8 +++ /dev/null @@ -1,861 +0,0 @@ -.TH "pbuilder" 8 "2016 March" "Debian" "pbuilder" -.SH NAME -pbuilder \- personal package builder -.SH SYNOPSIS -.BI "pbuilder create [" "options" "]" -.PP -.BI "pbuilder update [" "options" "]" -.PP -.BI "pbuilder build [" "options" "] " ".dsc-file" -.PP -.BI "pbuilder clean" -.PP -.BI "pbuilder login [" "options" "]" -.PP -.BI "pbuilder execute [" "options" "] -- " "script [" "script options" "]" -.PP -.BI "pbuilder dumpconfig" -.PP -.BI "pbuilder debuild [" "options" "]" -.SH "DESCRIPTION" -Front end program to the -.B "pbuilder" -suite of programs, used for creating and maintaining chroot environment -and building Debian package in the chroot environment. - -.SH "COMMANDS" - -.P -.B "create" -.RS -Creates a -.B "base.tgz" -for the specified distribution. -.RE - -.P -.B "update" -.br -.B "up" -.br -.B "u" -.RS -Updates the -.B "base.tgz" -for the specified distribution. -Also, by specifying the -.B "\-\-override\-config" -option, it is possible to install a new apt-line using -the given options and settings in the configuration file -for the base.tgz. - -For example, to switch the distribution of an existing -base.tgz to sid, specify the -.B "\-\-distribution sid \-\-override\-config" -options to update. -.RE - -.P -.B "build" -.br -.B "b" -.RS -Builds the package specified by -.I ".dsc-file" -in the chroot environment created using the -.B "base.tgz" -.RE - -.P -.B "clean" -.RS -Cleans up the directory specified by the configuration -.B "BUILDPLACE" -and -.B "APTCACHE" -specified in -.I "/etc/pbuilderrc" -.RE - -.P -.B "login" -.br -.B "l" -.RS -Logs into the chroot, and cleaned up afterwards. -Any changes you make will not be kept. -Only use this for temporary and debugging purposes. -Do not bind-mount filesystems directly inside the chroot. -Use -.B "\-\-bindmounts" -option to mount. -.RE - -.P -.B "execute" -.br -.B "e" -.RS -Execute a script or command inside the chroot, -in a similar manner to -.B "login" - -The file specified in the command-line argument will be -copied into the chroot, and invoked. - -The remaining arguments are passed on to the script. -.RE - -.P -.B "dumpconfig" -.RS -Dumps configuration information, used for debugging. -.RE - -.P -.B "debuild" -.RS -Builds a Debian package from the Debian source directory. -The current directory should have the usual -.I "debian/" -directory. - -Same as -.B "pdebuild --use-pdebuild-internal" -.RE - -.SH "OPTIONS" - -The command is followed by options of the form -.BI "\-\-" "option name" -which will modify the semantics as explained below. -They are applied from left-to-right, and when there are -conflicting options, the rightmost options will have effect. - -.TP -.BI "\-\-basetgz [" "basetgz-location" "]" -Specifies the location of -.B "base.tgz" - -This option will define the default distribution and -apt-lines when used in -.B "pbuilder update" -and -.B "pbuilder create" - -.TP -.BI "\-\-buildplace [" "location of build" "]" -Specifies the location where building and -.B "base.tgz" -updating and creation takes place. This is -a temporary work directory. - -A subdirectory of that directory using the current PID of the -process is used. - -.TP -.BI "\-\-buildresult [" "location to put build result" "]" -Specifies the location the build result gets into after building. -The deb files and other files that have resulted from build -is copied there. -Note that the default value is not the current directory, -or -.B ".." -but another place, -.B "/var/cache/pbuilder/result" -This is to avoid -overwriting already existing deb files with -the newly generated ones. - -.TP -.BI "\-\-mirror [" "mirror location" "]" -Specifies the URL of Debian mirror to be -specified in -.B "sources.list" -inside the chroot. -This option is only valid when distribution is being specified, for -.B "update" -and -.B "build" -targets. -The format is something like: -.I "http://http.us.debian.org/debian"; -which should point to your favourite mirror. - -This option can optionally be omitted, and left blank, -in which case, this part is skipped. - -Note that these URLs specified to pbuilder will be used from within -the chroot, and specifying -.B "file:/somewhere/" -will most probably fail. - -.TP -.BI "\-\-othermirror [" "deb http://xxx/xxx/ ./ " "|" " other deb lines... " "]" -The lines which is added to the sources.list, delimited with -.B "|" -Like -.B "deb http://local/mirror stable main|deb file:/usr/local/mirror ./" - -The deb lines here are the ones that will appear at the top of the -.B "sources.list" -inside the chroot. -Be sure to follow the syntax rules of -.BR "sources.list" "(5)." -These lines appear at the beginning of the -constructed sources file, so this is the place to list your -.B "local" -mirror sites; apt will then use them in preference to the ones -listed in -.B "\-\-mirror". - -.TP -.BI "\-\-distribution [" "distribution" "]" -Specifies the distribution used. The supported values are the ones debootstrap -supports, plus experimental which is special cased in pbuilder. For instance -you may use: -.B "sid" -or -.B "experimental". - -.TP -.BI "\-\-architecture [" "architecture" "]" -Specifies the -.B build architecture -(as described in -.BR dpkg\-architecture (1)). -It'll be the architecture used when creating the chroot, defaults to the -system one. The supported values are the ones debootstrap supports. - -.TP -.BI "\-\-host-arch [" "architecture" "]" -Specifies the -.B host architecture -(as described in -.BR dpkg\-architecture (1)). -Defaults to the build architecture. -Use this flag if you are interested in doing a cross architecture build. -pbuilder will make sure the environment is correctly set up, including adding -.I nocheck -to -.B DEB_BUILD_OPTIONS -and -.BR DEB_BUILD_PROFILES . - -.TP -.B \-\-no\-auto\-cross -Suppress automatic addition of -.I nocheck -to -.B DEB_BUILD_OPTIONS -and -.B DEB_BUILD_PROFILES -in case of cross-building. All the other configuration (adding the architecture -to dpkg, updating the apt cache, installing the cross toolchain, passing -\-\-host\-arch to dpkg-buildpackage, etc) is done nonetheless; specify this -flag twice to prevent that from happening too. - -.TP -.BI "\-\-components [" "components" "]" -Specifies the default distribution components to use. eg. "main contrib non-free". -Default is "main". - -.TP -.BI "\-\-override\-config" -Specify to use different apt set up inside the chroot than it was used for creating the base.tgz. -Specify this when you want to do -.B "pbuilder update" -with a different distribution target set up. - -.B "--distribution", "--components", "--mirror", "--othermirror" -options are only valid when -.B "\-\-override\-config" -option is specified in -.B "update" -target, or when -.B "pbuilder create" -is being called. - -.TP -.BI "\-\-http\-proxy [" "proxy" "]" -Specifies the http proxy URL. Something like -.B "http://xxx.xxx.xxx.xxx:8080/"; -should do. - -.TP -.BI "\-\-use\-network [" "yes" "|" "no" "]" -Specify -.B yes -when you do not want to disable network access during build. -Network is not available on a Debian buildd, so you might -want to keep the default of -.BR no . -Disabling network access currently only works on Linux. - -.TP -.BI "\-\-aptcache [" "location of retrieved package files" "]" -Specifies the location where the packages downloaded by apt should -be cached. Use -.B "\-\-aptcache """"" -if you want caching to be turned off. - -.TP -.BI "\-\-debdelta -This option is used in the -.B "update" -target, and enable the use of debdelta (if it is already installed, otherwise -will be installed the first time this option is used). - -.TP -.BI "\-\-configfile [" "configuration file to load" "]" -Additional configuration file to read after all other -configuration files have been read. - -\" START OF hookdir description -.TP -.BI "\-\-hookdir [" "location of user scripts" "]" -Specifies the location where scripts for user intervention during -the -.B "create" -and -.B "update" -process are stored. -Scripts are executed inside the chroot. -The script names must be in the form -.B "X<digit><digit><whatever-else-you-want>" -much like boot scripts. The scripts must be executable and may -be either binaries or interpreted scripts. If it is a script -in other than Bourne Shell or Perl, it is up to the user to -ensure the interpreter was previously installed in the chrooted -environment. Files ending in ~ or .bak are ignored. - -Although it may not seem necessary, -.B "pbuilder --update" -does not invoke the hooks if -.B "\-\-hookdir" -is empty, so if you want to avoid running hooks, -run pbuilder with -.B "\-\-hookdir """"" - -If there is a distribution hook, for example, if -there was a file -.B "sid" -inside the hook directory, and the script was creating the -chroot for -.B "sid" -distribution, pbuilder will call debootstrap with that -as the 4th parameter in the chroot creation process. -This allows for use of custom debootstrap hook script. - -.B "A<digit><digit><whatever-else-you-want>" -is for -.B "build" -target. -It is executed before build starts; after -unpacking the build system, and unpacking the source, -and satisfying the build-dependency. - -.B "B<digit><digit><whatever-else-you-want>" -is executed after build system finishes building, -successfully, before copying back the build result. - -.B "C<digit><digit><whatever-else-you-want>" -is executed after build failure, before cleanup. - -.B "D<digit><digit><whatever-else-you-want>" -is executed before unpacking the source inside the chroot, -after setting up the chroot environment. -Create $TMP, and $TMPDIR if necessary. - -This is called before build-dependency is satisfied. -Also useful for calling -.B "apt-get update" - -.B "E<digit><digit><whatever-else-you-want>" -is executed after -.B "pbuilder update" - and -.B "pbuilder create" -finishes apt-get work with the chroot, -before umounting kernel file systems (/proc) and -creating the tarball from the chroot. - -.B "F<digit><digit><whatever-else-you-want>" -is executed just before user logs in, or -program starts executing, after chroot is created -in -.B "login" -or -.B "execute" -target. - -.B "G<digit><digit><whatever-else-you-want>" -is executed just after debootstrap finishes, -and configuration is loaded, and pbuilder starts mounting /proc and invoking -.B "apt-get install" -in -.B "create" -target. - -.B "H<digit><digit><whatever-else-you-want>" -is executed just after unpacking the chroot, mounting proc and any bind mount -specified in BINDMOUNTS. It's executed for every target that requires the -unpacked chroot. It's useful if you want to dynamically change the chroot guts -before anything starts using it. - -.B "I<digit><digit><whatever-else-you-want>" -is executed after build system finishes building, successfully, after copying -back the build results. - -In your hook the following environment variables are available: -.RS 8 -.I PBUILDER_OPERATION -a string indicating which of the pbuilder command has been called. Possible -values are \fBbuild\fR, \fBclean\fR, \fBcreate\fR, \fBdebuild\fR, -\fBdumpconfig\fR, \fBexecute\fR, \fBlogin\fR, \fBupdate\fR. -.RE -.RS 8 -.I BUILDDIR -the place where the build happens, the sources are inside a directory named -.BR <package>-<version> . -.RE -.RS 8 -.I DISTRIBUTION -the name of the used distribution, as provided by the DISTRIBUTION config value, -or the \-\-distribution command line flag. -.RE -.RS 8 -.I BUILD_ARCH -contains the build architecture, the architecture the package is building on. -.RE -.RS 8 -.I HOST_ARCH -contains the host architecture, the architecture the package is building for. -.RE -\" End of hookdir description - -.TP -.BI "\-\-debbuildopts [" "options" "]" - -List of options that are passed on to dpkg-buildpackage. Multiple flags are -additive and are appended to the value of DEBBUILDOPTS as specified in -pbuilderrc. To clear the list of options, pass the empty string, e.g. -\-\-debbuildopts "". - -Multiple options are delimited with spaces, -like \-\-debbuildopts "\-j100 \-E" - -.TP -.BI "\-\-profiles [" "profile1[,profile2]" "]" -Comma-separated list of build profiles to use during the build. It overrides -a possible -.I DEB_BUILD_PROFILES -environment variable already defined. - -.TP -.BI "\-\-logfile [" "file to log" "]" -Specifies the logfile to create. -The messages generated during execution will be written to the specified file, -and the standard output. - -.TP -.BI "\-\-loglevel " "I" -Specify how much output you want from pbuilder, valid values are -.BR E -(errors only), -.BR W -(errors and warnings), -.BR I -(errors, warnings and informational) and -.BR D -(everything including some debug messages). - -.TP -.BI "\-\-binary\-arch" - -Specify to build only architecture specific targets instead of all targets. -This instructs pbuilder to respect only Build-Depends, Build-Depends-Arch, -Build-Conflicts, Build-Conflicts-Arch source relationships, and calls -\fIdpkg-buildpackage\fR with \fB\-B\fR. - -Setting \fB\-\-debbuildopts\fR after this option will re-set some parts of the -effects. - -Use this option rather than using \fB\-\-debbuildopts \-B\fR. - -.TP -.BI "\-\-binary\-indep" - -Specify to build only architecture independent targets instead of all targets. -This instructs pbuilder to respect only Build-Depends, Build-Depends-Indep, -Build-Conflicts, Build-Conflicts-Indep source relationships, and calls -\fIdpkg-buildpackage\fR with \fB\-A\fR. - -Setting \fB\-\-debbuildopts\fR after this option will re-set some parts of the -effect. - -Use this option rather than using \fB\-\-debbuildopts \-A\fR. - -.TP -.BR "\-\-source\-only\-changes" , " \-\-no\-source\-only\-changes" -Specify whether or not to generate an additional .changes file for a source-only -upload, whilst still producing a full .changes file for any binary packages built. - -.TP -.BI "\-\-bin\-nmu [" "changelog message" "]" -Specify to build a binary-NMU instead of a standard package. -This option takes the changelog message to pass to the binary-NMU package as parameter. - -.TP -.BI "\-\-bin\-nmu\-maintainer [" "maintainer" "]" -Specify the maintainer name and email address to be displayed in the changes file. -If no maintainer is provided, it defaults to the last uploader. - -.TP -.BI "\-\-bin\-nmu\-version [" "version number" "]" -Specify the number to append to the version in the binary-NMU package. -If no number is provided, it defaults to 1. - -.TP -.BI "\-\-bin\-nmu\-timestamp [" "timestamp" "]" -Specify the timestamp to use in the generated chagnelog entry. -If no timestamp is provided, it defaults to current time. -If you want to specify the time as a number of seconds since 1970-01-01 00:00:00 UTC, -prepend an at sign -.RB ( @ ) -like -.BR @1478786376 . - -.TP -.BI "\-\-bindmounts " "bind-mount-points" -Bind-mount the specified directories to inside the chroot. -.I "bind-mount-points" -is a space-delimited list of directories to bind-mount which should be -specified in a space-delimited manner, surrounded in double quotations, like: -.B """/srv /somedir /someotherdir""" - -.TP -.BI "\-\-debootstrapopts " "\-\-variant=buildd" " " "\-\-keyring" " " "/usr/share/keyrings/debian\-archive\-keyring.gpg" -Add extra command-line options to debootstrap. - -Specify multiple options through multiple instance of this -option, for example: - -.B "--debootstrapopts --arch=arm --debootstrapopts --variant=buildd" - -.TP -.BI "\-\-debootstrap " "debootstrap" -Use specified debootstrap implementation as debootstrap. -Known implementations are -.BR cdebootstrap , -.B qemu-debootstrap -and -.B debootstrap -and default is to use -.B debootstrap. - -.TP -.BI "\-\-allow\-untrusted " -Allow untrusted (no key installed) and unsigned repositories. -.BI Warning: -Enabling this option may allow remote attackers to compromise the system. -Better use signed repositories and -.B "\-\-keyring" -to add the key(s). - -.TP -.BI "\-\-keyring " "path/to/keyring" -Additional keyrings to use for package verification with apt, not used for -debootstrap (use -.BR "\-\-debootstrapopts" ). -Use this to add (local) signed repositories. By default the -debian-archive-keyring package inside the chroot is used. Can be specified -multiple times. - -Keyrings are copied into -.I "/etc/apt/trusted.gpg.d" -in the chroot. APT supports it since version 0.7.25.1, firstly available in the -Debian release codenamed "squeeze" (released on 2011). -For older chroots, use a -.B G -hook to run -.B "apt\-key" -manually. - -.TP -.BI "\-\-save\-after\-login " -.TP -.BI "\-\-save\-after\-exec " -Save the chroot image after exiting from the chroot instead of -deleting changes. -Effective for -.B login -and -.B execute -session. - -.TP -.BI "\-\-autocleanaptcache" -Clean apt cache automatically, to run apt-get autoclean to only -keep the packages which are required for the version of Debian. -This is useful when you keep a aptcache directory for each distribution -and want to keep the size of the aptcache down. - -.TP -.BI "\-\-help" - -Show a brief help message. - -.SH "MORE SPECIFIC OPTIONS" - -Some options are more involved to pbuilder internal than others. The -following options are available. - -.TP -.BI "\-\-removepackages [" "packages to remove" "]" -Removes the packages on creating the -.BR "base.tgz" "." -Use this option to remove potentially dangerous or undesirable -packages, like -.B "lilo" -which nobody will need to have inside a chroot. - -Packages should be specified in a space-delimited manner, -surrounded in double quotations, like -.B """lilo gcc mawk""" - -.TP -.BI "\-\-extrapackages [" "packages to add" "]" -Adds packages specified as an addition to the default, -which is -.B "build-essential" -by default. -This is used in -.B "build" -and -.B "create" -(after successfully creating the initial chroot) -and -.BR "update" . - -The packages should be specified as a space-delimited list, or by specifying -\-\-extrapackages multiple times. - -.TP -.BI "\-\-debemail [" "maintainer-name <email-address>" "]" - -Specifies that dpkg-buildpackage be called with -.BI "-m" "maintainer-name <email-address>" -instead of default value specified in the environment -variable, or pbuilderrc - -.B "This option is almost obsolete, use \-\-debbuildopts instead" - -.TP -.BI "\-\-pkgname\-logfile" -Alternative option to -.B "\-\-logfile" -option. -Automatically creates a logfile that is named by the .dsc file name, -only really applicable for -.B "build" -target. - -The file extension is specified by -.B "PKGNAME_LOGFILE_EXTENSION" -in -.B "pbuilderrc" - -.TP -.BI "\-\-aptconfdir [" "APT configuration directory to use" "]" -Uses the apt configuration file found in the specified directory -as the chroot configuration. -.B "/etc/apt" -is one example, so that the same configuration can be used inside the -chroot. - -This option overrides other options, and may cause some inconsistency -problems. - -.TP -.BI "\-\-timeout [" "timeout in sleep time" "]" -Time out building after sleeping set time. -Specify something like -.B "\-\-timeout 10h" -in the command line. -Default is no timeout. - -.TP -.BI "\-\-no\-targz" -Not using base.tgz for operation. -The -.B "\-\-buildplace" -will not be deleted and reconstructed from -a -.B .tar.gz -file. -Also, -.B "pbuilder" -will not add its process ID to the -.B "\-\-buildplace" -as it usually would. - -Useful when experimenting with -chroots, or trying to create chroots outside control -of -.B "pbuilder." - -.TP -.BI "\-\-compressprog" -Program to use for compression of the base.tgz. -The default is to use gzip, and any program that can be used to compress data -using a pipe can be used. - -If set to "pigz", compression and decompression is gzip compatible -but will use all available CPUs. -.br -If set to "cat", there will be no compression at all (so compression/decompression -will be a lot faster but takes much more space on the disk). -.TP -.BI "\-\-twice" -Build the package twice in a row. Useful to ensure the package cleans up -properly. The resulting packages are the ones from the second build. - -.TP -.BI "\-\-preserve\-buildplace" -Do not clean the -.B "\-\-buildplace" -if it has the same contents as the -.B .tar.gz -file, and no modifications are done. - -For preserving the build place for -.B "create" -and -.B "update" -targets, see -.B "debug" -option. - -As with -.BR "\-\-no\-targz" "," -suppresses appending -.BR "pbuilder" "'s" -process ID to the -.BR "\-\-buildplace" "." - -This is useful if you want to attempt to build a large number of -packages successively, but you expect that many of them cannot have -their build dependencies satisfied. - -It will clean up the build place on failure, -or after a successful build. - -.TP -.BI "\-\-debug" - -Turn on Debug mode of pbuilder, to be verbose about errors, -and try to avoid cleanup processing when error happens in -.B "update" -and -.B "create" -targets. - -.TP -.BI "\-\-inputfile " "filename" - -Add extra file to be copied to -.I "BUILDDIR" -inside the build environment. - -available in -.B "build" -and -.B "login" -and -.B "execute" -targets. - -.SH "FILES" -.TP -.I "/etc/pbuilderrc" -The system-wide configuration file for pbuilder. - -.TP -.I "/usr/share/pbuilder/pbuilderrc" -The default settings for pbuilder, used as fallback for all -values that is not specified in -.B "/etc/pbuilderrc." - -.TP -.I "${HOME}/.pbuilderrc" -The personal configuration file for pbuilder, which overrides -settings set in other configuration files. - -Note that ${HOME} is usually /root (if you are running pbuilder -through sudo). - -.SH "EXAMPLES" - -.TP -.B "pbuilder create" - -.nf -# pbuilder create -Distribution is sid. -Building the build environment - -> running debootstrap -/usr/sbin/debootstrap -I: Retrieving Release -I: Retrieving Packages -I: Validating Packages - . - . -.hy - -.TP -.B "pbuilder update" - -.nf -# pbuilder update -W: /home/dancer/.pbuilderrc does not exist -Building the build Environment - -> extracting base tarball [/var/cache/pbuilder/base.tgz] - . - . -.hy - -.TP -.B "pbuilder build" - -.nf -# pbuilder build dsh_*.dsc -I: using fakeroot in build. -Current time: Sat Jan 20 12:03:34 JST 2007 -pbuilder-time-stamp: 1169262214 -Building the build Environment - -> extracting base tarball [/home/dancer/DEBIAN/pbuilder/pbuilder/testsuite/tmp.FeeAX18779/testimage] - -> creating local configuration - . - . -.hy - -.SH "BUGS" -This program is starting to have too many options already. - -.SH "AUTHOR" -Initial coding, and main maintenance is done by -Junichi Uekawa <dan...@debian.org>. -User hooks code added by Dale Amon <a...@vnl.com> - -The homepage is available at -.B "\%https://pbuilder.alioth.debian.org"; - - -.SH "SEE ALSO" -.BR "/usr/share/doc/pbuilder/pbuilder-doc.html" ", " -.BR "pdebuild" "(1), " -.BR "pbuilderrc" "(5)" - - -\" LocalWords: buildresult diff --git a/pbuilder.8.pod b/pbuilder.8.pod new file mode 100644 index 00000000..63ac5c0a --- /dev/null +++ b/pbuilder.8.pod @@ -0,0 +1,651 @@ +.TH "pbuilder" 8 "2016 March" "Debian" "pbuilder" + +=pod + +=head1 NAME + +pbuilder - personal package builder + +=head1 SYNOPSIS + +B<pbuilder create [>I<options>B<]> + +B<pbuilder update [>I<options>B<]> + +B<pbuilder build [>I<options>B<] >I<.dsc-file> + +B<pbuilder clean> + +B<pbuilder login [>I<options>B<]> + +B<pbuilder execute [>I<options>B<] -- >I<script>B< [>I<script options>B<]> + +B<pbuilder dumpconfig> + +B<pbuilder debuild [>I<options>B<]> + +=head1 DESCRIPTION + +Front end program to the B<pbuilder> suite of programs, used for creating and +maintaining chroot environment and building Debian package in the chroot +environment. + +=head1 COMMANDS + +=over + +=item B<create> + +Creates a B<base.tgz> for the specified distribution. + +=item B<update>, B<up>, B<u> + +Updates the F<base.tgz> for the specified distribution. Also, by specifying +the B<--override-config> option, it is possible to install a new apt-line using +the given options and settings in the configuration file for the F<base.tgz>. + +For example, to switch the distribution of an existing +F<base.tgz> to sid, specify the B<--distribution sid --override-config> +options to update. + +=item B<build>, B<b> + +Builds the package specified by I<.dsc-file> in the chroot environment created +using the F<base.tgz>. + +=item B<clean> + +Cleans up the directory specified by the configuration B<BUILDPLACE> +and B<APTCACHE> specified in F</etc/pbuilderrc>. + +=item B<login>, B<l> + +Logs into the chroot, and cleaned up afterwards. Any changes you make will not +be kept. Only use this for temporary and debugging purposes. Do not bind-mount +filesystems directly inside the chroot. Use the B<--bindmounts> option to +mount. + +=item B<execute>, B<e> + +Execute a script or command inside the chroot, in a similar manner to B<login>. + +The file specified in the command-line argument will be copied into the chroot, +and invoked. + +The remaining arguments are passed on to the script. + +=item B<dumpconfig> + +Dumps configuration information, used for debugging. + +=item B<debuild> + +Builds a Debian package from the Debian source directory. The current +directory should have the usual F<debian/> directory. + +Same as B<pdebuild --use-pdebuild-internal>. + +=back + +=head1 OPTIONS + +The command is followed by options of the form B<-->I<option name> which will +modify the semantics as explained below. They are applied from left-to-right, +and when there are conflicting options, the rightmost options will have effect. + +=over + +=item B<--basetgz [>I<basetgz-location>B<]> + +Specifies the location of F<base.tgz> + +This option will define the default distribution and apt-lines when used in +B<pbuilder update> and B<pbuilder create>. + +=item B<--buildplace [>I<location of build>B<]> + +Specifies the location where building and F<base.tgz> updating and creation +takes place. This is a temporary work directory. + +A subdirectory of that directory using the current PID of the process is used. + +=item B<--buildresult [>I<location to put build result>B<]> + +Specifies the location the build result gets into after building. The deb +files and other files that have resulted from build is copied there. Note that +the default value is not the current directory, or F<..> but another place, +F</var/cache/pbuilder/result> This is to avoid overwriting already existing deb +files with the newly generated ones. + +=item B<--mirror [>I<mirror location>B<]> + +Specifies the URL of Debian mirror to be specified in F<sources.list> inside +the chroot. This option is only valid when distribution is being specified, +for B<update> and B<build> targets. The format is something like: +L<http://http.us.debian.org/debian> which should point to your favourite +mirror. + +This option can optionally be omitted, and left blank, in which case, this part +is skipped. + +Note that these URLs specified to pbuilder will be used from within the chroot, +and specifying B<file:/somewhere/> will most probably fail. + +=item B<--othermirror [>I<deb http://xxx/xxx/ ./ >B<|>I< other deb lines... >B<]> + +The lines which is added to the sources.list, delimited with B<|> Like +B<deb http://local/mirror stable main|deb file:/usr/local/mirror ./> + +The deb lines here are the ones that will appear at the top of the +F<sources.list> inside the chroot. Be sure to follow the syntax rules of +L<sources.list(5)>. These lines appear at the beginning of the constructed +sources file, so this is the place to list your B<local> mirror sites; apt will +then use them in preference to the ones listed in B<--mirror>. + +=item B<--distribution [>I<distribution>B<]> + +Specifies the distribution used. The supported values are the ones debootstrap +supports, plus experimental which is special cased in pbuilder. For instance +you may use: B<sid> or B<experimental>. + +=item B<--architecture [>I<architecture>B<]> + +Specifies the B<build architecture> (as described in L<dpkg-architecture(1)>). +It'll be the architecture used when creating the chroot, defaults to the system +one. The supported values are the ones debootstrap supports. + +=item B<--host-arch [>I<architecture>B<]> + +Specifies the B<host architecture> (as described in L<dpkg-architecture(1)>). +Defaults to the build architecture. Use this flag if you are interested in +doing a cross architecture build. pbuilder will make sure the environment is +correctly set up, including adding I<nocheck> to B<DEB_BUILD_OPTIONS> and +B<DEB_BUILD_PROFILES>. + +=item B<--no-auto-cross> + +Suppress automatic addition of I<nocheck> to B<DEB_BUILD_OPTIONS> and +B<DEB_BUILD_PROFILES> in case of cross-building. All the other configuration +(adding the architecture to dpkg, updating the apt cache, installing the cross +toolchain, passing B<--host-arch> to B<dpkg-buildpackage>, etc) is done +nonetheless; specify this flag twice to prevent that from happening too. + +=item B<--components [>I<components>B<]> + +Specifies the default distribution components to use. eg. "main contrib +non-free". Default is "main". + +=item B<--override-config> + +Specify to use different apt set up inside the chroot than it was used for +creating the base.tgz. Specify this when you want to do B<pbuilder update> +with a different distribution target set up. + +B<--distribution, --components, --mirror, --othermirror> +options are only valid when B<--override-config> option is specified in +B<update> target, or when B<pbuilder create> is being called. + +=item B<--http-proxy [>I<proxy>B<]> + +Specifies the http proxy URL. Something like +B<http://xxx.xxx.xxx.xxx:8080/> +should do. + + +=item B<--use-network [>I<yes>B<|>I<no>B<]> + +Specify B<yes> when you do not want to disable network access during build. +Network is not available on a Debian buildd, so you might want to keep the +default of B<no>. Disabling network access currently only works on Linux. + +=item B<--aptcache [>I<location of retrieved package files>B<]> + +Specifies the location where the packages downloaded by apt should be cached. +Use B<--aptcache> if you want caching to be turned off. + + +=item B<--debdelta> + +This option is used in the B<update> target, and enable the use of debdelta (if +it is already installed, otherwise will be installed the first time this option +is used). + + +=item B<--configfile [>I<configuration file to load>B<]> + +Additional configuration file to read after all other configuration files have +been read. + +=item B<--hookdir [>I<location of user scripts>B<]> + +Specifies the location where scripts for user intervention during the B<create> +and B<update> process are stored. Scripts are executed inside the chroot. The +script names must be in the form +B<E<lt>letterE<gt>E<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +much like boot scripts. The scripts must be executable and may be either +binaries or interpreted scripts. If it is a script in other than Bourne Shell +or Perl, it is up to the user to ensure the interpreter was previously +installed in the chrooted environment. Files ending in ~ or .bak are ignored. + +Although it may not seem necessary, B<pbuilder --update> does not invoke the +hooks if B<--hookdir> is empty, so if you want to avoid running hooks, run +pbuilder with B<--hookdir>. + +If there is a distribution hook, for example, if there was a file B<sid> inside +the hook directory, and the script was creating the chroot for B<sid> +distribution, pbuilder will call debootstrap with that as the 4th parameter in +the chroot creation process. This allows for use of custom debootstrap hook +script. + +B<AE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is for B<build> target. It is executed before build starts; after unpacking +the build system, and unpacking the source, and satisfying the +build-dependency. + +B<BE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed after build system finishes building, successfully, before copying +back the build result. + +B<CE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed after build failure, before cleanup. + + +B<DE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed before unpacking the source inside the chroot, after setting up the +chroot environment. Create B<$TMP>, and B<$TMPDIR> if necessary. + +This is called before build-dependency is satisfied. Also useful for calling +B<apt-get update> + +B<EE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed after B<pbuilder update> and B<pbuilder create> finish apt-get +work with the chroot, before umounting kernel file systems (/proc) and creating +the tarball from the chroot. + +B<FE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed just before user logs in, or program starts executing, after chroot +is created in B<login> or B<execute> target. + +B<GE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed just after debootstrap finishes, and configuration is loaded, and +pbuilder starts mounting /proc and invoking B<apt-get install> in B<create> +target. + +B<HE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed just after unpacking the chroot, mounting proc and any bind mount +specified in L<BINDMOUNTS>. It's executed for every target that requires the +unpacked chroot. It's useful if you want to dynamically change the chroot guts +before anything starts using it. + +B<IE<lt>digitE<gt>E<lt>digitE<gt>E<lt>whatever-else-you-wantE<gt>> +is executed after build system finishes building, successfully, after copying +back the build results. + +In your hook the following environment variables are available: + +=over + +=item I<PBUILDER_OPERATION> + +a string indicating which of the pbuilder command has been called. Possible +values are B<build>, B<clean>, B<create>, B<debuild>, +B<dumpconfig>, B<execute>, B<login>, B<update>. + +=item I<BUILDDIR> + +the place where the build happens, the sources are inside a directory named +F<E<lt>packageE<gt>-E<lt>versionE<gt>>. + +=item I<DISTRIBUTION> + +the name of the used distribution, as provided by the DISTRIBUTION config value, +or the B<--distribution> command line flag. + +=item I<BUILD_ARCH> + +contains the build architecture, the architecture the package is building on. + +=item I<HOST_ARCH> + +contains the host architecture, the architecture the package is building for. + +=back + +=item B<--debbuildopts [>I<options>B<]> + + +List of options that are passed on to dpkg-buildpackage. Multiple flags are +additive and are appended to the value of DEBBUILDOPTS as specified in +pbuilderrc. To clear the list of options, pass the empty string, e.g. +--debbuildopts "". + +Multiple options are delimited with spaces, +like --debbuildopts "-j100 -E" + + +=item B<--profiles [>I<profile1>B<[,>I<profile2>B<[,>I<...>B<]]]> + +Comma-separated list of build profiles to use during the build. It overrides a +possible I<DEB_BUILD_PROFILES> environment variable already defined. + +=item B<--logfile [>I<file to log>B<]> + +Specifies the logfile to create. The messages generated during execution will +be written to the specified file, and the standard output. + +=item B<--loglevel >I<I> + +Specify how much output you want from pbuilder, valid values are B<E> (errors +only), B<W> (errors and warnings), B<I> (errors, warnings and informational) +and B<D> (everything including some debug messages). + +=item B<--binary-arch> + +Specify to build only architecture specific targets instead of all targets. +This instructs pbuilder to respect only Build-Depends, Build-Depends-Arch, +Build-Conflicts, Build-Conflicts-Arch source relationships, and calls +I<dpkg-buildpackage> with B<-B>. + +Setting B<--debbuildopts> after this option will re-set some parts of the +effects. + +Use this option rather than using B<--debbuildopts -B>. + +=item B<--binary-indep> + +Specify to build only architecture independent targets instead of all targets. +This instructs pbuilder to respect only Build-Depends, Build-Depends-Indep, +Build-Conflicts, Build-Conflicts-Indep source relationships, and calls +I<dpkg-buildpackage> with B<-A>. + +Setting B<--debbuildopts> after this option will re-set some parts of the +effect. + +Use this option rather than using B<--debbuildopts -A>. + +=item B<--source-only-changes>, B<--no-source-only-changes> + +Specify whether or not to generate an additional .changes file for a +source-only upload, whilst still producing a full .changes file for any binary +packages built. + +=item B<--bin-nmu [>I<changelog message>B<]> + +Specify to build a binary-NMU instead of a standard package. +This option takes the changelog message to pass to the binary-NMU package as parameter. + +=item B<--bin-nmu-maintainer [>I<maintainer>B<]> + +Specify the maintainer name and email address to be displayed in the changes file. +If no maintainer is provided, it defaults to the last uploader. + +=item B<--bin-nmu-version [>I<version number>B<]> + +Specify the number to append to the version in the binary-NMU package. +If no number is provided, it defaults to 1. + +=item B<--bin-nmu-timestamp [>I<timestamp>B<]> + +Specify the timestamp to use in the generated chagnelog entry. If no timestamp +is provided, it defaults to current time. If you want to specify the time as a +number of seconds since 1970-01-01 00:00:00 UTC, prepend an at sign (B<@>) like +B<@1478786376>. + +=item B<--bindmounts >I<bind-mount-points> + +Bind-mount the specified directories to inside the chroot. +I<bind-mount-points> is a space-delimited list of directories to bind-mount +which should be specified in a space-delimited manner, surrounded in double +quotations, like: B</srv /somedir /someotherdir> + +=item B<--debootstrapopts >I<--variant=buildd>B< >I<--keyring>B< >I</usr/share/keyrings/debian-archive-keyring.gpg> + +Add extra command-line options to debootstrap. + +Specify multiple options through multiple instance of this +option, for example: + +B<--debootstrapopts --arch=arm --debootstrapopts --variant=buildd> + +=item B<--debootstrap >I<debootstrap> + +Use specified debootstrap implementation as debootstrap. Known implementations +are B<cdebootstrap>, B<qemu-debootstrap> and B<debootstrap> and default is to +use B<debootstrap.> + +=item B<--allow-untrusted> + +Allow untrusted (no key installed) and unsigned repositories. + +B<Warning:> + +Enabling this option may allow remote attackers to compromise the system. +Better use signed repositories and B<--keyring> to add the key(s). + +=item B<--keyring >I<path/to/keyring> + +Additional keyrings to use for package verification with apt, not used for +debootstrap (use B<--debootstrapopts>). Use this to add (local) signed +repositories. By default the debian-archive-keyring package inside the chroot +is used. Can be specified multiple times. + +Keyrings are copied into F</etc/apt/trusted.gpg.d> in the chroot. APT supports +it since version 0.7.25.1, firstly available in the Debian release codenamed +"squeeze" (released on 2011). For older chroots, use a B<G> hook to run +B<apt-key> manually. + +=item B<--save-after-login>, B<--save-after-exec> + +Save the chroot image after exiting from the chroot instead of deleting +changes. Effective for B<login> and B<execute> session. + +=item B<--autocleanaptcache> + +Clean apt cache automatically, to run apt-get autoclean to only +keep the packages which are required for the version of Debian. +This is useful when you keep a aptcache directory for each distribution +and want to keep the size of the aptcache down. + +=item B<--help> + +Show a brief help message. + +=back + +=head1 MORE SPECIFIC OPTIONS + +Some options are more involved to pbuilder internal than others. The +following options are available. + +=over + +=item B<--removepackages [>I<packages to remove>B<]> + +Removes the packages on creating the B<base.tgz>. Use this option to remove +potentially dangerous or undesirable packages, like B<lilo> which nobody will +need to have inside a chroot. + +Packages should be specified in a space-delimited manner, surrounded in double +quotations, like B<lilo gcc mawk> + +=item B<--extrapackages [>I<packages to add>B<]> + +Adds packages specified as an addition to the default, which is +B<build-essential> by default. This is used in B<build> and B<create> (after +successfully creating the initial chroot) and B<update>. + +The packages should be specified as a space-delimited list, or by specifying +B<--extrapackages> multiple times. + +=item B<--debemail [>I<maintainer-name E<lt>email-addressE<gt>>B<]> + +Specifies that dpkg-buildpackage be called with +B<-m>I<maintainer-name E<lt>email-addressE<gt>> +instead of default value specified in the environment variable, or +F<pbuilderrc>. + +B<This option is almost obsolete, use --debbuildopts instead> + +=item B<--pkgname-logfile> + +Alternative option to B<--logfile> option. Automatically creates a logfile +that is named by the .dsc file name, only really applicable for B<build> +target. + +The file extension is specified by B<PKGNAME_LOGFILE_EXTENSION> in +F<pbuilderrc> + +=item B<--aptconfdir [>I<APT configuration directory to use>B<]> + +Uses the apt configuration file found in the specified directory as the chroot +configuration. F</etc/apt> is one example, so that the same configuration can +be used inside the chroot. + +This option overrides other options, and may cause some inconsistency +problems. + +=item B<--timeout [>I<timeout in sleep time>B<]> + +Time out building after sleeping set time. Specify something like B<--timeout +10h> in the command line. Default is no timeout. + +=item B<--no-targz> + +Not using F<base.tgz> for operation. The B<--buildplace> will not be deleted +and reconstructed from a B<.tar.gz> file. Also, B<pbuilder> will not add its +process ID to the B<--buildplace> as it usually would. + +Useful when experimenting with chroots, or trying to create chroots outside +control of B<pbuilder>. + +=item B<--compressprog> + +Program to use for compression of the base.tgz. +The default is to use gzip, and any program that can be used to compress data +using a pipe can be used. + +If set to "pigz", compression and decompression is gzip compatible +but will use all available CPUs. + +If set to "cat", there will be no compression at all (so compression/decompression +will be a lot faster but takes much more space on the disk). + +=item B<--twice> + +Build the package twice in a row. Useful to ensure the package cleans up +properly. The resulting packages are the ones from the second build. + +=item B<--preserve-buildplace> + +Do not clean the B<--buildplace> if it has the same contents as the B<.tar.gz> +file, and no modifications are done. + +For preserving the build place for B<create> and B<update> targets, see +B<debug> option. + +As with B<--no-targz>, suppresses appending B<pbuilder>'s process ID to the +B<--buildplace>. + +This is useful if you want to attempt to build a large number of packages +successively, but you expect that many of them cannot have their build +dependencies satisfied. + +It will clean up the build place on failure, or after a successful build. + +=item B<--debug> + +Turn on Debug mode of pbuilder, to be verbose about errors, and try to avoid +cleanup processing when error happens in B<update> and B<create> targets. + +=item B<--inputfile >I<filename> + +Add extra file to be copied to I<BUILDDIR> inside the build environment. + +Available in B<build> and B<login> and B<execute> targets. + +=back + +=head1 FILES + +=over + +=item F</etc/pbuilderrc> + +The system-wide configuration file for pbuilder. + + +=item F</usr/share/pbuilder/pbuilderrc> + +The default settings for pbuilder, used as fallback for all +values that is not specified in +F</etc/pbuilderrc>. + +=item F<${HOME}/.pbuilderrc> + +The personal configuration file for pbuilder, which overrides +settings set in other configuration files. + +Note that ${HOME} is usually /root (if you are running pbuilder +through sudo). + +=back + +=head1 EXAMPLES + +=over + +=item B<pbuilder create> + + # pbuilder create + Distribution is sid. + Building the build environment + -> running debootstrap + /usr/sbin/debootstrap + I: Retrieving Release + I: Retrieving Packages + I: Validating Packages + . + . + +=item B<pbuilder update> + + # pbuilder update + W: /home/dancer/.pbuilderrc does not exist + Building the build Environment + -> extracting base tarball [/var/cache/pbuilder/base.tgz] + . + . + +=item B<pbuilder build> + + # pbuilder build dsh_*.dsc + I: using fakeroot in build. + Current time: Sat Jan 20 12:03:34 JST 2007 + pbuilder-time-stamp: 1169262214 + Building the build Environment + -> extracting base tarball [/home/dancer/DEBIAN/pbuilder/pbuilder/testsuite/tmp.FeeAX18779/testimage] + -> creating local configuration + . + . + +=back + +=head1 BUGS + +This program is starting to have too many options already. + +=head1 AUTHOR + +Initial coding, and main maintenance is done by +Junichi Uekawa L<dan...@debian.org>. +User hooks code added by Dale Amon L<a...@vnl.com> + +The homepage is available at +L<https://pbuilder.alioth.debian.org> + +=head1 SEE ALSO + +F</usr/share/doc/pbuilder/pbuilder-doc.html>, +L<pdebuild(1)>, +L<pbuilderrc(5)> + diff --git a/pbuilderrc.5 b/pbuilderrc.5 deleted file mode 100644 index 68f1f72b..00000000 --- a/pbuilderrc.5 +++ /dev/null @@ -1,590 +0,0 @@ -.TH "pbuilderrc" 5 "2016 March" "Debian" "pbuilder" -.SH NAME -pbuilderrc \- configuration files for personal package builder -.SH DESCRIPTION -.B "/etc/pbuilderrc" -contains default values used in the -.B "pbuilder" -program invocation. -.PP -The file itself is sourced by a shell script, so -it is required that the file conforms to shell script conventions. -.PP -The environment variable -.I PBUILDER_OPERATION -contains the current operation mode of pbuilder, and can be used to do a -conditional configuration. -Possible values are \fBbuild\fR, \fBclean\fR, \fBcreate\fR, \fBdebuild\fR, -\fBdumpconfig\fR, \fBexecute\fR, \fBlogin\fR, \fBupdate\fR. - -.SH "FORMAT" -.TP -.BI "APTCACHE=" "/var/cache/pbuilder/aptcache" -Specify the location that the packages downloaded by apt -should be cached. -Setting this value to "" will cause caching to be -turned off. -.TP -.BI "APTCACHEHARDLINK=" "yes" -Specify using hard links in apt cache handling. -Changing this to no will disable hard linking and will -copy the files. - -It is advised to set this to -.B "no" -if you are using user-mode-linux. -.TP -.BI "APTCONFDIR=" "/etc/apt" -Configures where the apt configuration files are copied from. -By default, this value is empty, -allowing the usual configuration options -to take effect. -Setting this variable overrides other options. - -.TP -.BI "ARCHITECTURE=" "`dpkg \-\-print\-architecture`" -Specifies the -.B build architecture -(as described in -.BR dpkg\-architecture (1)). -It'll be the architecture used when creating the chroot, defaults to the - system one. The supported values are the ones debootstrap supports. - -.TP -.BI "AUTOCLEANAPTCACHE=" "yes" -Always run with -.B "\-\-autocleanaptcache" -option. -.TP -.BI "AUTO_DEBSIGN=" "yes" -When this value is set to yes, -.B pdebuild -will invoke debsign command after building. -.TP -.BI "BASETGZ=" "/var/cache/pbuilder/base.tgz" -Specifies the default location for the archived -chroot image to be created and used. -This is overridden with the option -.BR "\-\-basetgz" "." -.TP -.BI "BINDMOUNTS=" "directories-to-bind-mount[:internal-mountpoint]" -When this value is set, pbuilder will mount these directories using -bind-mount. Different directories are space separated, a column can optionally -specify a mount destination inside the chroot. -.br -Do not bind-mount -.BR "/" . -.br -An Example: - -.EX -BINDMOUNTS="/home /mnt/test /home/joe/repo:/var/repo" -.EE -.TP -.BI "BUILDDIR=" "/build" -The directory inside the chroot where the build happens. -This directory will contain the build products; the source packages will be -unpacked in a subdirectory therein contained, named -.IR $srcpkg - $ver , -with -.I $ver -being the upstream part of the version, without epoch and debian revision. - -Attention! Some directories \(em such as -.B /tmp -\(em are not safe to use since they can be world-writable, and external users -can temper with the build process. -.TP -.BI "BUILDPLACE=" "/var/cache/pbuilder/build/" -The default place which the chroot is constructed. -.B pbuilder -will use the directory -.BR "$BUILDPLACE$$" "." -which means, that it will use the directory and the -PID to determine the directory to use. -This should obtain an unique directory for -concurrent runs of pbuilder in one machine. -This is not guaranteed to happen on network shared drives, -so be aware of this fact when playing with this option -on NFS shared beowulf clusters. -Change it to something like -.I "/var/cache/pbuilder/build/$HOSTNAME/" -when doing such a thing. - -.B "pbuilder clean" -cleans up this directory. -.TP -.BI "BUILDRESULT=" "/var/cache/pbuilder/result/" -Specify the default directory which the build result will -be copied over to after the building. - -Unlike the -.B "\-\-buildresult" -command-line option the path is not canonicalized, so you should specify a -full path, not a relative path. -.TP -.BI "EATMYDATA=" "no" -Enable or disable the builtin eatmydata support. -.br -For this to work the library of the same architecture as the one inside the -chroot has to be installed in the host. -.TP -.BI "CCACHEDIR=" "" -Specifies where ccache will keep its cached compiler output. -If this is specified, ccache will be installed upon pbuilder create or -pbuilder update, -.I /usr/lib/ccache -will be prepended to the -.BR PATH , -.B CCACHEDIR -will be bind-mounted in the chroot, and -.B CCACHE_DIR -(ccache variable) will be set to -.BR CCACHEDIR . -Note that files in -.B CCACHEDIR -are chowned to -.B BUILDUSERID -(1234 by default). -.br -.I ccache -is disabled by default. -.TP -.BI "BUILDRESULTUID=" -.TP -.BI "BUILDRESULTGID=" -Set the UID and GID of the files built as result. -They probably need to be set to numeric UID values, -so that it works the same inside the chroot and outside the -chroot. - -If sudo is used, the values specified by sudo is used. -They are -.BR "SUDO_UID" ", and" -.BR "SUDO_GID" ". " -The default value is -.B "0" -.TP -.BI "BUILDSOURCEROOTCMD=" "fakeroot" -This option is used on invocation of fakeroot -for -.B "dpkg\-buildpackage" -in -.B "pdebuild" -.TP -.BI "BUILDUSERID=" "1234" -The uid to be used inside chroot. -It should ideally not collide with user-id outside the chroot, -to avoid user inside chroot having access to -processes owned by the user id outside the chroot. -.TP -.BI "BUILDUSERNAME=" "pbuilder" -The user name of the user the build will run as. -Specifying this will enable the use of fakeroot inside -pbuilder. - -Note that this will require fakeroot to be installed within -the chroot, and fakeroot will automatically be installed. -And -.B "\-rfakeroot" -will be added to -.B "DEBBUILDOPTS" -.TP -.BI "COMPONENTS=" "main" -Specify the default distribution components to use. -This option is space-delimited, use quotes when listing multiple components. -This option only affects when doing -.B "pbuilder create" -or when -.B "\-\-override\-config" -is specified for -.B "pbuilder update" -option. -.TP -.BI "COMPRESSPROG=" "gzip" -Program to use for compression of the base.tgz. -The default is to use gzip, and any program that can be used to compress data -using a pipe can be used. - -If set to "pigz", compression and decompression is gzip compatible -but will use all available CPUs. -.br -If set to "cat", there will be no compression at all (so compression/decompression -will be a lot faster but takes much more space on the disk). -.TP -.BI "export http_proxy=" "http://your-proxy:8080/"; -Defines the proxy for http connection. -.TP -.BI "export DEBIAN_BUILDARCH=" "athlon" -Uses this variable as -.BR "DEBIAN_BUILDARCH" "." -This trick can be used for other environmental variables as well. -.TP -.BI "DEBBUILDOPTS=" "" -The options given here will be passed on to -.BR dpkg\-buildpackage . -This can be useful e.g. for binary-only builds. The command-line option -.B "\-\-debbuildopts" will be appended to any contents specified here but -may also be used to reset the list of options. - -The default value is to build source and binary package. -.TP -.BI "DEBOOTSTRAPOPTS=" "( '\-\-variant=buildd' '\-\-keyring' '/usr/share/keyrings/debian\-archive\-keyring.gpg' )" -When this option is set to -.B "\-\-variant=buildd" -.B "pbuilder" -will invoke -.B "$DEBOOTSTRAP" -with -.B "\-\-variant=buildd" -option, which results in debootstrap creating a minimal chroot for -buildd instead of trying to create a minimal installation chroot. -.B "\-\-keyring" -is used to specify a keyring for debootstrap. -.TP -.BI "APTKEYRINGS=" "()" -Additional keyrings to use for package verification with apt, not used for -debootstrap (use -.BR "$DEBOOTSTRAPOPTS" ). -Use this to add (local) signed repositories. By default the -debian-archive-keyring package inside the chroot is used. - -Keyrings are copied into -.I "/etc/apt/trusted.gpg.d" -in the chroot. APT supports it since version 0.7.25.1, firstly available in the -Debian release codenamed "squeeze" (released on 2011). -For older chroots, use a -.B G -hook to run -.B "apt\-key" -manually. -.TP -.BI "DEBOOTSTRAP=" "debootstrap" -Use this option to switch the implementation of -debootstrap. -Known implementations of debootstrap are -.B "cdebootstrap" -and -.B "debootstrap" -.TP -.BI "export DEBIAN_FRONTEND=" "noninteractive" -Sets interactiveness of pbuilder run. -Setting this value to blank will cause the -pbuilder run to be interactive. -Change this value when noninteractive upgrades -do not work. -.TP -.BI "DISTRIBUTION=" "sid" -Specify the default distribution to use. -This option only affects when doing -.B "pbuilder create" -or when -.B "\-\-override\-config" -is specified for -.B "pbuilder update" -option. -.TP -.BI "EXTRAPACKAGES=" """ccache lintian XXX""" -Specifies extra packages which the system should install -in the chroot on -.BR "pbuilder create" "." -This is a space-delimited list. -Also this is installed on -.B "pbuilder update" -.TP -.BI "HOOKDIR=" "/usr/lib/pbuilder/hooks" -Specifies the default location for the user hooks -directory. -This is overridden with the option -.BR "\-\-hookdir" "." - -If this is specified, hooks are searched for in -the chroot, when running -.BR "pbuilder" "." -If it is not defined, or is an empty string, -hooks are not executed. - -For details, see -.B "pbuilder(8)" -.TP -.BI "LOGLEVEL=" "I" -Specify how much output you want from pbuilder, valid values are -.BR E -(errors only), -.BR W -(errors and warnings), -.BR I -(errors, warnings and informational) and -.BR D -(everything including some debug messages). -.TP -.BI "USECOLORS=" "auto" -Specify whether you'd like to see colored output from pbuilder. Valid values are -.B auto -(to try to automatically detect whether the terminal supports them), -.B yes -(to always use colors), and -.B no -(to never use colors). -.TP -.BI "MIRRORSITE=" "http://www.jp.debian.org/debian"; -Specify the mirror site which contains the -main Debian distribution. - -Note that you cannot really use -.B "file:/" -kind of URL, because the location needs to be accessible from within -the chroot. -.TP -.BI "OTHERMIRROR=" "deb http://xxx/xxx/ ./ " "[|" " other deb lines... " "]" -The lines which is added to the sources.list, delimited with -.B "|" -Like: -.br -.B "deb http://local/mirror sid main|deb file:/usr/local/mirror ./" - -The deb lines here are the ones that will appear at the top of the -.B "sources.list" -inside the chroot. -Be sure to follow the syntax rules of -.BR "sources.list" "(5)." -These lines appear at the beginning of the -constructed sources file, so this is the place to list your -.B "local" -mirror sites; apt will then use them in preference to the ones -listed in -.B "MIRRORSITE". - -To make changes on mirror site effective on -.B update -.B "\-\-override\-config" -needs to be specified. -.TP -.BI "PDEBUILD_PBUILDER=" "pbuilder" -Specify what pbuilder implementation to use for pdebuild. -The currently possible values are -.B "pbuilder" -and -.B "cowbuilder" -.TP -.BI "PKGNAME_LOGFILE_EXTENSION=" "_$(dpkg \-\-print\-architecture).build" -The extension of filename used in pkgname\-logfile option. -.TP -.BI "PKGNAME_LOGFILE=" "yes" -Always run with -.B "\-\-pkgname\-logfile" -option, and create a logfile named after the package name. -.TP -.BI "PBUILDERROOTCMD=" "sudo \-E" -This option is used on invocation of -.B "pbuilder build" -in -.B "pdebuild" -.TP -.BI "PBUILDERSATISFYDEPENDSCMD=" "/usr/lib/pbuilder/pbuilder\-satisfydepends" -This option is used by various parts of pbuilder to satisfy -(i.e. install) the build-dependencies of a package. -These are the available implementations: - -.I pbuilder\-satisfydepends\-apt -the newest implementation, which leverage the ability of apt 1.4 to satisfy -build dependencies and build conflicts from a .dsc; useful since it's pretty -fast and doesn't require the installation of any non-required package in the -chroot, nor of dummy packages. - -.I pbuilder\-satisfydepends\-experimental -might be useful to pull packages from repositories with a low APT Pin Priority -(for example, Debian's experimental or stable-backports). - -.I pbuilder\-satisfydepends\-aptitude -will resolve build-dependencies and build-conflicts with aptitude which helps -dealing with complex cases but does not support unsigned APT repositories. - -.I pbuilder\-satisfydepends\-gdebi -will resolve build-dependencies using gdebi, faster than classic implementation, -and does not require installation of a dummy package like the aptitude -implementation. - -.I pbuilder\-satisfydepnds\-classic -the "classic" implementation, which was the original implementation used by -default until v0.172. - -The default is now "aptitude". -.TP -.BI "PBUILDERSATISFYDEPENDSOPT=" "()" -Array of flags to give to pbuilder\-satisfydepends. - -.TP -.BI "SOURCE_ONLY_CHANGES=" "yes" -Specify whether to generate an additional .changes file for a source-only -upload, whilst still producing a full .changes file for any binary packages -built. - -.TP -.BI "ALLOWUNTRUSTED=" "no" -Allow untrusted (no key installed) and unsigned repositories. -.BI Warning: -Enabling this option may allow remote attackers to compromise the system. -Better use signed repositories and -.B "$APTKEYRINGS" -to add the key(s). - -.TP -.BI "APTGETOPT=" "()" -Extra flags to give to apt\-get. - -.TP -.BI "APTITUDEGETOPT=" "()" -Extra flags to give to aptitude. - -.TP -.BI "DEBDELTA=" "no" -Enable use of debdelta to download the needed updated in the chroot, if -debdelta is already installed. - -.TP -.BI "REMOVEPACKAGES=" "lilo" -Specify the packages to be removed on creation of -.B base.tgz -Leaving lilo in the chroot is like keeping a timebomb... -.TP -.BI "TIMEOUT_TIME=" "2h" -Sets timeout time. -Build will be stopped with SIGTERM after the set time. -.TP -.BI "USEDEVFS=" "no" -Whether to mount a devfs or not. Has no effect on kFreeBSD, as a devfs (and fdescfs for -.BR /dev/fd ) -is always used. -.TP -.BI "USEDEVPTS=" "yes" -Specify -.B yes -when it is desired to mount -.B /dev/pts -interface. It is usually a good idea, since there -are many software which fail miserably when there is no -.B /dev/pts -being mounted. -.TP -.BI "USESYSFS=" "yes" -Whether to mount a sysfs (linsysfs for kFreeBSD) in -.B /sys -or not. Has no effect on GNU/Hurd hosts, where sysfs is not available. -It is usually a good idea, since there are several software which require -.B /sys -being populated. -.TP -.BI "USENETWORK=" "no" -Specify -.B yes -when you do not want to disable network access during build. -Network is not available on a Debian buildd, so you might -want to keep the default. -Disabling network access currently only works on Linux. -.TP -.BI "USECGROUP=" "yes" -Specify -.B yes -to use a cgroup to isolate build processes, so that any stray processes -from the build can be cleaned up afterwords. -This currently only works on Linux systems running systemd. -.TP -.BI "USESHM=" "yes" -Specify -.B yes -when it is desired to mount -.B /dev/shm -mount point. It is usually a good idea in order to work with software that -expects shm to work. -.br -.B /run/shm -will be configured as a symbolic link to -.BR /dev/shm . -.br -This option used to be named -.BR USERUNSHM , -for compatibility purpose the old name is still supported, and if set it'll -override any -.BR USESHM . -.br -Has no effect on GNU/Hurd hosts due to bugs in -.BR /hurd/tmpfs ; -since /dev is always bind-mounted, the host's -.B /dev/shm -will be used. - -.TP -.BI "USE_PDEBUILD_INTERNAL=" "yes" -When this option is set to -.I yes -.B "pdebuild\-internal" -implementation of -.B pdebuild -is used. -.TP -.BI "USEPROC=" "yes" -Specify -.B yes -when it is desired to mount -.B /proc -interface. It is usually a good idea, since there are many -software which fail miserably when there is no -.B /proc -being mounted. -.TP -.BI "ADDITIONAL_BUILDRESULTS=" "(foo \(dqbar*\(dq \(dqbaz\(rs biz\(dq)" -Array of additional files to copy out of the build area. -.br -In case a wildcard is needed (e.g. -.BR *.changes ) -quote it to have the wildcard escaped and not expanded at configuration load time, -but instead expanded at run time when the additional build artifacts are exported. -Spaces in file names needs to be escaped by using a \(rs or a wildcard to match -the space. - -.TP -.BI "CONFDIR=" "/etc/pbuilder/conf_files" -.B pbuilder -copies some configuration files (like -.B /etc/hosts -or -.BR /etc/hostname ) -from the host system into the chroot. If the directory specified here -exists and contains one of the copied files (without the leading /etc) that -file will be copied from here instead of the system one. -.TP -.BI "BUILD_HOME=" "/nonexistent" -Set the what the -.B HOME -environment variable points to during the builds. It defaults to a non-existing -directory to prevent builds from writing to HOME, which is reserved to users. -If you need a working HOME you can set it to -.B $BUILDDIR -instead. -.TP -.BI "BINNMU_MAINTAINER=" "" -Set the value of the maintainer name and email in the changelog during binNMU. -Such value is then copied to the Changed-By field of the .changes file. Can be -set at run time with the -.B --bin-nmu-maintainer -command line option. - - -.SH "AUTHOR" -Initial coding, and main maintenance is done by -Junichi Uekawa <dan...@debian.org>. -User hooks code added by Dale Amon <a...@vnl.com> - -The homepage is available at -.B "\%https://pbuilder-team.pages.debian.net/pbuilder/"; -.SH "FILES" -.I "/etc/pbuilderrc, $HOME/.pbuilderrc" -.SH "SEE ALSO" -.BR "/usr/share/doc/pbuilder/pbuilder\-doc.html" ", " -.BR "cowbuilder" "(8), " -.BR "pbuilder" "(8), " -.BR "pdebuild" "(1)" - -\" LocalWords: interactiveness noninteractive pdebuild pbuilder buildd -\" LocalWords: pbuilderrc diff --git a/pbuilderrc.5.pod b/pbuilderrc.5.pod new file mode 100644 index 00000000..e05a71c4 --- /dev/null +++ b/pbuilderrc.5.pod @@ -0,0 +1,484 @@ +.TH "pbuilderrc" 5 "2016 March" "Debian" "pbuilder" + +=pod + +=head1 NAME + +pbuilderrc - configuration files for personal package builder + +=head1 DESCRIPTION + +F</etc/pbuilderrc> contains default values used in the B<pbuilder> program +invocation. + +The file itself is sourced by a shell script, so +it is required that the file conforms to shell script conventions. + +The environment variable I<PBUILDER_OPERATION> contains the current operation +mode of pbuilder, and can be used to do a conditional configuration. Possible +values are B<build>, B<clean>, B<create>, B<debuild>, B<dumpconfig>, +B<execute>, B<login>, B<update>. + +=head1 FORMAT + +=over + +=item B<APTCACHE=>I</var/cache/pbuilder/aptcache> + +Specify the location that the packages downloaded by apt +should be cached. +Setting this value to "" will cause caching to be +turned off. + +=item B<APTCACHEHARDLINK=>I<yes> + +Specify using hard links in apt cache handling. Changing this to no will +disable hard linking and will copy the files. + +It is advised to set this to B<no> if you are using user-mode-linux. + +=item B<APTCONFDIR=>I</etc/apt> + +Configures where the apt configuration files are copied from. By default, this +value is empty, allowing the usual configuration options to take effect. +Setting this variable overrides other options. + +=item B<ARCHITECTURE=>I<`dpkg --print-architecture`> + +Specifies the B<build architecture> (as described in B<dpkg-architecture>(1)). +It'll be the architecture used when creating the chroot, defaults to the system +one. The supported values are the ones debootstrap supports. + +=item B<AUTOCLEANAPTCACHE=>I<yes> + +Always run with B<--autocleanaptcache> option. + +=item B<AUTO_DEBSIGN=>I<yes> + +When this value is set to yes, B<pdebuild> will invoke debsign command after +building. + +=item B<BASETGZ=>I</var/cache/pbuilder/base.tgz> + +Specifies the default location for the archived chroot image to be created and +used. This is overridden with the option B<--basetgz>. + +=item B<BINDMOUNTS=>I<directories-to-bind-mount[:internal-mountpoint]> + +When this value is set, pbuilder will mount these directories using bind-mount. +Different directories are space separated, a column can optionally specify a +mount destination inside the chroot. + +Do not bind-mount B</>. + +An Example: + + BINDMOUNTS="/home /mnt/test /home/joe/repo:/var/repo" + +=item B<BUILDDIR=>I</build> + +The directory inside the chroot where the build happens. This directory will +contain the build products; the source packages will be unpacked in a +subdirectory therein contained, named I<$srcpkg>-I<$ver>, with I<$ver> being +the upstream part of the version, without epoch and debian revision. + +Attention! Some directories -- such as F</tmp> -- are not safe to use since +they can be world-writable, and external users can temper with the build +process. + +=item B<BUILDPLACE=>I</var/cache/pbuilder/build/> + +The default place which the chroot is constructed. B<pbuilder> will use the +directory B<$BUILDPLACE$$>. which means, that it will use the directory and +the PID to determine the directory to use. This should obtain an unique +directory for concurrent runs of pbuilder in one machine. This is not +guaranteed to happen on network shared drives, so be aware of this fact when +playing with this option on NFS shared beowulf clusters. Change it to +something like I</var/cache/pbuilder/build/$HOSTNAME/> when doing such a thing. + +B<pbuilder clean> cleans up this directory. + +=item B<BUILDRESULT=>I</var/cache/pbuilder/result/> + +Specify the default directory which the build result will be copied over to +after the building. + +Unlike the B<--buildresult> command-line option the path is not canonicalized, +so you should specify a full path, not a relative path. + +=item B<EATMYDATA=>I<no> + +Enable or disable the builtin eatmydata support. + +For this to work the library of the same architecture as the one inside the +chroot has to be installed in the host. + +=item B<CCACHEDIR=>I<> + +Specifies where ccache will keep its cached compiler output. If this is +specified, ccache will be installed upon pbuilder create or pbuilder update, +I</usr/lib/ccache> will be prepended to the B<PATH>, B<CCACHEDIR> will be +bind-mounted in the chroot, and B<CCACHE_DIR> (ccache variable) will be set to +B<CCACHEDIR>. Note that files in B<CCACHEDIR> are chowned to B<BUILDUSERID> +(1234 by default). + +I<ccache> is disabled by default. + +=item B<BUILDRESULTUID=>, B<BUILDRESULTGID=> + +Set the UID and GID of the files built as result. They probably need to be set +to numeric UID values, so that it works the same inside the chroot and outside +the chroot. + +If sudo is used, the values specified by sudo is used. They are B<SUDO_UID>, +and B<SUDO_GID>. The default value is B<0> + +=item B<BUILDSOURCEROOTCMD=>I<fakeroot> + +This option is used on invocation of fakeroot for B<dpkg-buildpackage> in +B<pdebuild> + +=item B<BUILDUSERID=>I<1234> + +The uid to be used inside chroot. It should ideally not collide with user-id +outside the chroot, to avoid user inside chroot having access to processes +owned by the user id outside the chroot. + +=item B<BUILDUSERNAME=>I<pbuilder> + +The user name of the user the build will run as. Specifying this will enable +the use of fakeroot inside pbuilder. + +Note that this will require fakeroot to be installed within the chroot, and +fakeroot will automatically be installed. And B<-rfakeroot> will be added to +B<DEBBUILDOPTS> + +=item B<COMPONENTS=>I<main> + +Specify the default distribution components to use. This option is +space-delimited, use quotes when listing multiple components. This option only +affects when doing B<pbuilder create> or when B<--override-config> is specified +for B<pbuilder update> option. + +=item B<COMPRESSPROG=>I<gzip> + +Program to use for compression of the base.tgz. The default is to use gzip, +and any program that can be used to compress data using a pipe can be used. + +If set to "pigz", compression and decompression is gzip compatible but will use +all available CPUs. + +If set to "cat", there will be no compression at all (so +compression/decompression will be a lot faster but takes much more space on the +disk). + +=item B<export http_proxy=>I<http://your-proxy:8080/> + +Defines the proxy for http connection. + +=item B<export DEBIAN_BUILDARCH=>I<athlon> + +Uses this variable as B<DEBIAN_BUILDARCH>. This trick can be used for other +environmental variables as well. + +=item B<DEBBUILDOPTS=>I<> + +The options given here will be passed on to B<dpkg-buildpackage>. This can be +useful e.g. for binary-only builds. The command-line option B<--debbuildopts +will be appended to any contents specified here but> may also be used to reset +the list of options. + +The default value is to build source and binary package. + +=item B<DEBOOTSTRAPOPTS=>I<( '--variant=buildd' '--keyring' '/usr/share/keyrings/debian-archive-keyring.gpg' )> + +When this option is set to B<--variant=buildd> B<pbuilder> will invoke +B<$DEBOOTSTRAP> with B<--variant=buildd> option, which results in debootstrap +creating a minimal chroot for buildd instead of trying to create a minimal +installation chroot. B<--keyring> is used to specify a keyring for +debootstrap. + +=item B<APTKEYRINGS=>I<()> + +Additional keyrings to use for package verification with apt, not used for +debootstrap (use B<$DEBOOTSTRAPOPTS>). Use this to add (local) signed +repositories. By default the debian-archive-keyring package inside the chroot +is used. + +Keyrings are copied into F</etc/apt/trusted.gpg.d> in the chroot. APT supports +it since version 0.7.25.1, firstly available in the Debian release codenamed +"squeeze" (released on 2011). For older chroots, use a B<G> hook to run +B<apt-key> manually. + +=item B<DEBOOTSTRAP=>I<debootstrap> + +Use this option to switch the implementation of debootstrap. Known +implementations of debootstrap are B<cdebootstrap> and B<debootstrap> + +=item B<export DEBIAN_FRONTEND=>I<noninteractive> + +Sets interactiveness of pbuilder run. Setting this value to blank will cause +the pbuilder run to be interactive. Change this value when noninteractive +upgrades do not work. + +=item B<DISTRIBUTION=>I<sid> + +Specify the default distribution to use. This option only affects when doing +B<pbuilder create> or when B<--override-config> is specified for B<pbuilder +update> option. + +=item B<EXTRAPACKAGES=>I<>B<ccache lintian XXX>I<> + +Specifies extra packages which the system should install in the chroot on +B<pbuilder create>. This is a space-delimited list. Also this is installed on +B<pbuilder update> + +=item B<HOOKDIR=>I</usr/lib/pbuilder/hooks> + +Specifies the default location for the user hooks directory. This is +overridden with the option B<--hookdir>. + +If this is specified, hooks are searched for in the chroot, when running +B<pbuilder>. If it is not defined, or is an empty string, hooks are not +executed. + +For details, see L<pbuilder(8)> + +=item B<LOGLEVEL=>I<I> + +Specify how much output you want from pbuilder, valid values are B<E> (errors +only), B<W> (errors and warnings), B<I> (errors, warnings and informational) +and B<D> (everything including some debug messages). + +=item B<USECOLORS=>I<auto> + +Specify whether you'd like to see colored output from pbuilder. Valid values +are B<auto> (to try to automatically detect whether the terminal supports +them), B<yes> (to always use colors), and B<no> (to never use colors). + +=item B<MIRRORSITE=>I<http://www.jp.debian.org/debian> + +Specify the mirror site which contains the main Debian distribution. + +Note that you cannot really use B<file:/> kind of URL, because the location +needs to be accessible from within the chroot. + +=item B<OTHERMIRROR=>I<deb http://xxx/xxx/ ./ >B<[|>I< other deb lines... >B<]> + +The lines which is added to the sources.list, delimited with B<|> Like: + +B<deb http://local/mirror sid main|deb file:/usr/local/mirror ./> + +The deb lines here are the ones that will appear at the top of the +F<sources.list> inside the chroot. Be sure to follow the syntax rules of +L<sources.list(5)>. These lines appear at the beginning of the constructed +sources file, so this is the place to list your B<local> mirror sites; apt will +then use them in preference to the ones listed in B<MIRRORSITE>. + +To make changes on mirror site effective on B<update>, the option +B<--override-config> needs to be specified. + +=item B<PDEBUILD_PBUILDER=>I<pbuilder> + +Specify what pbuilder implementation to use for pdebuild. The currently +possible values are B<pbuilder> and B<cowbuilder> + +=item B<PKGNAME_LOGFILE_EXTENSION=>I<_$(dpkg --print-architecture).build> + +The extension of filename used in pkgname-logfile option. + +=item B<PKGNAME_LOGFILE=>I<yes> + +Always run with B<--pkgname-logfile> option, and create a logfile named after +the package name. + +=item B<PBUILDERROOTCMD=>I<sudo -E> + +This option is used on invocation of B<pbuilder build> in B<pdebuild> + +=item B<PBUILDERSATISFYDEPENDSCMD=>I</usr/lib/pbuilder/pbuilder-satisfydepends> + +This option is used by various parts of pbuilder to satisfy (i.e. install) the +build-dependencies of a package. These are the available implementations: + +=over + +=item I<pbuilder-satisfydepends-apt> + +the newest implementation, which leverage the ability of apt 1.4 to satisfy +build dependencies and build conflicts from a .dsc; useful since it's pretty +fast and doesn't require the installation of any non-required package in the +chroot, nor of dummy packages. + +=item I<pbuilder-satisfydepends-experimental> + +might be useful to pull packages from repositories with a low APT Pin Priority +(for example, Debian's experimental or stable-backports). + +=item I<pbuilder-satisfydepends-aptitude> + +will resolve build-dependencies and build-conflicts with aptitude which helps +dealing with complex cases but does not support unsigned APT repositories. + +=item I<pbuilder-satisfydepends-gdebi> + +will resolve build-dependencies using gdebi, faster than classic implementation, +and does not require installation of a dummy package like the aptitude +implementation. + +=item I<pbuilder-satisfydepnds-classic> + +the "classic" implementation, which was the original implementation used by +default until v0.172. + +=back + +The default is now "aptitude". + +=item B<PBUILDERSATISFYDEPENDSOPT=>I<()> + +Array of flags to give to pbuilder-satisfydepends. + + +=item B<SOURCE_ONLY_CHANGES=>I<yes> + +Specify whether to generate an additional .changes file for a source-only +upload, whilst still producing a full .changes file for any binary packages +built. + + +=item B<ALLOWUNTRUSTED=>I<no> + +Allow untrusted (no key installed) and unsigned repositories. + +B<Warning:> +Enabling this option may allow remote attackers to compromise the system. +Better use signed repositories and B<$APTKEYRINGS> to add the key(s). + +=item B<APTGETOPT=>I<()> + +Extra flags to give to apt-get. + +=item B<APTITUDEGETOPT=>I<()> + +Extra flags to give to aptitude. + +=item B<DEBDELTA=>I<no> + +Enable use of debdelta to download the needed updated in the chroot, if +debdelta is already installed. + +=item B<REMOVEPACKAGES=>I<lilo> + +Specify the packages to be removed on creation of F<base.tgz> Leaving lilo in +the chroot is like keeping a timebomb... + +=item B<TIMEOUT_TIME=>I<2h> + +Sets timeout time. +Build will be stopped with SIGTERM after the set time. + +=item B<USEDEVFS=>I<no> + +Whether to mount a devfs or not. Has no effect on kFreeBSD, as a devfs (and +fdescfs for F</dev/fd>) is always used. + +=item B<USEDEVPTS=>I<yes> + +Specify B<yes> when it is desired to mount F</dev/pts> interface. It is usually +a good idea, since there are many software which fail miserably when there is +no B</dev/pts> being mounted. + +=item B<USESYSFS=>I<yes> + +Whether to mount a sysfs (linsysfs for kFreeBSD) in F</sys> or not. Has no +effect on GNU/Hurd hosts, where sysfs is not available. It is usually a good +idea, since there are several software which require B</sys> being populated. + +=item B<USENETWORK=>I<no> + +Specify B<yes> when you do not want to disable network access during build. +Network is not available on a Debian buildd, so you might want to keep the +default. Disabling network access currently only works on Linux. + +=item B<USECGROUP=>I<yes> + +Specify B<yes> to use a cgroup to isolate build processes, so that any stray +processes from the build can be cleaned up afterwards. This currently only +works on Linux systems running systemd. + +=item B<USESHM=>I<yes> + +Specify B<yes> when it is desired to mount F</dev/shm> mount point. It is +usually a good idea in order to work with software that expects shm to work. +F</run/shm> will be configured as a symbolic link to F</dev/shm>. + +This option used to be named B<USERUNSHM>, for compatibility purpose the old +name is still supported, and if set it'll override any B<USESHM>. + +Has no effect on GNU/Hurd hosts due to bugs in F</hurd/tmpfs>; since /dev is +always bind-mounted, the host's F</dev/shm> will be used. + +=item B<USE_PDEBUILD_INTERNAL=>I<yes> + +When this option is set to I<yes>, the B<pdebuild-internal> implementation of +B<pdebuild> is used. + +=item B<USEPROC=>I<yes> + +Specify B<yes> when it is desired to mount B</proc> interface. It is usually a +good idea, since there are many software which fail miserably when there is no +B</proc> being mounted. + +=item B<ADDITIONAL_BUILDRESULTS=>I<(foo \(dqbar*\(dq \(dqbaz\(rs biz\(dq)> + +Array of additional files to copy out of the build area. + +In case a wildcard is needed (e.g. B<*.changes>) quote it to have the wildcard +escaped and not expanded at configuration load time, but instead expanded at +run time when the additional build artifacts are exported. Spaces in file +names needs to be escaped by using a \(rs or a wildcard to match the space. + + +=item B<CONFDIR=>I</etc/pbuilder/conf_files> + +B<pbuilder> copies some configuration files (like F</etc/hosts> or +F</etc/hostname>) from the host system into the chroot. If the directory +specified here exists and contains one of the copied files (without the leading +/etc) that file will be copied from here instead of the system one. + +=item B<BUILD_HOME=>I</nonexistent> + +Set the what the B<HOME> environment variable points to during the builds. It +defaults to a non-existing directory to prevent builds from writing to HOME, +which is reserved to users. If you need a working HOME you can set it to +B<$BUILDDIR> instead. + +=item B<BINNMU_MAINTAINER=>I<> + +Set the value of the maintainer name and email in the changelog during binNMU. +Such value is then copied to the Changed-By field of the .changes file. Can be +set at run time with the B<--bin-nmu-maintainer> command line option. + +=back + +=head1 AUTHOR + +Initial coding, and main maintenance is done by +Junichi Uekawa <dan...@debian.org>. +User hooks code added by Dale Amon <a...@vnl.com> + +The homepage is available at +L<https://pbuilder-team.pages.debian.net/pbuilder/> + +=head1 FILES + +F</etc/pbuilderrc>, F<$HOME/.pbuilderrc> + +=head1 SEE ALSO + +F</usr/share/doc/pbuilder/pbuilder-doc.html>, +L<cowbuilder(8)>, +L<pbuilder(8)>, +L<pdebuild(1)> + diff --git a/pdebuild.1 b/pdebuild.1 deleted file mode 100644 index 66231a45..00000000 --- a/pdebuild.1 +++ /dev/null @@ -1,205 +0,0 @@ -.TH "pdebuild" 1 "2006 May 24" "Debian" "pbuilder" -.SH NAME -pdebuild \- pbuilder way of doing debuild -.SH SYNOPSIS -.BI "pdebuild [" "pdebuild options" "] \-\- [" "pbuilder options" "]" -.PP -.SH DESCRIPTION -A convenience program for -.B "pbuilder" -which invokes pbuilder after obtaining appropriate root privilege -in a Debian source directory. -One must be inside the source tree containing the -.B "debian" -directory. - -By default, build log file is stored in ../<package>_<version>_<arch>.build. - - -.SH "PDEBUILD OPTIONS" - -The options have the form -.BI "\-\-" "option name" -which modify the operation semantics as explained below. They are -applied from left to right, and when options conflict, the option that -appear later take precedence. - -.TP -.BI "\-\-buildsourceroot [" "fakeroot" "]" -The command used to gain root privilege for -invoking -.B "debian/rules clean" - -.TP -.BI "\-\-pbuilderroot [" "sudo -E" "]" -The command used to gain root privilege for -invoking pbuilder. - -.TP -.BI "\-\-pbuildersatisfydepends [" "/usr/lib/pbuilder/pbuilder-satisfydepends" "]" -The command used to satisfy (i.e. install) build-dependencies. - -.TP -.BI "\-\-architecture" - -Set architecture. This is currently required when it doesn't match the host -architecture. - -.TP -.BI "\-\-auto\-debsign" - -Invoke debsign at the end of pdebuild process. - -.TP -.BI "\-\-debsign\-k [" "key\-id" "]" -Pass -.B \-k -option to debsign to specify which key-id to sign with. - -.TP -.BI "\-\-buildresult [" "Directory for build results" "]" - -The place where the build result is stored. - -Note that for pdebuild, buildresult needs to be specified as a pdebuild -option on the command-line, not as a pbuilder option. - -Note that the default value for buildresult is what is defined for -pbuilder, which is -.B "/var/cache/pbuilder/result" -and not -.B ".." - -.TP -.BI "\-\-configfile [" "Extra config file to use" "]" - -The configuration file is used, and passed on to -.BR "pbuilder" . - -.TP -.BI "\-\-debbuildopts [" "options to pass to dpkg-buildpackage" "]" - -The space-delimited list of options are passed to dpkg-buildpackage. -This option appends to pbuilder option -.B "\-\-debbuildopts" -and may also be used to reset the list of options by passing the empty -string. - -Multiple options are delimited with spaces. - -Note that for pdebuild, -.B "dpkg-source" -is used to build the source package which is given to pbuilder. This option has -no effect on the arguments used to build this source package, but will control -whether the -.B "clean" -target is run first as usual, and any options for dpkg-genchanges will be -passed on. - -.TP -.BI "\-\-use\-pdebuild\-internal" -Uses a different implementation of pdebuild, which calls clean and build inside -the chroot, using bind-mounts. - -.B "pdebuild\-internal" -tries to run debian/rules clean inside the chroot. -To do so, the working directory is passed on inside the chroot, -in the form of bind-mounting and -.B debuild -is run. - -This option will not protect the working directory and its parent directories -from the build scripts. - -.TP -.BI "\-\-logfile [" "file to log" "]" -Specifies the build logfile to create. -The messages generated during execution will be written to the file, -as well as standard output. - -.TP -.BI "\-\-pbuilder [" "pbuilder" "]" -Specifies which command to invoke as pbuilder. - -.TP -.BI "\-\-help" - -Show a brief help message. - -.TP -.BI "\-\- [" "pbuilder options" "]" - -After the -.B "\-\-" -symbol, an arbitrary number of pbuilder options can be specified. -See pbuilder(8) for a full list of options. - - -There is an exception that -.B "\-\-buildresult" -needs to be specified as a pdebuild option before the -.B "\-\-" -in order to be effective. - -.SH "FILES" -.TP -.I "/etc/pbuilderrc" -The configuration file for pbuilder, used in pdebuild. - -.TP -.I "/usr/share/pbuilder/pbuilderrc" -The default configuration file for pbuilder, used in pdebuild. - -.TP -.I "${HOME}/.pbuilderrc" -Configuration file for pbuilder, used in pdebuild. It -overrides -.B /etc/pbuilderrc - - -.SH "EXAMPLES" - -.TP -.B "pdebuild" - -.nf -$ pwd -/home/dancer/DEBIAN/cowdancer/cowdancer -$ ls debian/rules -debian/rules -$ pdebuild -dh clean - dh_testdir - dh_auto_clean - dh_autoreconf_clean - dh_clean - . - . - . -dpkg-source: info: using source format '3.0 (native)' -dpkg-source: info: building cowdancer in cowdancer_0.84.tar.xz -dpkg-source: info: building cowdancer in cowdancer_0.84.dsc - . - . - . -.hy - -.SH "BUGS" - -pdebuild will accept all options that pbuilder accepts as pdebuild -option. However, unless the option is documented in the manual page, -it may be ignored. - -.SH "AUTHOR" -Initial coding and main maintenance is done by -Junichi Uekawa <dan...@debian.org>. - -The homepage is -.B "\%http://pbuilder.alioth.debian.org"; - -.SH "SEE ALSO" -.BR "/usr/share/doc/pbuilder/pbuilder-doc.html" ", " -.BR "pbuilder" "(8), " -.BR "pbuilderrc" "(5)" - -\" LocalWords: pdebuild pbuilder debuild debian debsign buildresult diff --git a/pdebuild.1.pod b/pdebuild.1.pod new file mode 100644 index 00000000..b53595da --- /dev/null +++ b/pdebuild.1.pod @@ -0,0 +1,187 @@ +.TH "pdebuild" 1 "2006 May 24" "Debian" "pbuilder" + +=pod + +=head1 NAME + +pdebuild - pbuilder way of doing debuild + +=head1 SYNOPSIS + +B<pdebuild [>I<pdebuild options>B<] -- [>I<pbuilder options>B<]> + +=head1 DESCRIPTION + +A convenience program for B<pbuilder> which invokes pbuilder after obtaining +appropriate root privilege in a Debian source directory. One must be inside +the source tree containing the F<debian> directory. + +By default, build log file is stored in +F<../E<lt>packageE<gt>_E<lt>versionE<gt>_E<lt>archE<gt>.build>. + + +=head1 PDEBUILD OPTIONS + +The options have the form B<-->I<option name> which modify the operation +semantics as explained below. They are applied from left to right, and when +options conflict, the option that appear later take precedence. + +=over + +=item B<--buildsourceroot [>I<fakeroot>B<]> + +The command used to gain root privilege for invoking B<debian/rules clean> + +=item B<--pbuilderroot [>I<sudo -E>B<]> + +The command used to gain root privilege for invoking pbuilder. + +=item B<--pbuildersatisfydepends [>I</usr/lib/pbuilder/pbuilder-satisfydepends>B<]> + +The command used to satisfy (i.e. install) build-dependencies. + +=item B<--architecture> + +Set architecture. This is currently required when it doesn't match the host +architecture. + +=item B<--auto-debsign> + +Invoke debsign at the end of pdebuild process. + +=item B<--debsign-k [>I<key-id>B<]> + +Pass B<-k> option to debsign to specify which key-id to sign with. + +=item B<--buildresult [>I<Directory for build results>B<]> + +The place where the build result is stored. + +Note that for pdebuild, buildresult needs to be specified as a pdebuild +option on the command-line, not as a pbuilder option. + +Note that the default value for buildresult is what is defined for pbuilder, +which is F</var/cache/pbuilder/result> and not F<..> + +=item B<--configfile [>I<Extra config file to use>B<]> + +The configuration file is used, and passed on to +B<pbuilder>. + +=item B<--debbuildopts [>I<options to pass to dpkg-buildpackage>B<]> + +The space-delimited list of options are passed to dpkg-buildpackage. This +option appends to pbuilder option B<--debbuildopts> and may also be used to +reset the list of options by passing the empty string. + +Multiple options are delimited with spaces. + +Note that for pdebuild, B<dpkg-source> is used to build the source package +which is given to pbuilder. This option has no effect on the arguments used to +build this source package, but will control whether the B<clean> target is run +first as usual, and any options for dpkg-genchanges will be passed on. + +=item B<--use-pdebuild-internal> + +Uses a different implementation of pdebuild, which calls clean and build inside +the chroot, using bind-mounts. + +B<pdebuild-internal> tries to run debian/rules clean inside the chroot. To do +so, the working directory is passed on inside the chroot, in the form of +bind-mounting and B<debuild> is run. + +This option will not protect the working directory and its parent directories +from the build scripts. + +=item B<--logfile [>I<file to log>B<]> + +Specifies the build logfile to create. The messages generated during execution +will be written to the file, as well as standard output. + +=item B<--pbuilder [>I<pbuilder>B<]> + +Specifies which command to invoke as pbuilder. + +=item B<--help> + +Show a brief help message. + +=item B<-- [>I<pbuilder options>B<]> + +After the B<--> symbol, an arbitrary number of pbuilder options can be +specified. See L<pbuilder(8)> for a full list of options. + +There is an exception that B<--buildresult> needs to be specified as a pdebuild +option before the B<--> in order to be effective. + +=back + +=head1 FILES + +=over + +=item F</etc/pbuilderrc> + +The configuration file for pbuilder, used in pdebuild. + + +=item F</usr/share/pbuilder/pbuilderrc> + +The default configuration file for pbuilder, used in pdebuild. + +=item F<${HOME}/.pbuilderrc> + +Configuration file for pbuilder, used in pdebuild. It +overrides F</etc/pbuilderrc> + +=back + +=head1 EXAMPLES + +=over + +=item B<pdebuild> + + $ pwd + /home/dancer/DEBIAN/cowdancer/cowdancer + $ ls debian/rules + debian/rules + $ pdebuild + dh clean + dh_testdir + dh_auto_clean + dh_autoreconf_clean + dh_clean + . + . + . + dpkg-source: info: using source format '3.0 (native)' + dpkg-source: info: building cowdancer in cowdancer_0.84.tar.xz + dpkg-source: info: building cowdancer in cowdancer_0.84.dsc + . + . + . + +=back + +=head1 BUGS + +B<pdebuild> will accept all options that pbuilder accepts as pdebuild +option. However, unless the option is documented in the manual page, +it may be ignored. + +=head1 AUTHOR + +Initial coding and main maintenance is done by +Junichi Uekawa <dan...@debian.org>. + +The homepage is +L<http://pbuilder.alioth.debian.org> + + +=head1 SEE ALSO + +F</usr/share/doc/pbuilder/pbuilder-doc.html>, +L<pbuilder(8)>, +L<pbuilderrc(5)> + -- 2.30.2
signature.asc
Description: PGP signature
