1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
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.34.0.orig.tar.xz and
perl_5.34.0.orig-regen-configure.tar.xz in the parent directory
(see below for information about getting the regen-configure component
tarball).
cd perl
git branch upstream-debian-5.34 upstream-debian-5.32
git branch debian-5.34 debian-5.32
gbp import-orig --upstream-version 5.34.0 --upstream-branch upstream-debian-5.34 --debian-branch debian-5.34 --component regen-configure --pristine-tar --no-merge ../perl_5.34.0.orig.tar.xz
git debrebase new-upstream 5.34.0
# possibly resolve conflicts
git diff debian-5.32..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.
Cross build support
-------------------
The build system currently support cross builds by storing architecture
specific configuration information under the debian/cross/ directory in
the source package. This works around for the lack of cross configuration
support in the Configure script.
These cross build support files need to be refreshed for new
upstream versions, and whenever configuration options change. See
debian/cross/README for more information.
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.
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
|
