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
|
debputy - Integration modes
===========================
_This is [reference documentation] and is primarily useful if you want to know more on integration modes_
_If you want to migrate to one of these integration modes, then [GETTING-STARTED-WITH-dh-debputy.md](GETTING-STARTED-WITH-dh-debputy.md) might be better._
<!-- To writers and reviewers: Check the documentation against https://documentation.divio.com/ -->
The debputy tool is a Debian package builder, and it has multiple levels of
"integration" with the package build. Each integration mode has different
pros and cons, which will be covered in this document.
The integration modes are:
* `dh-sequence-zz-debputy-rrr`
* `dh-sequence-zz-debputy` (or `dh-sequence-debputy`)
* `full`
The integration modes that start with `dh-sequence-` are named such because
they leverage `dh` and its add-on system. The `dh-sequence-zz-` is a trick
to convince `dh` to load the add-ons last when they are activated via
`Build-Depends`, which is part of `debputy`'s strategy for maximizing
compatibility with other `dh` add-ons.
Integration mode - `dh-sequence-zz-debputy-rrr`
-----------------------------------------------
This integration mode is a minimal integration mode aimed exactly at removing the
(implicit) requirement for `fakeroot` in packages that need static ownership in
the `.deb`.
It trades many of `debputy` features for compatibility with `debhelper` and ease
of transitions.
This integration mode is relevant for you when:
* You want to get rid of the implicit `fakeroot` requirement, and you need static
ownership, OR
* You want to transition to `debputy` in the long term, but more involved integration
modes do not support what you need, OR
* The mode has a particular feature you want that `debhelper` does not provide.
Pros:
* You can use `debputy` to assign static ownerships without needing `fakeroot`,
which is not possible with `debhelper`.
* You get maximum compatibility with existing `dh` add-ons.
* Migration is generally possible with minimal or small changes.
* It is accessible in `bookworm-backports`
Cons:
* Many of `debputy`'s features cannot be used.
* Most limitations of `debhelper` still applies (though these limitations are the
status quo, so the package would have a solution to them if needed).
* You still longer a turning complete configuration language for your package helper
(`debian/rules`) with poor introspection.
To migrate, please use:
debputy migrate-from-dh --migration-target dh-sequence-zz-debputy-rrr
Note: The `debputy migrate-from-dh` command accepts a `--no-act --acceptable-migration-issues=ALL`,
if you want to see how involved the migration will be.
For documentation, please see:
* [GETTING-STARTED-WITH-dh-debputy.md] for a more detailed migration guide (how-to guide).
* https://wiki.debian.org/BuildingWithoutFakeroot
Integration mode - `dh-sequence-zz-debputy`
-------------------------------------------
This integration mode is a more involved integration mode of `debputy` that partly leverages
`dh`. In this mode, `debputy` will take over all the logic of installing files into the
respective package staging directories (`debian/<pkg>`). Roughly speaking, the original
`debhelper` runs until `dh_auto_install` and then `debputy` takes over.
This integration mode is relevant when:
* You want to migrate to the `full` integration mode, but you would like to split the migration
in two, OR
* You want to use more of `debputy`'s features and do not use any unsupported `dh` add-ons without
wanting to migrate the build part.
Pros:
* You can use the most features of `debputy`. Only the build and environment related ones are
not accessible.
* It is accessible in `bookworm-backports`
Cons:
* Almost all `dh` add-ons will stop working since they rely on being able to see the content
of `debian/<pkg>`. Since `debputy` will populate *and* assemble the `.deb`, there is never
a window for the affected add-on to work. Any features provided by these add-ons would have
to be provided by a `debputy` plugin (or `debputy` itself).
* Your only `debhelper` limitations is `dh` notorious lack of proper multi-build support.
* You still longer a turning complete configuration language for your package helper
(`debian/rules`) with poor introspection.
To migrate, please use:
debputy migrate-from-dh --migration-target dh-sequence-zz-debputy
Note: The `debputy migrate-from-dh` command accepts a `--no-act --acceptable-migration-issues=ALL`,
if you want to see how involved the migration will be. It will also detect possible incompatible
`dh` add-ons if you are concerned about whether your package can be supported.
For documentation, please see:
* [GETTING-STARTED-WITH-dh-debputy.md] for a more detailed migration guide (how-to guide).
Integration mode - `full`
-------------------------
This is the integration mode that `debputy` is about. In the `full` integration mode, `debputy`
replaces `dh` as the package helper. It even removes `debian/rules` replacing it with `dpkg`'s
new `Build-Driver` feature.
Pros:
* You can use all features from `debputy` including its native multi-build support.
* You can still leverage `debhelper` build systems (anything integrating with the `dh_auto_*`
tools.) via the `debhelper` build system.
* You no longer have a turning complete configuration language for your package helper
(`debian/rules`) with poor introspection.
Cons:
* (Temporary) Incomplete `debputy migrate-from-dh` support
* It is a new ecosystem missing a lot of the third-party features you would find for `dh`.
Only `debhelper` build systems (`dh_auto_*`) can be reused.
* It requires Debian `trixie` or later due to `Build-Driver` (`dpkg-dev`)
* You no longer have the flexibility of a turning complete configuration language for your
package helper, which some people might miss. :)
To migrate, please use:
debputy migrate-from-dh --migration-target full
Note: The `debputy migrate-from-dh` command accepts a `--no-act --acceptable-migration-issues=ALL`,
if you want to see how involved the migration will be. It will also detect possible incompatible
`dh` add-ons if you are concerned about whether your package can be supported.
[reference documentation]: https://documentation.divio.com/reference/
|
