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
|
dh-exec
=======
[](https://travis-ci.org/algernon/dh-exec)
[Debhelper][1] (in compat level 9 and above) allows its config files
to be executable, and uses the output of such scripts as if it was
the content of the config file.
This is a collection of scripts and programs to help creating
such scripts in a standardised and easy to understand fashion.
This collection provides solutions for the following tasks:
* Expanding variables in various [debhelper][1] files (either from the
environment, or variables known to **dpkg-architecture**(1) -
including multi-arch ones)
* An extension to dh_install, that supports renaming files during the
copy process, using an extended syntax.
* Another extension to dh_install, allowing one to move a file to one package,
and copy the rest to another.
* Ability to filter files by architecture or build profile, within a
single debhelper control file.
[1]: https://tracker.debian.org/pkg/debhelper
Usage
=====
The recommended way to use dh-exec is through the **dh-exec**(1)
wrapper, which will bind all the other tools together. That is, when
adding a she-bang line to an executable debhelper config file, use
`/usr/bin/dh-exec`.
Using dh-exec means one will need to use debhelper compat level 9 or
above and executable debhelper config files: there is no extra support
needed in `debian/rules` or elsewhere, just an executable file with an
appropriate she-bang line.
Advantages
==========
One may of course question the existence of a seemingly complicated
tool, all for achieving some variable substitution, something one
could do with a here-doc and a shell script. However, one would be
gravely mistaken thinking that it's all dh-exec does and what it is
good for.
A few major advantages dh-exec has over custom here-doc or sed magic
tricks:
* A declarative syntax, familiar to everyone who used debhelper and
other debian tools.
One can employ architecture or build profile restrictions in
executable scripts just as one does in `debian/control`.
* A single tool that does the heavy lifting for you, just like
debhelper does.
Instead of repeating similar code across a number of packages, a
simple build-dependency on a helper tool gets you a lot more, for a
fraction of the price.
* It is reliable, stable and in active use.
As of this writing, there are over a hundred packages
build-depending on `dh-exec`, and using parts of its feature sets,
and the number keeps growing.
Examples
========
One of the most simple cases is expanding multi-arch variables in an
install file:
#! /usr/bin/dh-exec
usr/lib/*.so.* /usr/lib/${DEB_HOST_MULTIARCH}/libsomething.so.*
Of course, this has the disadvantage of running all dh-exec scripts,
so it will also try to expand any environment variables too. For
safety, one can turn that off, and explicitly request that only
multi-arch expansion shall be done:
#! /usr/bin/dh-exec --with-scripts=subst-multiarch
usr/lib/*.so.* /usr/lib/${DEB_HOST_MULTIARCH}/libsomething.so.*
/usr/share/doc/my-package/${HOME}-sweet-home
In this second case, the *${HOME}* variable will not be expanded, even
if such an environment variable is present when dh-exec runs.
But variable expansion is not all that dh-exec is able to perform!
Suppose we want to install a file, under a different name: with
dh-exec, that is also possible:
#! /usr/bin/dh-exec --with=install
debian/default.conf => /etc/my-package/start.conf
These can, of course, be combined. One can even limit scripts to
multiarch substitution and install-time renaming only, skipping
everything else dh-exec might try:
#! /usr/bin/dh-exec --with-scripts=subst-multiarch,install-rename
cfgs/cfg-${DEB_HOST_GNU_TYPE}.h => /usr/include/${DEB_HOST_MULTIARCH}/package/config.h
Additionally, assuming we have two binary packages: `foo-gtk` and `foo-utils`,
and we want to include `/usr/bin/foo-gtk` in the former package, the rest of
`/usr/bin` in the latter. Our install files would look like these, for `foo-gtk`
and `foo-utils` respectively:
#! /usr/bin/dh-exec
=> /usr/bin/foo-gtk
#! /usr/bin/dh-exec
/usr/bin/*
But wait, there's more! You can restrict lines based on architecture,
or build profile:
#! /usr/bin/dh-exec
[linux-any] usr/bin/linux-*
[!freebsd-any] lib/systemd/system/*
<stage1> usr/bin/compiler1
When not to use dh-exec
=======================
Do note that dh-exec is not required at all if all you want to do is
mark a multi-arch path as belonging to a package: debhelper itself
supports wildcards! So if your install script would look like the
following:
#! /usr/bin/dh-exec
usr/lib/${DEB_HOST_MULTIARCH}/libsomething.so.*
Then most likely, you do not need dh-exec, and you can replace the
above with this simple line:
usr/lib/*/libsomething.so.*
Similarly, all of the following can be simplified to using wildcards,
unless there's another directory under `/usr/lib` which one doesn't
want to install:
#! /usr/bin/dh-exec
usr/lib/${DEB_HOST_MULTIARCH}
usr/lib/${DEB_HOST_MULTIARCH}/pkgconfig/*.pc usr/lib/${DEB_HOST_MULTIARCH}/pkgconfig
--
Gergely Nagy <algernon@debian.org>
|
