diff options
Diffstat (limited to 'debian/README.source')
| -rw-r--r-- | debian/README.source | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source new file mode 100644 index 0000000..f673249 --- /dev/null +++ b/debian/README.source @@ -0,0 +1,187 @@ +Building the Debian Perl package +================================ + +Patches Applied +---------------- + +A copy of all patches which have been applied to the source are in the +debian/patches directory of the Debian source package. + +There are two classes of patches in the directory: debian/patches/fixes/* are +generally applicable to any Perl installation (and usually back-ported +from upstream, or posted to p5p when applied). + +Patches in debian/patches/debian implement changes which are specific to +the Debian packaging, such as our @INC ordering or specific to policy +such as not including standard directories in LD_RUN_PATH. + +Packaging Details +----------------- + +The Debian build process consists of the following components: + + debian/rules + makefile which drives the build process as usual with Debian packages. + This has been converted to use debhelper starting with version 5.30.0-2. + + debian/config.debian + a helper script, invoked by debian/rules to run Configure with + various options. + + debian/config.over + used to fiddle some config.sh variables (copied to the source + directory by the build process where it is picked up by Configure). + + debian/patches + directory containg the patches applied (see above). These are maintained + with git-debrebase, but if a standalone way to add a new patch is needed + (for instance when NMUing), the recommended way is to use quilt(1). + Using DEP-3 compatible headers for the patch will improve its description + in `perl -V' output. See below for more information about using + git-debrebase. + + quilt new debian/myfix + quilt add <file> + [ hack <file> ] + echo 'patch description (Closes: #xxxxxx)' | quilt header -a + # (or even better provide a full DEP-3 compatible header) + quilt refresh + + debian/released-versions + contains a list of released Debian versions, used by the + debian/mkprovides script to generate a list of perlapi-<ver> + provides for perl-base indicating the released versions the package + is compatible with. + + debian/headers + list of C headers to process with h2ph, which is run with "-a" to + pick up any required includes--keep this base list as short as + possible. + +Managing debian/patches with git-debrebase +------------------------------------------ + +This section is targeted at the Debian package maintainers, working with +the Git repository pointed by the Vcs-Git field in debian/control. NMUers +and the like can use the old way of standalone patch handling described +above, or just hack the source and ignore debian/patches altogether. + +First, you need to be running buster or later, and have the 'git-debrebase' +package installed. + +Then, follow the guide at dgit-maint-debrebase(7) ("EDITING THE DELTA QUEUE") +<https://manpages.debian.org/stretch-backports/dgit/dgit-maint-debrebase.7.en.html#EDITING_THE_DELTA_QUEUE> + +tldr; git-debrebase -i to edit the patch queue + +In addition, ensure you add the necessary metadata in the commit message: + + Gbp-Pq: Topic {fixes,debian} + Gbp-Pq: Name my_fix_name.diff + +IMPORTANT: any time you have been working with debrebase (for example +to import a new upstream release, or edit any file outside debian/) +ensure that you run the following commands before pushing: + + git debrebase conclude + git-debrebase make-patches # or dgit build-source + +If you omit the former command, you will be unable to fast-forward-push. +If you omit the latter, then the repository will not accurately represent +the state of the package which will be a a problem for consistency and +historical accuracy. + +Note that at the moment the perl maintainers are considering the use of dgit for +building and uploading as optional (and yet to be documented). Continue to +build and upload using your preferred methods in the meantime. + +Importing new upstream releases +------------------------------- + +Assuming you are importing a new major upstream release and +have the files perl_5.31.0.orig.tar.xz and +perl_5.31.0.orig-regen-configure.tar.gz in the parent directory +(see below for information about the regen-configure component +tarball). + +# necessary due to https://bugs.debian.org/898026 +ln -s perl_5.31.0.orig-regen-configure.tar.gz perl_5.31.0.orig-regen-configure.tar.xz +cd perl +git branch upstream-debian-5.31 upstream-debian-5.30 +git branch debian-5.31 debian-5.30 +gbp import-orig --upstream-version 5.31.0 --upstream-branch upstream-debian-5.31 --debian-branch debian-5.31 --component regen-configure --no-merge ../perl_5.31.0.orig.tar.xz +git debrebase new-upstream 5.31.0 +# possibly resolve conflicts +git diff debian/5.30.0-1..HEAD . ':!debian' # review changes +# hack on code, add other patches, etc +# before pushing +git debrebase conclude +git debrebase make-patches + +Package maintainer tests +------------------------ + +There are package maintainer tests in the debian/t/ directory that +are supposed to pass at all times. It is recommended that you add +a git pre-commit hook (.git/hooks/pre-commit) that runs the tests +before releasing, for instance: + +#!/bin/sh + +if [ -e debian/changelog ] && \ + git diff --cached debian/changelog | grep -q '^-.*UNRELEASED' && \ + git diff --cached debian/changelog | grep -q '^\+.*unstable' +then + prove debian/t/*.t +fi + +A special note on patching Configure +------------------------------------ + +The Configure and config_h.SH files are autogenerated upstream. The +tooling is based on the 'dist' suite, which (among other things) contains +a collection of probe units and a program called 'metaconfig' that makes +the Configure script. Since 5.26.1-1, the perl source package contains +a fork of these 'dist' probe units along with a set of specialised ones +specific to the Perl Configure. These are in a separate original tarball +component ('perl-regen-configure'). + +The recommended way to change Configure is to edit these units in +regen-configure/U and run 'debian/rules update-configure' to regenerate +Configure. + +(There is also some upstream machinery (mkgloss*, mksample) for +automatically updating Porting/config.sh and Porting/Glossary that is +not integrated to the Debian packaging. These only affect the source +code documentation, not functionality.) + +Please see <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=762638> +for a discussion about this issue. + +Regenerating the 'perl-regen-configure' original component tarball +------------------------------------------------------------------ + +This is a snapshot of the upstream git repository at +<https://github.com/perl5-metaconfig/metaconfig>, generated based on +information in debian/watch and debian/copyright (Files-Excluded). +It can be regenerated by running uscan(1), which uses mk-origtargz(1) +behind the scenes. + +The initial packaging for 5.26.1 was based on upstream +commit d99ddb45cefcc4ae5fde1787cfbe18e1073f9f54, tagged +as debian/perl-5.26.1 in the above repository. + +Credits +------- + +Previous maintainers of Debian Perl packages: + + Ray Dassen <jdassen@WI.LeidenUniv.NL>, + Carl Streeter <streeter@cae.wisc.edu>, + Robert Sanders <Robert.Sanders@linux.org> and + Darren Stalder <torin@daft.com>. + + -- Brendan O'Dea <bod@debian.org> Tue, 8 Mar 2005 19:30:38 +1100 + + -- Niko Tyni <ntyni@debian.org> Wed, 03 Feb 2010 14:47:51 +0200 + |