← Back to branch summary

~ubuntu-branches/ubuntu/trusty/xorg/trusty-updates

« back to all changes in this revision

Viewing changes to xsf-docs/reference/dependencies.txt

  • Committer: Bazaar Package Importer
  • Author(s): Timo Aaltonen, Bryce Harrington, Timo Aaltonen
  • Date: 2011-06-14 15:39:40 UTC
  • mfrom: (6.3.18 sid)
  • Revision ID: james.westby@ubuntu.com-20110614153940-b9i0fr1v2kchiozh
Tags: 1:7.6+7ubuntu1
https://launchpad.net/bugs/480744
https://launchpad.net/bugs/778758
* Merge from Debian unstable, remaining changes:
  - Add apport hook
  - Demote xfonts-{75DPI,100DPI} to Suggests. Demote xfonts-scalable to
    Recommends.
  - debian/local/Xsession:
    Truncate xsession-errors on startup if too big
  - debian/local/Xsession.d/20x11-common_process-args:
    Add support for session command containing args.
  - debian/local/Xsession.d/60x11-common_localhost:
    Authorise all processes running with the user's credentials to connect
    to the server.
  - debian/rules, debian/control:
    Add dependencies on x11-common, and symlink /usr/share/doc directories
    of all packages to x11-common's.
  - debian/scripts/vars.*:
    + Don't drop wacom from input-all.
    + Add -vmmouse to input-all for amd64 and i386.
    + Add -qxl to video-all for amd64 and i386.
    + Add -geode to video-all for i386.
    + Drop video drivers that are likely irrelevant for ARM.
  - debian/xserver-xorg.postinst.in: Also migrate users from psb → vesa.

[ Bryce Harrington ]
* apport/source_xorg.py:
  - Move Failsafe-X out of the xorg package to xdiagnose
    (LP: #480744)
  - Simplify answers for bug reporters filing post-release reports.
    (LP: #778758)
  - Remove attach_drm_info().  This is useful info but we use it very
    infrequently, and it is already available in other log files.  But the
    call makes bug reports a bit cluttered since it adds a lot of lines to
    the report itself.

[ Timo Aaltonen ]
* rules: A stampfile generation was commented out by mistake, uncomment
  it.
* Rework the x11-common.{postinst,postrm,preinst} failsafe conffile
  handling, the previous ones added in 1:7.6+4ubuntu1 were wrong too.
* scripts/vars.{amd64,i386,powerpc}: Remove apm, ark, chips, i128, i740,
  rendition, s3virge, tseng, voodoo from xserver-xorg-video-all
  dependencies. They are unmaintained and obsolete.

Show diffs side-by-side

added added

removed removed

Lines of Context:
xsf-docs/reference/dependencies.txt
 
1
Dependencies between server and drivers
 
2
=======================================
 
3
:toc:
 
4
Cyril Brulebois <kibi@debian.org>
 
5
 
 
6
 
 
7
Upstream-side: ABI version numbers
 
8
----------------------------------
 
9
 
 
10
The X server defines several
 
11
http://en.wikipedia.org/wiki/Application_binary_interface[ABI] version numbers in the
 
12
`hw/xfree86/common/xf86Module.h` header, through the
 
13
`SET_ABI_VERSION(maj,min)` macro. In this document, the focus is on
 
14
`ABI_VIDEODRV_VERSION` and `ABI_XINPUT_VERSION`, which are
 
15
respectively about `video` drivers and `input` drivers.
 
16
 
 
17
An example of input ABI is `12.1`, `12` being the `major`, `1` being
 
18
the `minor`.
 
19
 
 
20
Like in usual shared libraries, the major is bumped when interfaces
 
21
are broken. There’s no compatibility at all in that case.
 
22
 
 
23
The minor gets bumped when interfaces are added. In other words, if a
 
24
driver is working with `x.y`, it should also work with higher minors:
 
25
`x.z`; `z>y`. The converse is not true, if a driver requires a given
 
26
minor (for example because it needs a new feature, like MultiTouch),
 
27
it won’t work with lower minors (which didn’t provide the needed
 
28
feature). Put another way: we have ascending compatibility with the
 
29
minors.
 
30
 
 
31
Conclusion: We need to keep track of both major and minor.
 
32
 
 
33
Thanks to `pkg-config` we can query them:
 
34
 
 
35
----
 
36
$ pkg-config --variable=abi_videodrv xorg-server
 
37
9.0
 
38
$ pkg-config --variable=abi_xinput xorg-server
 
39
12.1
 
40
----
 
41
 
 
42
<<<
 
43
Debian-side: Using virtual packages
 
44
-----------------------------------
 
45
 
 
46
Server’s build system
 
47
~~~~~~~~~~~~~~~~~~~~~
 
48
 
 
49
When `xorg-server` gets built, we use ++pkg-config++’s output to
 
50
determine the current major. Through substitution variables, we add
 
51
two virtual packages in the `Provides` field of the server (for both
 
52
`xserver-xorg-core` and `xserver-xorg-core-udeb`): `xorg-input-abi-$x`
 
53
and `xorg-video-abi-$y`, where `$x` and `$y` are the major part of the
 
54
version queried through `pkg-config` variables.
 
55
 
 
56
To handle ascending compatibility for minors, we maintain in
 
57
`debian/serverminver` the minimal version of `xserver-xorg-core` which
 
58
is needed. When a minor is bumped, we store the server version in that
 
59
file. This way, drivers built afterwards will depend on a *minimal*
 
60
version of the driver, the last which saw a minor version bump. In
 
61
other words: they will “depend on the server version they were built
 
62
against, or a higher/compatible one”.
 
63
 
 
64
Both ABI and minimal server version are recorded in two files shipped
 
65
in `xserver-xorg-dev`, to be used while building drivers:
 
66
 
 
67
   * `/usr/share/xserver-xorg/xinputdep`
 
68
   * `/usr/share/xserver-xorg/videodrvdep`
 
69
 
 
70
Example for `xinputdep`:
 
71
 
 
72
----
 
73
xorg-input-abi-11, xserver-xorg-core (>= 2:1.8.99.904)
 
74
----
 
75
To make sure we bump the `debian/serverminver` when there’s a minor
 
76
ABI change, there’s a `abibumpcheck` target (on which `clean`
 
77
depends), which extracts input and video ABI from the upstream header,
 
78
and compares them to the previous ones stored in
 
79
`debian/serverminver`, failing and diffing is something changed.
 
80
 
 
81
 
 
82
Driver’s control file
 
83
~~~~~~~~~~~~~~~~~~~~~
 
84
 
 
85
Drivers also use substitution variables in their control file,
 
86
replaced at build time.
 
87
 
 
88
----
 
89
# Input driver:
 
90
Depends: ${xinpdriver:Depends}, …
 
91
Provides: ${xinpdriver:Provides}
 
92
 
 
93
# Video driver:
 
94
Depends: ${xviddriver:Depends}, …
 
95
Provides: ${xviddriver:Provides}
 
96
----
 
97
 
 
98
For now, `${xinpdriver:Provides}` is always replaced with
 
99
`xorg-driver-input`, and `${xviddriver:Provides}` is always replaced
 
100
with `xorg-driver-video`. Hopefully provided packages will not change,
 
101
but using substitution variables is cheap, and makes it easy to add
 
102
tweaks afterwards if needed.
 
103
 
 
104
 
 
105
Driver’s build system
 
106
~~~~~~~~~~~~~~~~~~~~~
 
107
 
 
108
To set those variables, we ship a `dh_xsf_substvars` script in
 
109
`xserver-xorg-dev` starting with `2:1.9.4`, to be run before
 
110
`dh_gencontrol`. It iterates on the packages listed by
 
111
`dh_listpackages` (very old `debhelper` command) and does the
 
112
following work:
 
113
 
 
114
 * It reads variables from the files mentioned above.
 
115
 * If a package name ends with `-udeb`, it replaces
 
116
   `xserver-xorg-core` with `xserver-xorg-core-udeb`.
 
117
 * If a package name ends with `-dbg`, it does nothing for this
 
118
   package. Debug packages usually depend strictly on the non-debug
 
119
   packages, which in turn have appropriate dependencies.
 
120
 * If a package name starts with `xserver-xorg-input-`, it appends
 
121
   `xinpdriver:Depends=…` and `xinpdriver:Provides=…` to this
 
122
   package’s substvars file.
 
123
 * If a package name starts with `xserver-xorg-video-`, it appends
 
124
   `xviddriver:Depends=…` and `xviddriver:Provides=…` to this
 
125
   package’s substvars file.
 
126
 
 
127
Why such heuristics? The idea is to avoid getting “unused substitution
 
128
variable” warning messages while building. And since there’s a clear
 
129
`xserver-xorg-{input,video}-*` namespace, we can use that to specify
 
130
only input-related variables for input drivers, and only video-related
 
131
variables for video drivers.
 
132
 
 
133
To make it easy to compute substvars when using `dh`, a `dh` sequence
 
134
(`xsf.pm`) is shipped. As of `2:1.9.4-1`, it inserts
 
135
`dh_xsf_substvars` right before the `dh_gencontrol` call. Other
 
136
repetitive tasks could also be automated this way.
 
137
 
 
138
 
 
139
<<<
 
140
Sample driver packaging
 
141
-----------------------
 
142
 
 
143
The following assumes:
 
144
 
 
145
 * The upstream build system is sane enough, which lets us run
 
146
   `autoreconf` at build time.
 
147
 * It is a `video` driver. For an `input` driver, replace both
 
148
   `xviddriver` occurrences with `xinpdriver`.
 
149
 
 
150
Sample debian/control file
 
151
~~~~~~~~~~~~~~~~~~~~~~~~~~
 
152
 
 
153
----
 
154
Build-Depends:
 
155
 debhelper (>= 8),
 
156
 dh-autoreconf,
 
157
 quilt,
 
158
 xserver-xorg-dev (>= 2:1.9.4),
 
159
----
 
160
 
 
161
----
 
162
Depends:
 
163
 ${shlibs:Depends},
 
164
 ${misc:Depends},
 
165
 ${xviddriver:Depends},
 
166
Provides:
 
167
 ${xviddriver:Provides}
 
168
----
 
169
 
 
170
Sample debian/rules file
 
171
~~~~~~~~~~~~~~~~~~~~~~~~
 
172
 
 
173
----
 
174
#!/usr/bin/make -f
 
175
 
 
176
# Configuration:
 
177
#override_dh_auto_configure:
 
178
#        dh_auto_configure -- --with-FOO --without-BAR
 
179
 
 
180
# Install in debian/tmp to retain control through dh_install:
 
181
override_dh_auto_install:
 
182
        dh_auto_install --destdir=debian/tmp
 
183
 
 
184
# Kill *.la files, and forget no-one:
 
185
override_dh_install:
 
186
        find debian/tmp -name '*.la' -delete
 
187
        dh_install --fail-missing
 
188
 
 
189
## Debug package:
 
190
#override_dh_strip:
 
191
#        dh_strip --dbg-package=xserver-xorg-video-DRIVER-dbg
 
192
 
 
193
# That's a plugin, use appropriate warning level:
 
194
override_dh_shlibdeps:
 
195
        dh_shlibdeps -- --warnings=6
 
196
 
 
197
%:
 
198
        dh $@ --with quilt,autoreconf,xsf --builddirectory=build/
 
199
----
 
200
 
 
201
Some comments:
 
202
 
 
203
 * `dh_auto_configure`: Commented out since there’s usually no
 
204
   specific option to pass when building drivers. Sometimes needed to
 
205
   get a related utility built.
 
206
 * `dh_auto_install`: It behaves differently when operating on a
 
207
   single package (it installs under `debian/PACKAGE` instead of
 
208
   `debian/tmp`), so make it use `debian/tmp` in all cases. This way,
 
209
   `dh_install` has to be used (see below). That also means that a
 
210
   binary package (_e.g._ a debug package) can be added without
 
211
   changing this part.
 
212
 * `dh_install`: No point in keeping the `.la` files. Also, using
 
213
   `--fail-missing` makes sure every file installed by upstream is
 
214
   installed in some package, or explicitly ignored.
 
215
 * `dh_strip`: Commented out, there’s only a few drivers shipping a
 
216
   debug package.
 
217
 * `dh_shlibdeps`: The comment really says it all.
 
218
 * `dh`: The order is important! We want patching to happen before
 
219
   autoreconfiguring (both `quilt` and `autoreconf` insert commands
 
220
   before `dh_auto_configure`, and after `dh_clean`). Also, we build
 
221
   out-of-tree. The `xsf` sequence is explained in the previous part.
 
222
 
 
223
If one needs to build several flavours,
 
224
http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-fbdev.git;a=blob;f=debian/rules[++fbdev++’s rules file]
 
225
can be used as an example.
 
226
 
 
227
 
 
228
<<<
 
229
Staying tuned
 
230
-------------
 
231
 
 
232
Staying informed of driver-related changes can be a bit difficult in
 
233
the following cases:
 
234
 
 
235
 * If one maintains a single driver within the X Strike Force, one
 
236
   might not notice the few mails about drivers in the heavy mail flow
 
237
   on `debian-x@`.
 
238
 * If one maintains a driver outside the X Strike Force, one is
 
239
   probably not subscribed to the mailing list at all.
 
240
 
 
241
For those reasons, a mail alias is being set up to gather all
 
242
maintainers interested in receiving driver-related mails.