35950e31b1e84744341b0f86447174245858968b
[perl/perl.git] / debian / README.source
1 Building the Debian Perl package
2 ================================
3
4 Build Options
5 -------------
6
7 In addition to the ``nostrip'' and ``noopt'' DEB_BUILD_OPTIONS
8 required by policy (10.1) the build process also recognises the
9 following perl-specific options:
10
11   x-perl-shared
12   x-perl-static
13     Select whether /usr/bin/perl is linked to the shared or static
14     perl library.  By default the link type is shared on all
15     architectures other than i386 (where the relocations incur a
16     measurable performance penalty).
17
18   x-perl-notest (or nocheck)
19     The regression test suite is normally run after each of the static
20     and shared build phases.  It is occaisionally useful to supress
21     these tests (when debugging the build process for example, or to
22     allow porters to work around known build chain or kernel bugs).
23
24 Patches Applied
25 ----------------
26
27 A copy of all patches which have been applied to the source are in the
28 debian/patches directory of the Debian source package.
29
30 There are two classes of patches in the directory: debian/patches/fixes/* are
31 generally applicable to any Perl installation (and usually back-ported
32 from upstream, or posted to p5p when applied).
33
34 Patches in debian/patches/debian implement changes which are specific to
35 the Debian packaging, such as our @INC ordering or specific to policy
36 such as not including standard directories in LD_RUN_PATH.
37
38 Packaging Details
39 -----------------
40
41 The Debian build process consists of the following components:
42
43   debian/rules
44     makefile which drives the build process as usual with Debian
45     packages.  This process is slightly more complex than normal to
46     simplify bootstrapping a new port--using only basic shell utils, and
47     perl (once built, as perl.static).  To bootstrap a new architecture,
48     use:
49
50       DEB_BUILD_GNU_TYPE=<arch> debian/rules binary-arch
51
52   debian/config.debian 
53     a helper script, invoked by debian/rules to run Configure with
54     various options.
55
56   debian/config.over
57     used to fiddle some config.sh variables (copied to the source
58     directory by the build process where it is picked up by Configure).
59
60   debian/patches
61     directory containg the patches applied (see above).  These are maintained
62     with git-dpm, but if a standalone way to add a new patch is needed 
63     (for instance when NMUing), the recommended way is to use quilt(1).
64     Using DEP-3 compatible headers for the patch will improve its description
65     in `perl -V' output.
66
67       quilt new debian/myfix
68       quilt add <file>
69       [ hack <file> ]
70       echo 'patch description (Closes: #xxxxxx)' | quilt header -a
71       # (or even better provide a full DEP-3 compatible header)
72       quilt refresh
73
74   debian/released-versions
75     contains a list of released Debian versions, used by the
76     debian/mkprovides script to generate a list of perlapi-<ver>
77     provides for perl-base indicating the released versions the package
78     is compatible with.
79
80   debian/headers
81     list of C headers to process with h2ph, which is run with "-a" to
82     pick up any required includes--keep this base list as short as
83     possible.
84
85   debian/*.{files{,.static,.shared},docs,moduledocs}
86     used to split packages; see the comments/code in the install-stamp
87     target of debian/rules.
88
89 Managing debian/patches with git-dpm 
90 ------------------------------------
91
92 This section is targeted at the Debian package maintainers, working with
93 the Git repository pointed by the Vcs-Git field in debian/control.  NMUers
94 and the like can use the old way of standalone patch handling described
95 above, or just hack the source and ignore debian/patches altogether.
96
97 First, you need to be running wheezy or later, and have the 'git-dpm'
98 package installed.
99
100 Any upstream modifications need to be done on a special 'patched' branch
101 that is created with 'git-dpm checkout-patched'. Every commit on this branch
102 corresponds to one patch in debian/patches. The commits can be handled
103 with normal git tools like 'git rebase -i'.
104
105 When everything is ready, 'git-dpm update-patches' will merge the work into
106 the master branch with the debian/ directory and remove the 'patched' branch,
107 which is not supposed to be pushed to the shared repository.
108
109 See the git-dpm(1) manual page for more information.
110
111 Package maintainer tests
112 ------------------------
113
114 There are package maintainer tests in the debian/t/ directory that
115 are supposed to pass at all times. It is recommended that you add
116 a git pre-commit hook (.git/hooks/pre-commit) that runs the tests
117 before releasing, for instance:
118
119 #!/bin/sh
120
121 if [ -e debian/changelog ] && \
122    git diff --cached debian/changelog | grep -q '^-.*UNRELEASED' && \
123    git diff --cached debian/changelog | grep -q '^\+.*unstable'
124 then
125     prove debian/t/*.t
126 fi
127
128 Credits
129 -------
130
131 Previous maintainers of Debian Perl packages:
132
133   Ray Dassen <jdassen@WI.LeidenUniv.NL>,
134   Carl Streeter <streeter@cae.wisc.edu>,
135   Robert Sanders <Robert.Sanders@linux.org> and
136   Darren Stalder <torin@daft.com>.
137
138  -- Brendan O'Dea <bod@debian.org>  Tue,  8 Mar 2005 19:30:38 +1100
139
140  -- Niko Tyni <ntyni@debian.org> Wed, 03 Feb 2010 14:47:51 +0200
141