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
|
This package provides documentation for Debian's GNU Compiler Collection
packages.
Problem is the documentation is GFDL-licensed, and does contain invariant
sections. This makes the documentation files undistributable by Debian.
Policy is to have only unmodified upstream files in .orig.tar.gz file.
Everything else is added in the Debian source package files.
The .orig.tar.gz file is generated by a Python script which basically
greps through the upstream tarball for the documentation sources. This
has to be redone for *every* new upstream release.
The gcc-X.Y-doc(-non-dfsg) Debian package adds a Makefile and Debian
packaging files to that 'upstream' archive. Also, it applies several patches
on the 'upstream' files, for several reasons:
- Since Debian routinely carries multiple versions of GCC simultaneously,
we rename the .info files so that they can coexist as well, which requires
that cross-references be adjusted accordingly.
- Since Debian GCC differs from upstream GCC, some changes to documentation
are needed as well.
- Sometimes additional patching is required to make documentation build from
source.
Patches are managed using the "3.0 (quilt)" source format. See
<http://wiki.debian.org/Projects/DebSrc3.0> for more information on
how to work with this source format.
Debian GCC maintainers kindly provide required documentation patches under
debian/gcc/patches/ directory in the Debian gcc-X.Y source package. This
information may be converted to patches for gcc-X.Y-doc-non-dfsg using
debian/convert-debian-gcc-diff perl script. For reference, each released
version of gcc-X.Y-doc-non-dfsg contains saved convert-debian-gcc-diff
command-line in convert-debian-gcc-diff_cmdline-{version} file.
If adding a new patch, better to name it starting from aNN (if it should
be applied before from-debian-gcc-* patches), or zNN (if it should be applied
after from-debian-gcc-* patches). Also better not to touch from-debian-gcc-*
patches by hand and use debian/convert-debian-gcc-diff script instead.
Updating to a new upstream release includes the following steps:
- Create a changelog entry with the new version number and package
name.
- If updating to a new X.Y release, bump the version numbers in
debian/watch and debian/gbp.conf accordingly.
- Run "debian/rules get-orig-source", which will generate the new
.orig.tar.gz from the upstream tarball using the
debian/extract-doc-tarball-from-upstream script. (This script contains a
list of regexes for selecting files from upstream tarball.)
- Switch to the new upstream tarball, preferably using
git-import-orig(1). (You'll have to stash any uncommitted changes.)
- Update debian/Makefile to build any newly-referenced documents,
and the various <package>.{docs,doc-base.*,info,links,manpages}
files to install and register them appropriately.
- Also follow the instructions below for syncing with a new Debian package
release.
- If updating to a new X.Y release, you must also rename all packages
in debian/control whose names should contain X.Y,
Syncing against a new Debian package release includes the following steps:
- check what .texi files are modified by patches from Debian GCC source
package; don't forget that:
- If .texi modification is in the same patch file as other modifications,
it will be commented out (because .texi files are not there in debian
version of gcc source) - however uncommenting will be handled by
debian/convert-debian-gcc-diff script.
FIXME/Update: gcc-4.6 don't seem to have such partially commented patches,
instead, it's separating doc patches to separate files.
- Not all patches from debian/patches/ are applied to debian packages,
so it's necessary to check debian/rules to find out what is applied and
what is not.
(Some of this information is included in the
/usr/share/doc/gcc-X.Y-base/README.Debian.<arch>.gz file provided by the
gcc-X.Y-base package, but this will miss architecture-specific patches that
don't apply to the <arch> architecture.)
- The role of debian/rules is split over many files in gcc-X.Y, and info
about patch is in rules.patch and rules.defs.
- A helper, check_gcc_patches, is provided to inspect the patches, read its
source for usage. It greps through debian/rules.patch for relevant info,
and you need also read debian/rules.defs for various variable definitions.
- construct a new debian/convert-debian-gcc-diff command line and execute it,
- replace saved debian/convert-debian-gcc-diff command line with the new one,
- check that package builds without any warnings! if not, find out what's
wrong and fix it.
It would be good to check the links in the HTML files from time to
time. Something like the following zsh command might be useful for
this:
% checklink $((for i in $(dcmd --deb gcc-4.6-doc_4.6.3-1\~naesten6_i386.changes); dpkg-deb --fsys-tarfile $i) | tar -ti | grep '\.html$' | cut -c2-) > gcc-4.6-doc.checklink.txt
(Note that checklink comes from the w3c-linkchecker package.)
-- Samuel Bronson <naesten@gmail.com>, Fri, 30 Mar 2012 13:55:06 -0400
-- Nikita V. Youshchenko <yoush@debian.org>, Sun, 28 Sep 2008 19:40:54 +0400
|
