[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

xsf-docs: Changes to 'master'

 index.mdwn                  |    4 +
 reference/dependencies.mdwn |  131 ++++++++++++++++++++++++++++++++++++++++++++
 xsf.css                     |    5 +
 3 files changed, 140 insertions(+)

New commits:
commit dfb93d750512f99ecbbe8e7d97db97acb6641505
Author: Cyril Brulebois <kibi@debian.org>
Date:   Tue Feb 1 13:34:52 2011 +0100

    dependencies: New reference document.

diff --git a/index.mdwn b/index.mdwn
index f3e1efc..ab5e152 100644
--- a/index.mdwn
+++ b/index.mdwn
@@ -8,6 +8,10 @@
  * [How to configure input](howtos/configure-input.html)
  * [How to configure outputs](howtos/use-xrandr.html)
+## Reference documentation
+ * [Dependencies between server and drivers](reference/dependencies.html)
 ## Other documentation
  * [Upstream features](upstream-features.html)
diff --git a/reference/dependencies.mdwn b/reference/dependencies.mdwn
new file mode 100644
index 0000000..fa0e816
--- /dev/null
+++ b/reference/dependencies.mdwn
@@ -0,0 +1,131 @@
+# Dependencies between server and drivers
+Cyril Brulebois &lt;kibi@debian.org>
+## Upstream-side: ABI version numbers
+The X server defines several
+[ABI](http://en.wikipedia.org/wiki/Application_binary_interface) in
+`hw/xfree86/common/xf86Module.h`, through the
+`SET_ABI_VERSION(maj,min)` macro. In this document, the focus is on
+respectively about `video` drivers and `input` drivers.
+An example of input ABI is `12.1`, `12` being the `major`, `1` being
+the `minor`.
+Like in usual shared libraries, the major is bumped when interfaces
+are broken. There’s no compatibility at all in that case.
+The minor gets bumped when interfaces are added. In other words, if a
+driver is working with `x.y`, it should also work with higher minors:
+`x.z`; `z>y`. The converse is not true, if a driver requires a given
+minor (for example because it needs a new feature, like MultiTouch),
+it won’t work with lower minors (which didn’t provide the needed
+feature). Put another way: we have ascending compatibility with the
+Conclusion: We need to keep track of both major and minor.
+Thanks to `pkg-config` we can query them:
+    $ pkg-config --variable=abi_videodrv xorg-server
+    9.0
+    $ pkg-config --variable=abi_xinput xorg-server
+    12.1
+## Debian-side: Using virtual packages
+### Server’s build system
+When `xorg-server` gets built, we use `pkg-config`’s output to
+determine the current major. Through substitution variables, we add
+two virtual packages in the `Provides` field of the server (for both
+`xserver-xorg-core` and `xserver-xorg-core-udeb`): `xorg-input-abi-$x`
+and `xorg-video-abi-$y`, where `$x` and `$y` are the major part of the
+version queried through `pkg-config` variables.
+***FIXME: Currently we have both major and minor.***
+To handle ascending compatibility for minors, we maintain in
+`debian/serverminver` the minimal version of `xserver-xorg-core` which
+is needed. When a minor is bumped, we store the server version in that
+file. This way, drivers built afterwards will depend on a *minimal*
+version of the driver, the last which saw a minor version bump. In
+other words: they will “depend on the server version they were built
+against, or a higher/compatible one”.
+Both ABI and minimal server version are recorded in two files shipped
+in `xserver-xorg-dev`, to be used while building drivers:
+   * `/usr/share/xserver-xorg/xinputdep`
+   * `/usr/share/xserver-xorg/videodrvdep`
+Example for `xinputdep`:
+    xorg-input-abi-11, xserver-xorg-core (>= 2:
+***FIXME: Lies! That's currently `xorg-input-abi-11.0, …` instead.***
+### Driver’s control file
+Drivers also use substitution variables in their control file,
+replaced at build time.
+    # Input driver:
+    Depends: ${xinpdriver:Depends}, …
+    Provides: ${xinpdriver:Provides}
+    # Video driver:
+    Depends: ${xviddriver:Depends}, …
+    Provides: ${xviddriver:Provides}
+For now, `${xinpdriver:Provides}` is always replaced with
+`xorg-driver-input`, and `${xviddriver:Provides}` is always replaced
+with `xorg-driver-video`. Hopefully provided packages will not change,
+but using substitution variables is cheap, and makes it easy to add
+tweaks afterwards if needed.
+### Driver’s build system
+To set those variables, we ship a `dh_xsf_substvars` script in
+`xserver-xorg-dev` starting with ***FIXME_version***, to be run before
+`dh_gencontrol`. It iterates on the packages listed by
+`dh_listpackages` (very old `debhelper` command) and does the
+following work:
+ * It reads variables from the files mentioned above.
+ * If a package name ends with `-udeb`, it replaces
+   `xserver-xorg-core` with `xserver-xorg-core-udeb`.
+ * If a package name ends with `-dbg`, it does nothing for this
+   package. Debug packages usually depend strictly on the non-debug
+   packages, which in turn have appropriate dependencies.
+ * If a package name starts with `xserver-xorg-input-`, it appends
+   `xinpdriver:Depends=…` and `xinpdriver:Provides=…` to this
+   package’s substvars file.
+ * If a package name starts with `xserver-xorg-video-`, it appends
+   `xviddriver:Depends=…` and `xviddriver:Provides=…` to this
+   package’s substvars file.
+Why such heuristics? The idea is to avoid getting “unused substitution
+variable” warning messages while building. And since there’s a clear
+`xserver-xorg-{input,video}-*` namespace, we can use that to specify
+only input-related variables for input drivers, and only video-related
+variables for video drivers.
+## Possible improvements
+Once we’re done implementing the above stuff in `xorg-server`, and
+getting rid of deprecated features, we can do a bit more.
+To make it easy to compute substvars when using `dh`, we can ship a
+`dh` sequence to insert `dh_xsf_substvars` right before the
+`dh_gencontrol` call. That sequence could also be used to automate
+other stuff.
+We probably should have some way of tracking ABI bumps automatically,
+to make sure we bump `serverminver` when needed.

commit 45ae4b42e61f581087bdad27a42df4b80fb37206
Author: Cyril Brulebois <kibi@debian.org>
Date:   Tue Feb 1 12:14:36 2011 +0100

    css: Avoid too much margin in nested lists.

diff --git a/xsf.css b/xsf.css
index 1b7aaf6..5c070c4 100644
--- a/xsf.css
+++ b/xsf.css
@@ -59,6 +59,11 @@ ol {
   text-align: justify;
+/* Avoid too much margin in nested lists */
+ul ul, ol ul, ul ol, ol ol {
+  margin-left: 0px;
 pre {
   margin-left: 60px;

Reply to: