From 9e88810c3a65c518cb04ff9fecc6bae62483339f Mon Sep 17 00:00:00 2001 From: openKylinBot Date: Sat, 14 May 2022 03:21:45 +0800 Subject: [PATCH] Import Upstream version 7.7+19ubuntu14 --- xsf-docs/COPYING | 19 + xsf-docs/Makefile | 64 ++++ xsf-docs/asciidoc-xhtml11.css | 424 +++++++++++++++++++++++ xsf-docs/asciidoc-xhtml11.js | 128 +++++++ xsf-docs/faq/general.txt | 96 +++++ xsf-docs/howto/build-mesa.txt | 201 +++++++++++ xsf-docs/howto/configure-input.txt | 193 +++++++++++ xsf-docs/howto/report-bugs.txt | 62 ++++ xsf-docs/howto/triage-bugs.txt | 104 ++++++ xsf-docs/howto/use-gdb.txt | 179 ++++++++++ xsf-docs/howto/use-xrandr.txt | 214 ++++++++++++ xsf-docs/howtos | 1 + xsf-docs/index.txt | 51 +++ xsf-docs/reference/dependencies.txt | 260 ++++++++++++++ xsf-docs/reference/experimental.txt | 98 ++++++ xsf-docs/reference/git-usage.txt | 200 +++++++++++ xsf-docs/reference/squeeze-backports.txt | 70 ++++ xsf-docs/reference/upstream-contacts.txt | 46 +++ xsf-docs/upstream-features.txt | 17 + xsf-docs/xsf.css | 8 + xsf-docs/xsf.png | Bin 0 -> 3914 bytes xsf-docs/xsf.svg | 234 +++++++++++++ 22 files changed, 2669 insertions(+) create mode 100644 xsf-docs/COPYING create mode 100644 xsf-docs/Makefile create mode 100644 xsf-docs/asciidoc-xhtml11.css create mode 100644 xsf-docs/asciidoc-xhtml11.js create mode 100644 xsf-docs/faq/general.txt create mode 100644 xsf-docs/howto/build-mesa.txt create mode 100644 xsf-docs/howto/configure-input.txt create mode 100644 xsf-docs/howto/report-bugs.txt create mode 100644 xsf-docs/howto/triage-bugs.txt create mode 100644 xsf-docs/howto/use-gdb.txt create mode 100644 xsf-docs/howto/use-xrandr.txt create mode 120000 xsf-docs/howtos create mode 100644 xsf-docs/index.txt create mode 100644 xsf-docs/reference/dependencies.txt create mode 100644 xsf-docs/reference/experimental.txt create mode 100644 xsf-docs/reference/git-usage.txt create mode 100644 xsf-docs/reference/squeeze-backports.txt create mode 100644 xsf-docs/reference/upstream-contacts.txt create mode 100644 xsf-docs/upstream-features.txt create mode 100644 xsf-docs/xsf.css create mode 100644 xsf-docs/xsf.png create mode 100644 xsf-docs/xsf.svg diff --git a/xsf-docs/COPYING b/xsf-docs/COPYING new file mode 100644 index 0000000..31eda94 --- /dev/null +++ b/xsf-docs/COPYING @@ -0,0 +1,19 @@ +© 2010-2011 Cyril Brulebois + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/xsf-docs/Makefile b/xsf-docs/Makefile new file mode 100644 index 0000000..6b565e7 --- /dev/null +++ b/xsf-docs/Makefile @@ -0,0 +1,64 @@ +#!/usr/bin/make -f + +txt_files = $(shell find -name '*.txt' -a ! -name '.*.txt') + +html_files = $(patsubst %.txt,%.html,$(txt_files)) + +pdf_files = $(patsubst %.txt,%.pdf,$(txt_files)) + +TXT_TO_HTML = TZ=UTC asciidoc -a linkcss +HTML_TO_PDF = wkhtmltopdf +CSS_FILE = xsf.css +ADOC_CSS_FILE= asciidoc-xhtml11.css +ADOC_JS_FILE = asciidoc-xhtml11.js +SVG_LOGO = xsf.svg +PNG_LOGO = xsf.png + +all_files = $(html_files) $(txt_files) $(CSS_FILE) $(ADOC_CSS_FILE) $(ADOC_JS_FILE) $(SVG_LOGO) $(PNG_LOGO) + +all: html $(PNG_LOGO) + +html: $(html_files) + +pdf: $(pdf_files) + +%.html: rel_path=$(shell echo $@|sed 's,[^/],,g;s,/,../,g') +%.html: link_home=$(shell echo "XSF / ") +%.html: %.txt + @echo " HTML $@" + @$(TXT_TO_HTML) -o $@.tmp $< + @echo " HOME $@" + @if [ $< != index.txt ]; then sed -i 's,

,

$(link_home),' $@.tmp; fi + @echo " CSS $@" + @sed -i 's,\(rel="stylesheet" href="\)[^"]*,\1$(rel_path)$(CSS_FILE),' $@.tmp + @echo " JS $@" + @sed -i 's,\(type="text/javascript" src="\)[^"]*,\1$(rel_path)$(ADOC_JS_FILE),' $@.tmp + @mv $@.tmp $@ + +%.pdf: %.html $(CSS_FILE) $(ADOC_CSS_FILE) $(ADOC_JS_FILE) $(SVG_LOGO) + @echo " GEN $@" + @$(HTML_TO_PDF) $< $@ + +# We usually don't need to run this one, but it's easier to keep both +# SVN and PNG logos in sync: +$(PNG_LOGO): $(SVG_LOGO) + inkscape $< -e $@ + +install: + @if [ -z "$(DESTDIR)" ]; then \ + echo 'E: DESTDIR is not set, not installing.'; exit 1; \ + fi + mkdir -p $(DESTDIR) + # There are probably better ways: + set -e; for i in $(all_files); do \ + d=$(DESTDIR)/`dirname $$i` && \ + mkdir -p $$d && \ + install $$i $$d; \ + done + +clean: + @echo "Removing all generated files" + rm -f $(html_files) $(pdf_files) + + +.PHONY: clean html pdf all diff --git a/xsf-docs/asciidoc-xhtml11.css b/xsf-docs/asciidoc-xhtml11.css new file mode 100644 index 0000000..af273ad --- /dev/null +++ b/xsf-docs/asciidoc-xhtml11.css @@ -0,0 +1,424 @@ +/* Sans-serif font. */ +h1, h2, h3, h4, h5, h6, +div.title, caption.title, +thead, p.table.header, +div#toctitle, +span#author, span#revnumber, span#revdate, span#revremark, +div#footer { + font-family: Arial,Helvetica,sans-serif; +} + +/* Serif font. */ +div.sectionbody { + font-family: Georgia,"Times New Roman",Times,serif; +} + +/* Monospace font. */ +tt { + font-size: inherit; +} + +body { + margin: 1em 5% 1em 5%; +} + +a { + color: blue; + text-decoration: underline; +} +a:visited { + color: fuchsia; +} + +em { + font-style: italic; + color: navy; +} + +strong { + font-weight: bold; + color: #083194; +} + +tt { + font-size: inherit; + color: navy; +} + +h1, h2, h3, h4, h5, h6 { + color: #527bbd; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3; +} + +h1, h2, h3 { + border-bottom: 2px solid silver; +} +h2 { + padding-top: 0.5em; +} +h3 { + float: left; +} +h3 + * { + clear: left; +} + +div.sectionbody { + margin-left: 0; +} + +hr { + border: 1px solid silver; +} + +p { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +ul, ol, li > p { + margin-top: 0; +} +ul > li { color: #aaa; } +ul > li > * { color: black; } + +pre { + padding: 0; + margin: 0; +} + +span#author { + color: #527bbd; + font-weight: bold; + font-size: 1.1em; +} +span#email { +} +span#revnumber, span#revdate, span#revremark { +} + +div#footer { + font-size: small; + border-top: 2px solid silver; + padding-top: 0.5em; + margin-top: 4.0em; +} +div#footer-text { + float: left; + padding-bottom: 0.5em; +} +div#footer-badges { + float: right; + padding-bottom: 0.5em; +} + +div#preamble { + margin-top: 1.5em; + margin-bottom: 1.5em; +} +div.tableblock, div.imageblock, div.exampleblock, div.verseblock, +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, +div.admonitionblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.admonitionblock { + margin-top: 2.0em; + margin-bottom: 2.0em; + margin-right: 10%; + color: #606060; +} + +div.content { /* Block element content. */ + padding: 0; +} + +/* Block element titles. */ +div.title, caption.title { + color: #527bbd; + font-weight: bold; + text-align: left; + margin-top: 1.0em; + margin-bottom: 0.5em; +} +div.title + * { + margin-top: 0; +} + +td div.title:first-child { + margin-top: 0.0em; +} +div.content div.title:first-child { + margin-top: 0.0em; +} +div.content + div.title { + margin-top: 0.0em; +} + +div.sidebarblock > div.content { + background: #ffffee; + border: 1px solid #dddddd; + border-left: 4px solid #f0f0f0; + padding: 0.5em; +} + +div.listingblock > div.content { + border: 1px solid #dddddd; + border-left: 5px solid #f0f0f0; + background: #f8f8f8; + padding: 0.5em; +} + +div.quoteblock, div.verseblock { + padding-left: 1.0em; + margin-left: 1.0em; + margin-right: 10%; + border-left: 5px solid #f0f0f0; + color: #777777; +} + +div.quoteblock > div.attribution { + padding-top: 0.5em; + text-align: right; +} + +div.verseblock > pre.content { + font-family: inherit; + font-size: inherit; +} +div.verseblock > div.attribution { + padding-top: 0.75em; + text-align: left; +} +/* DEPRECATED: Pre version 8.2.7 verse style literal block. */ +div.verseblock + div.attribution { + text-align: left; +} + +div.admonitionblock .icon { + vertical-align: top; + font-size: 1.1em; + font-weight: bold; + text-decoration: underline; + color: #527bbd; + padding-right: 0.5em; +} +div.admonitionblock td.content { + padding-left: 0.5em; + border-left: 3px solid #dddddd; +} + +div.exampleblock > div.content { + border-left: 3px solid #dddddd; + padding-left: 0.5em; +} + +div.imageblock div.content { padding-left: 0; } +span.image img { border-style: none; } +a.image:visited { color: white; } + +dl { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +dt { + margin-top: 0.5em; + margin-bottom: 0; + font-style: normal; + color: navy; +} +dd > *:first-child { + margin-top: 0.1em; +} + +ul, ol { + list-style-position: outside; +} +ol.arabic { + list-style-type: decimal; +} +ol.loweralpha { + list-style-type: lower-alpha; +} +ol.upperalpha { + list-style-type: upper-alpha; +} +ol.lowerroman { + list-style-type: lower-roman; +} +ol.upperroman { + list-style-type: upper-roman; +} + +div.compact ul, div.compact ol, +div.compact p, div.compact p, +div.compact div, div.compact div { + margin-top: 0.1em; + margin-bottom: 0.1em; +} + +div.tableblock > table { + border: 3px solid #527bbd; +} +thead, p.table.header { + font-weight: bold; + color: #527bbd; +} +tfoot { + font-weight: bold; +} +td > div.verse { + white-space: pre; +} +p.table { + margin-top: 0; +} +/* Because the table frame attribute is overriden by CSS in most browsers. */ +div.tableblock > table[frame="void"] { + border-style: none; +} +div.tableblock > table[frame="hsides"] { + border-left-style: none; + border-right-style: none; +} +div.tableblock > table[frame="vsides"] { + border-top-style: none; + border-bottom-style: none; +} + + +div.hdlist { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +div.hdlist tr { + padding-bottom: 15px; +} +dt.hdlist1.strong, td.hdlist1.strong { + font-weight: bold; +} +td.hdlist1 { + vertical-align: top; + font-style: normal; + padding-right: 0.8em; + color: navy; +} +td.hdlist2 { + vertical-align: top; +} +div.hdlist.compact tr { + margin: 0; + padding-bottom: 0; +} + +.comment { + background: yellow; +} + +.footnote, .footnoteref { + font-size: 0.8em; +} + +span.footnote, span.footnoteref { + vertical-align: super; +} + +#footnotes { + margin: 20px 0 20px 0; + padding: 7px 0 0 0; +} + +#footnotes div.footnote { + margin: 0 0 5px 0; +} + +#footnotes hr { + border: none; + border-top: 1px solid silver; + height: 1px; + text-align: left; + margin-left: 0; + width: 20%; + min-width: 100px; +} + +div.colist td { + padding-right: 0.5em; + padding-bottom: 0.3em; + vertical-align: top; +} +div.colist td img { + margin-top: 0.3em; +} + +@media print { + div#footer-badges { display: none; } +} + +div#toc { + margin-bottom: 2.5em; +} + +div#toctitle { + color: #527bbd; + font-size: 1.1em; + font-weight: bold; + margin-top: 1.0em; + margin-bottom: 0.1em; +} + +div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { + margin-top: 0; + margin-bottom: 0; +} +div.toclevel2 { + margin-left: 2em; + font-size: 0.9em; +} +div.toclevel3 { + margin-left: 4em; + font-size: 0.9em; +} +div.toclevel4 { + margin-left: 6em; + font-size: 0.9em; +} + +span.aqua { color: aqua; } +span.black { color: black; } +span.blue { color: blue; } +span.fuchsia { color: fuchsia; } +span.gray { color: gray; } +span.green { color: green; } +span.lime { color: lime; } +span.maroon { color: maroon; } +span.navy { color: navy; } +span.olive { color: olive; } +span.purple { color: purple; } +span.red { color: red; } +span.silver { color: silver; } +span.teal { color: teal; } +span.white { color: white; } +span.yellow { color: yellow; } + +span.aqua-background { background: aqua; } +span.black-background { background: black; } +span.blue-background { background: blue; } +span.fuchsia-background { background: fuchsia; } +span.gray-background { background: gray; } +span.green-background { background: green; } +span.lime-background { background: lime; } +span.maroon-background { background: maroon; } +span.navy-background { background: navy; } +span.olive-background { background: olive; } +span.purple-background { background: purple; } +span.red-background { background: red; } +span.silver-background { background: silver; } +span.teal-background { background: teal; } +span.white-background { background: white; } +span.yellow-background { background: yellow; } + +span.big { font-size: 2em; } +span.small { font-size: 0.6em; } diff --git a/xsf-docs/asciidoc-xhtml11.js b/xsf-docs/asciidoc-xhtml11.js new file mode 100644 index 0000000..30d738a --- /dev/null +++ b/xsf-docs/asciidoc-xhtml11.js @@ -0,0 +1,128 @@ +var asciidoc = { // Namespace. + +///////////////////////////////////////////////////////////////////// +// Table Of Contents generator +///////////////////////////////////////////////////////////////////// + +/* Author: Mihai Bazon, September 2002 + * http://students.infoiasi.ro/~mishoo + * + * Table Of Content generator + * Version: 0.4 + * + * Feel free to use this script under the terms of the GNU General Public + * License, as long as you do not remove or alter this notice. + */ + + /* modified by Troy D. Hanson, September 2006. License: GPL */ + /* modified by Stuart Rackham, 2006, 2009. License: GPL */ + +// toclevels = 1..4. +toc: function (toclevels) { + + function getText(el) { + var text = ""; + for (var i = el.firstChild; i != null; i = i.nextSibling) { + if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants. + text += i.data; + else if (i.firstChild != null) + text += getText(i); + } + return text; + } + + function TocEntry(el, text, toclevel) { + this.element = el; + this.text = text; + this.toclevel = toclevel; + } + + function tocEntries(el, toclevels) { + var result = new Array; + var re = new RegExp('[hH]([2-'+(toclevels+1)+'])'); + // Function that scans the DOM tree for header elements (the DOM2 + // nodeIterator API would be a better technique but not supported by all + // browsers). + var iterate = function (el) { + for (var i = el.firstChild; i != null; i = i.nextSibling) { + if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { + var mo = re.exec(i.tagName); + if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { + result[result.length] = new TocEntry(i, getText(i), mo[1]-1); + } + iterate(i); + } + } + } + iterate(el); + return result; + } + + var toc = document.getElementById("toc"); + var entries = tocEntries(document.getElementById("content"), toclevels); + for (var i = 0; i < entries.length; ++i) { + var entry = entries[i]; + if (entry.element.id == "") + entry.element.id = "_toc_" + i; + var a = document.createElement("a"); + a.href = "#" + entry.element.id; + a.appendChild(document.createTextNode(entry.text)); + var div = document.createElement("div"); + div.appendChild(a); + div.className = "toclevel" + entry.toclevel; + toc.appendChild(div); + } + if (entries.length == 0) + toc.parentNode.removeChild(toc); +}, + + +///////////////////////////////////////////////////////////////////// +// Footnotes generator +///////////////////////////////////////////////////////////////////// + +/* Based on footnote generation code from: + * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html + */ + +footnotes: function () { + var cont = document.getElementById("content"); + var noteholder = document.getElementById("footnotes"); + var spans = cont.getElementsByTagName("span"); + var refs = {}; + var n = 0; + for (i=0; i" + + "" + + n + ". " + note + ""; + spans[i].innerHTML = + "[" + n + "]"; + var id =spans[i].getAttribute("id"); + if (id != null) refs["#"+id] = n; + } + } + if (n == 0) + noteholder.parentNode.removeChild(noteholder); + else { + // Process footnoterefs. + for (i=0; i" + n + "]"; + } + } + } +} + +} diff --git a/xsf-docs/faq/general.txt b/xsf-docs/faq/general.txt new file mode 100644 index 0000000..b0554e5 --- /dev/null +++ b/xsf-docs/faq/general.txt @@ -0,0 +1,96 @@ +General FAQ +=========== +:toc: +Cyril Brulebois + + +Input drivers +------------- + + * _How do I configure input for X?_ + + Look at the link:../howto/configure-input.html[how to configure input] documentation. + + * _Why can’t I kill X through `Ctrl+Alt+Backspace`?_ + + That’s explained in the above-mentioned documentation. + + +<<< +Video drivers +------------- + +All drivers +~~~~~~~~~~~ + + * _What’s wrong with the DPI setting?_ + + By the default, the X server uses 96 DPI, as seen on upstream bug + https://bugs.freedesktop.org/show_bug.cgi?id=23705[#23705] (in + particular + https://bugs.freedesktop.org/show_bug.cgi?id=23705#c6[Keith’s comment]). A + particular DPI setting can be set through desktop environment’s + preferences, through the `-dpi` X server command line option (see + ++Xserver++’s manual page), or through ++xrandr++’s `--dpi` option. + + * _How do I get some info about 3D support?_ + + Look at the link:../howto/build-mesa.html[instructions to build mesa], + there are a few commands to learn about 3D support, the current driver, + etc. + +Ati driver +~~~~~~~~~~ + + * _Why is it I’m getting low performances, or even crashes?_ + + Make sure you have installed the + link:http://packages.debian.org/firmware-linux&exact=1[`firmware-linux` + package]. The driver might still be working without the firmware, + but using code paths which aren’t supported as well as the “normal” + ones. + +Intel driver +~~~~~~~~~~~~ + + * _Why isn’t it working?_ + + KMS is mandatory, as documented in its `README.Debian` (view it + online: + http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-intel.git;a=blob;f=debian/README.Debian[git.debian.org]). You + probably disabled KMS or didn’t include it in your kernel + configuration if you’re using a custom kernel. + + * _X is crashing all the time with my “old” Intel card. What can I do?_ + + Unfortunately, old cards are not very well supported, and you can’t + do much more than switching to a generic driver, like `fbdev` or + `vesa`, as documented in `README.Debian` (view it online: + http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-intel.git;a=blob;f=debian/README.Debian[git.debian.org]). Please + note that you need to disable `KMS` if you want to use the `vesa` + driver. A minimal `xorg.conf` would look like: +---- +Section "Device" + Identifier "MyBuggyCard" + Driver "fbdev" +EndSection +---- + +Nouveau driver +~~~~~~~~~~~~~~ + + * _Why isn’t it working?_ + + Since it’s still considered experimental by its authors, the + interfaces aren’t stable yet, so the driver has particular + dependencies on the kernel, which are documented in `README.Debian` + (view it online: + http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-nouveau.git;a=blob;f=debian/README.Debian;h=27ced6b1bf5102a5b72525318439efdfb330745d;hb=6c2f12ca18f55b55d49e083d86d87d970ce53a07[for squeeze], + http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-nouveau.git;a=blob;f=debian/README.Debian[for sid]). + + +<<< +Others +------ + +Session management +~~~~~~~~~~~~~~~~~~ + + * _How to start a bare X session (without Gnome, KDE, etc.)?_ + + Assuming there’s no X running on the `:1` display, run this from a + VT: +---- +startx /usr/bin/xterm -- :1 +---- diff --git a/xsf-docs/howto/build-mesa.txt b/xsf-docs/howto/build-mesa.txt new file mode 100644 index 0000000..eb17cba --- /dev/null +++ b/xsf-docs/howto/build-mesa.txt @@ -0,0 +1,201 @@ +How to build mesa +================= +:toc: +Cyril Brulebois + + +Foreword +-------- + +Mesa is a special package since many flavours are built, which means +it takes quite some time to get all packages ready, as well as some +disc space (over 2GB for the `build/` directory alone). + +Also, trying to figure out whether latest `master` is also affected, +or backporting some bug fixes might lead to some painful I/O while +generating the `.deb` files, and then installing/unpacking them. This +is why this document was written: Helping users test other mesa +releases, branches, bug fixes without having to build full packages, +and without having to mess with their systems (_i.e._ no root access +is needed once the build dependencies are installed). + +We’ll focus on the DRI (Direct Rendering Infrastructure) flavour +(`libgl1-mesa-dri`), which is the most common. + +It might be possible to adapt the following steps to another flavour, +in which case the appropriate options to be passed to `./configure` +should be looked up in the `debian/rules` file of the Debian source +package. + + +<<< +Gathering information +--------------------- + +Get started by installing `mesa-utils`, which contains `glxinfo`. + + * _Is direct rendering enabled?_ ++ + $ glxinfo | grep ^direct + direct rendering: Yes ++ +↪ Yes. + + * _Is this the classic or http://en.wikipedia.org/wiki/Gallium3D[Gallium] driver?_ ++ + $ glxinfo | grep 'renderer string' + OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT ++ +↪ No “Gallium” here, therefore: “classic”. + + * _Which driver is this, and where is it located?_ ++ + $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$ + libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so + libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so ++ +↪ `i915`, from the system directory: `/usr/lib/dri` (likely installed through a Debian package). + + + * _How can I get more debugging information?_ + + export LIBGL_DEBUG=verbose + export MESA_DEBUG=1 + export EGL_LOG_LEVEL=debug + + +<<< +Preparing mesa sources +---------------------- + +To get started, installing all build dependencies of the `mesa` source +package should be sufficient, along with the essential build tools, +and `git`: + +---- +$ sudo apt-get install build-essential git +$ sudo apt-get build-dep mesa +---- + +Make sure you have some disc space available, since the git repository +is over 120MB, and since the mesa directory is over 500MB after a +build. Once you’re ready, grab the upstream mesa sources: + +---- +$ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git +$ cd mesa.git +$ autoreconf -vfi +---- + +Here’s what the `./configure` call will look like: + +---- +$ ./configure --prefix=/usr \ + --enable-driglx-direct \ + --enable-gles1 \ + --enable-gles2 \ + --enable-glx-tls \ + --with-dri-driverdir=/usr/lib/dri \ + --with-egl-platforms='drm x11' \ + … +---- + +Now, what are the parameters to replace “++…++” with? Basically, if +you determined an Intel driver (`i915` or `i965`), you want to use the +classic drivers and to disable the Gallium drivers. Other drivers are +only available on Gallium (`r300`, `r600`, `radeonsi` and more). +Running `./configure --help` might be useful. + + +Examples for common drivers: + + * For `i915`, you need: + + --with-dri-drivers=i915 + + * For `i965`, you need: + + --with-dri-drivers=i965 + + * For `nouveau`, you may want to try: + + --with-dri-drivers=nouveau --with-gallium-drivers=nouveau + + * For `r300`, you need: + + --with-gallium-drivers=r300 + + * For `r600`, you need: + + --with-gallium-drivers=r600 + + * For `radeonsi`, you need: + + --with-gallium-drivers=radeonsi + +Now, once you’ve run `./configure`, time for your favorite beverage: + +---- +$ make +---- + +<<< +Running the newly-built mesa libraries +-------------------------------------- + +Shared libraries end up in the `lib/` directory. It contains the +classic drivers, while Gallium drivers end up under `lib/gallium`. If +you’re not an Intel user, overwrite the classic drivers with the +Gallium ones: + +---- +$ mv lib/gallium/* lib/ +---- + +Now, 3 variables need to be set, so that the locally-built libraries +are used. + + * To begin with, libGL itself and its drivers: ++ + $ export LIBGL_DRIVERS_PATH=lib ++ +_Did this work?_ ++ + $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$ + libGL: OpenDriver: trying lib/tls/i915_dri.so + libGL: OpenDriver: trying lib/i915_dri.so ++ +↪ Yes: No system directory, paths are relative to `lib/`. + + * Set `LD_LIBRARY_PATH` to make sure the locally-built libraries + (including those pulled through library dependencies) are used, + instead of system ones: ++ + $ export LD_LIBRARY_PATH=lib ++ +_Did this work?_ ++ + $ ldd lib/libGLESv2.so | grep glapi + libglapi.so.0 => lib/libglapi.so.0 (0x00007fee3192e000) ++ +↪ Yes: Path is relative to `lib`. + + * Set the EGL search path: ++ + $ export EGL_DRIVERS_PATH=lib/egl ++ +_Did this work?_ ++ + $ EGL_LOG_LEVEL=debug es2_info 2>&1 >/dev/null | grep '\.so' + libEGL debug: added lib/egl/egl_gallium.so to module array + libEGL debug: dlopen(lib/egl/egl_gallium.so) + libEGL debug: DRI2: dlopen(lib/i915_dri.so) ++ +↪ Yes: No system directory, paths are relative to `lib/`. + + +[float] +The end. +~~~~~~~~ + +Now you should be ready to test upstream’s suggestions! diff --git a/xsf-docs/howto/configure-input.txt b/xsf-docs/howto/configure-input.txt new file mode 100644 index 0000000..0a44e7a --- /dev/null +++ b/xsf-docs/howto/configure-input.txt @@ -0,0 +1,193 @@ +How to configure input +====================== +:toc: +Cyril Brulebois + + +General considerations +---------------------- + +Foreword +~~~~~~~~ + +The Debian wiki also contains an +http://wiki.debian.org/XStrikeForce/InputHotplugGuide[input hotplug guide] +which contains some context around X’s input subsystem. The present +document is meant to be an executive summary, and might miss some +bits. (*FIXME:* Merge those bits.) + + +Rules of thumb +~~~~~~~~~~~~~~ + +In this documentation, only the last part of the driver’s name will be +mentioned, all of them are under the `xserver-xorg-input-*` namespace. + + * On Linux, `evdev` is used for both keyboard and mouse + input. + * On Linux as well, `synaptics` can be used to benefit from extra + features; it takes precedence over `evdev` automatically if both + are installed. + * On GNU/kFreeBSD and GNU/Hurd, `kbd` handles the keyboard and + `mouse` handles mice, unsurprisingly. + + +Configuration snippets +~~~~~~~~~~~~~~~~~~~~~~ + +X can now be run without `xorg.conf`, but sometimes one has to +configure a few settings for this or that driver. Starting with +`squeeze`, that can be done by adding a file under +`/etc/X11/xorg.conf.d`, with a `.conf` suffix, as documented in the +`xorg.conf` manpage. + +Some packages ship a default configuration file under +`/usr/share/X11/xorg.conf.d` with general rules to match appropriate +hardware. The files under `/etc/X11/xorg.conf.d` take precedence, as +documented in the `xorg.conf` manpage. + +It’s probably mostly useful in the `synaptics` case, in case one wants +to change default settings on a system-wide fashion. See the _Pointer +configuration_ section below for an example. + + +<<< +Basic keyboard configuration +---------------------------- + +The `keyboard-configuration` package ships `/etc/default/keyboard` +which can be used to set the following `xkb` items: model, layout, +variant, and options. Here’s an example: + +---- +XKBMODEL="pc105" +XKBLAYOUT="fr" +XKBVARIANT="oss" +XKBOPTIONS="compose:menu,terminate:ctrl_alt_bksp" +---- + +Quick words about the options: + + * They are comma-separated. + * The list of options and a short description for each can be found + in the `/usr/share/X11/xkb/rules/base.lst` file (shipped by the + `xkb-data` package). + * First option: `compose:menu`. This sets the `menu` key as the + Compose key. More information about it can be found in the + `Compose` manpage. + * Second option: `terminate:ctrl_alt_bksp`. By default, the X server + is no longer killed through `Ctrl+Alt+Backspace`. This option + restores the old behaviour. + +Two ways to change the configuration: + + * `dpkg-reconfigure keyboard-configuration` is going to ask questions + through debconf prompts. + * Manually editing `/etc/default/keyboard` also works. + +How does it propagate to X? + + * When HAL is used (that is: on GNU/kFreeBSD and GNU/Hurd), one has + to restart it: `invoke-rc.d hal restart` + * When udev is used (on GNU/Linux, starting with `squeeze`), one has + to tell udev to reload input-related configuration: + `udevadm trigger --subsystem-match=input --action=change` + (that can be found in ++keyboard-configuration++’s `README.Debian` + file). Properties attached to the input devices are then updated, + and X uses those properties when it starts, as can be seen by + searching for `xkb_` in the X log. Please note that trying + `invoke-rc.d udev restart` changes nothing, one has to use + `udevadm`. Properties can be inspected through: + `/sbin/udevadm info --export-db` + + +<<< +Pointer configuration +--------------------- + +evdev configuration +~~~~~~~~~~~~~~~~~~~ + +Available options are documented in the `evdev` manpage. Let’s check +what a configuration snippet (mentioned in _General considerations_) +would look like. Here is a fictional `/etc/X11/xorg.conf.d/42-evdev.conf`: + +---- +Section "InputClass" + Identifier "evdev pointer tweaked catchall" + MatchIsPointer "on" + Driver "evdev" + Option "Emulate3Buttons" "True" + Option "SwapAxes" "True" +EndSection +---- + +Line by line walkthrough: + + * To avoid specifying any device under `/dev/input` (`event$N` might + change, remember it’s about hotplug support!), we use an + `InputClass`. + * We need an identifier, the actual name doesn’t matter. + * We match everything that looks like a touchpad. Meaning no generic + pointer, keyboard, or tablet. + * We specify the driver we want to use for the matched device(s). + * Finally the options we want to set. Here we enable the 3rd button + emulation (clicking left and right buttons at the same time then no + longer acts as if the middle button was clicked). Then we swap x + and y axes, just for the fun of it. + + +synaptics configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +The `synaptics` driver comes with two tools. The more interesting one +is `synclient`, which can be used to list available options and +current settings: `synclient -l`. The documentation for each option +can be found in the `synaptics` manpage. + +`synclient` can also be used to set options. A common example is +enabling tapping (upstream kept it disabled by default, Debian won’t +deviate, no need to file bugs): `synclient TapButton1=1`; one can also +disable the touchpad temporarily: `synclient TouchpadOff=1` to +disable it, `synclient TouchpadOff=0` to enable it again. + +Let’s check what a configuration snippet (mentioned in _General +considerations_) would look like. Here is a fictional +`/etc/X11/xorg.conf.d/42-synaptics.conf`: + +---- +Section "InputClass" + Identifier "touchpad tweaked catchall" + MatchIsTouchpad "on" + Driver "synaptics" + Option "TapButton1" "1" + Option "HorizEdgeScroll" "1" +EndSection +---- + +Line by line walkthrough: + + * To avoid specifying any device under `/dev/input` (`event$N` might + change, remember it’s about hotplug support!), we use an + `InputClass`. + * We need an identifier, the actual name doesn’t matter. + * We match everything that looks like a touchpad. Meaning no generic + pointer, keyboard, or tablet. + * We specify the driver we want to use for the matched device(s). + * Finally the options we want to set. We enable tapping for the first + button. And we enable horizontal scrolling (by default, only + vertical scrolling is enabled). + +Settings can also be changed by various settings managers, like +Gnome’s or KDE’s. An example of a graphical user interface making it +possible to set options in a clicky way: `gpointing-device-settings`. + +There’s a palm detection setting but that relies on hardware/firmware +support for the touchpad. The other tool shipped with the `synaptics` +driver is `syndaemon`, which makes it trivial to disable the touchpad +temporarily, when the keyboard is being used. Here’s an example: +`syndaemon -d -i 0.5` makes `syndaemon` start in background (`-d` for +daemon mode), waiting 0.5 second before enabling the touchpad again +after the last keypress. Warning: it becomes quite difficult to use +things like `Ctrl+click` in a browser, or `Alt+drag` to move +windows. diff --git a/xsf-docs/howto/report-bugs.txt b/xsf-docs/howto/report-bugs.txt new file mode 100644 index 0000000..718a1d1 --- /dev/null +++ b/xsf-docs/howto/report-bugs.txt @@ -0,0 +1,62 @@ +How to report bugs +================== +Cyril Brulebois + + +Report it upstream +------------------ + +In most cases, it is preferrable to report the bug upstream at +https://bugs.freedesktop.org/enter_bug.cgi?product=xorg + +See https://01.org/linuxgraphics/documentation/how-report-bugs-0 for a good +introduction on how to write useful bug reports. While the document is targeted +at Intel graphics hardware, it is a good guideline for other vendor’s hardware +as well. + +Simple as reportbug +------------------- + +Initial report +~~~~~~~~~~~~~~ + +Unless you know which package to report the bug against, you can +report the bug against the `xorg` metapackage: + +---- +reportbug xorg +---- + +Like most packages related to the X server, reporting a bug against +this package triggers a bug script which is going to collect X-related +information, be it installed packages, running kernel, X +configuration, X log, and so on. + +**** +.Note +In case this metapackage wasn’t used to install your X stack, +report a bug against `xserver-xorg` instead. And if that one isn’t +installed either, go for `xserver-xorg-core`. +**** + +If a backtrace shows up in the X log, it’s much appreciated to try and +get a link:use-gdb.html[full backtrace using gdb]. + + +Follow-up with more info +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you reported a bug against another package and if that bug was +reassigned to an X-related package, we might need more +information. You can run the bug script manually and attach its output +to your mail to the bug report: + +---- +/usr/share/bug/xserver-xorg-core/script 3>/tmp/script.log +---- + +**** +.Note +Make sure there’s no space between `3` and `>`, that’s a shell +redirection. +**** diff --git a/xsf-docs/howto/triage-bugs.txt b/xsf-docs/howto/triage-bugs.txt new file mode 100644 index 0000000..3440938 --- /dev/null +++ b/xsf-docs/howto/triage-bugs.txt @@ -0,0 +1,104 @@ +How to triage bugs +================== +:toc: +Cyril Brulebois + + +Packaging bugs or upstream bugs? +-------------------------------- + +It’d be nice to get all upstream bugs tagged as such (`upstream` tag), +forwarded upstream (which means the bugzilla instance on +http://bugs.freedesktop.org/ for most packages), and marked as such. + +A mail to `control@bugs.debian.org` would look like: + +---- +tag X upstream +forwarded X https://bugs.freedesktop.org/show_bug.cgi?id=Y +thanks +---- + +Then http://bts-link.alioth.debian.org/[`bts-link`] comes into play +and helps us tracking upstream status, which is pretty nice to have. + + +<<< +Usertags +-------- + +Another feature of the BTS is usertagging. That lets people keep track +of additional tags, “attached” to a given mail address. For XSF, +that’s `debian-x@lists.debian.org`. + +The list of all usertagged bugs can be seen on the following page; the +list of all used usertags is at the bottom, in the form. + +→ http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x%40lists.debian.org + +Let’s give some examples: + + * `i810`, `i915`: helps triaging `-video-intel` bugs depending on the + chipset. + * `r200`, `r300`: ditto for `-video-ati`. + * `xset`, `xrandr`: helps triaging `x11-xserver-utils` bugs depending + on the affected tool (like other `x11-*` packages, that’s a bundle + of teeny tiny apps). + * `squeeze-candidate`: helps keeping a list of bugs we’d like to get + fixed in a point release (through a stable update). + * `needs-forwarding`: of course, it’d be nice to have all upstream + bugs reported upstream, but some might need special attention + (_e.g._ security bugs). + +Here’s an example of URL, for the last tags: + +→ http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x%40lists.debian.org&tag=squeeze-candidate + +→ http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x%40lists.debian.org&tag=needs-forwarding + +By the way one should keep an eye on the list of found/fixed +versions since those bugs are likely marked as resolved (in `unstable` +or `experimental`), but might still affect a stable release. + +To list the bugs marked `squeeze-candidate` but not +`squeeze-accepted`: + +→ http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x%40lists.debian.org&tag=squeeze-candidate&exclude=tag:squeeze-accepted + + +<<< +Categories +---------- + +The BTS has yet another feature which can help, categories. That’s +based on usertags as well, but one has to use the package address +(`$package@packages.debian.org`), so that’s package-specific rather +than team-specific. + +Categories are +http://wiki.debian.org/bugs.debian.org/usertags[documented on the wiki], +and they would probably be welcome in the `intel` and `ati` cases +above, as well as in the “multiple tools in a single bundle” +cases… An example of what we could achieve is the +http://bugs.debian.org/devscripts[devscripts bug page] (it takes +some time to load, plenty of bugs). + +Needed steps for that to happen: + + * create usercategories. + * move usertags from `debian-x@lists.debian.org` to + `$package@packages.debian.org`, probably using the `bts select` + command to get the list over which to iterate. + * profit! + +To move the usertags, something like that should do the job: +---- +# Adding usertags: +user $package1@packages.debian.org +usertag X xset +usertag Y xrandr +user $package2@packages.debian.org +usertag Z i810 + +# Removing tags which are no longer needed: +user debian-x@lists.debian.org +usertag X - xset +usertag Y - xrandr +usertag Z - i810 +---- diff --git a/xsf-docs/howto/use-gdb.txt b/xsf-docs/howto/use-gdb.txt new file mode 100644 index 0000000..dce7d02 --- /dev/null +++ b/xsf-docs/howto/use-gdb.txt @@ -0,0 +1,179 @@ +How to use gdb +============== +:toc: +Cyril Brulebois + + +Foreword +-------- + +One should note that X is responsible for VT switching, meaning +switching between an X session and console terminals. In other words, +`Ctrl+Alt+Fn` is handled by X. If X is stopped, for example because +it’s running under `gdb`, one can no longer switch to another +VT. That’s why we’re recommending using a second machine to debug +X. Nevertheless, here are some instructions to attempt debugging X +with a single machine. + +One-machine approach +~~~~~~~~~~~~~~~~~~~~ + +This is a _post-mortem_ approach. The idea is to run X with the +`-core` option. Once it dies, a core file (`/etc/X11/core`) is +generated, and can be loaded from `gdb`. + +Follow these steps: + + 1. Getting a core file. + 2. Loading a core file. + 3. Displaying/saving a backtrace. + +Two-machine approach +~~~~~~~~~~~~~~~~~~~~ + +You pay the “need a second machine” price, but that buys you +interactivity. Just log into the first machine from the second one, +using `ssh`. + +Follow these steps: + + 1. Attaching/Starting X from gdb. + 2. Displaying/saving a backtrace. + +Needed packages +~~~~~~~~~~~~~~~ + +Obviously, `gdb` is needed; `xserver-xorg-core-dbg` contains the +debugging symbols for the server itself. Other needed packages can be +determined by looking at the backtrace. **FIXME: More info about +that.** + + +<<< +Actual gdb work +--------------- + +Getting a core file +~~~~~~~~~~~~~~~~~~~ + + * Using `gdm3` 3.4.1 and above: uncomment `Enable = true` in the + `[debug]` section of the `/etc/gdm3/daemon.conf` file. + + * Using an older `gdm3` package: The idea is to tweak the daemon’s + `LocalXserverCommand` setting, adding the `-core` option. As of + `gdm3 2.30`, the defaults can be found in + `/usr/share/gdm/gdm.schemas`. Sample `/etc/gdm3/daemon.conf` + excerpt: + +---- +[daemon] +LocalXserverCommand=/usr/bin/Xorg -br -verbose -audit 0 -novtswitch -core +---- + + * Using `kdm`: One should look for the `ServerArgsLocal` variable in + the `/etc/kde4/kdm/kdmrc` file, and add `-core` there. Example: + +---- +ServerArgsLocal=-br -nolisten tcp -core +---- + + * Using `xdm`: It’s sufficient to add `-core` to the command + configured through `/etc/X11/xdm/Xservers`, for example: + +---- +:0 local /usr/bin/X :0 vt7 -nolisten tcp -core +---- + +Loading a core file +~~~~~~~~~~~~~~~~~~~ + +That’s trivial, one just needs to pass both the core file and the path +to the binary: + +---- +# gdb -c /etc/X11/core /usr/bin/Xorg +---- + +Now `gdb` is ready to display backtraces. + +Attaching X from gdb +~~~~~~~~~~~~~~~~~~~~ + +The way of starting X doesn’t really matter, as `gdb` makes it +possible to attach a running process. If there’s a single X instance +running, that will do the job: + +---- +# gdb attach $(pidof X) +[---GDB starts---] +(gdb) handle SIGPIPE nostop +(gdb) cont +---- + +If there are several instances, one can use `ps aux` to determine the +PID of the appropriate instance (2nd column → `$pid`), and then attach +it: + +---- +# gdb attach $pid +[---GDB starts---] +(gdb) handle SIGPIPE nostop +(gdb) cont +---- + +Starting X from gdb +~~~~~~~~~~~~~~~~~~~ + +In case X crashes at start-up, one can start X from `gdb` in the +following way. In this example, the only parameter is the display, but +more parameters can be added. + +---- +# gdb --args Xorg :0 +[---GDB starts---] +(gdb) handle SIGPIPE nostop +(gdb) run +---- + +What is SIGPIPE? +~~~~~~~~~~~~~~~~ + +`SIGPIPE` is a signal that can reach the X server quite easily, +especially when performing a VT switch, or refreshing large parts of +the screen. That’s why we ask `gdb` not to stop when such a signal is +caught, thanks to the `handle SIGPIPE nostop` command. + +How to display a backtrace? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once X is crashed, for example because it received a `SIGSEGV` +(segmentation fault, usually because of a NULL pointer dereference), +or a `SIGBUS`, one gets back to the `gdb` prompt. One can then request +a backtrace (`bt`) or a full backtrace (`bt full`). The latter is what +developers are usually interested in, because variable values are also +available. + +---- +(gdb) bt +(gdb) bt full +---- + +How to save a backtrace? +~~~~~~~~~~~~~~~~~~~~~~~~ + +To save a recording of the gdb session to a file (`gdb.txt` by +default): + +---- +(gdb) set logging on +---- + +To save in a different file, use this instead: + +---- +(gdb) set logging file my-file.txt +(gdb) set logging on +---- + +Once logging is enabled, you can request a (full) backtrace using the +previous commands. diff --git a/xsf-docs/howto/use-xrandr.txt b/xsf-docs/howto/use-xrandr.txt new file mode 100644 index 0000000..499bb2a --- /dev/null +++ b/xsf-docs/howto/use-xrandr.txt @@ -0,0 +1,214 @@ +How to use xrandr +================= +:toc: +Cyril Brulebois + + +Getting started +--------------- + +What is xrandr? +~~~~~~~~~~~~~~~ + +`xrandr` is a command-line tool to interact with the X `RandR` +extension [see http://www.x.org/wiki/Projects/XRandR[x.org], +http://en.wikipedia.org/wiki/RandR[wikipedia]], which allows for +live (re)configuration of the X server (_i.e._ without restarting it): +It provides automatic discovery of modes (resolutions, refresh rates, +etc.) together with the ability to configure outputs dynamically +(resize, rotate, move, etc.). + +*FIXME: Status across drivers?* + +What consequences for xorg.conf? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting with `squeeze`, removing the `xorg.conf` configuration file +entirely should work well enough, but in case that doesn’t work out, +let’s document what can be removed from it from a `RandR` point of +view. + +With the driver detecting modes automatically, several configuration +options become useless most of the time in your configuration file +(xorg.conf). You might want to remove: + + * `HorizSync` and `VertRefresh` from the `Monitor` section. + * Modes from `Display` subsection in `Screen` section. + * `ModeLine` from the `Monitor` section. + +There’s also no need to keep static dual-head configuration. Some +suggestions to get a tiny `xorg.conf`: + + * Drop dual `Device`/`Screen`/`Monitor` sections, a single one is + needed. + * Drop `MonitorLayout` option and `Screen` lines from the remaining + `Device` section. + * Drop the `ServerLayout` section(s). + * Drop `RightOf`/`LeftOf` indication of the remaining `Screen` line + in `ServerLayout` section. + + +<<< +Basic xrandr usage +------------------ + +Once the configuration file (`xorg.conf`) is removed or updated, +starting the server should enable some outputs by default. Their +top-left corners will be at the same part of the image, but their +modes will probably be different. + +All outputs may be configured through `xrandr`. To see the available +outputs, just run `xrandr`: + +---- +$ xrandr +Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096 +VGA1 disconnected (normal left inverted right x axis y axis) +LVDS1 connected 1280x800+0+0 inverted X and Y axis (normal left inverted right x axis y axis) 261mm x 163mm + 1280x800 59.8*+ + 1024x768 60.0 + 800x600 60.3 56.2 + 640x480 59.9 +DVI1 disconnected (normal left inverted right x axis y axis) +TV1 disconnected (normal left inverted right x axis y axis) +---- + +Comments: + + * We see 4 outputs: `VGA1`, `LVDS1`, `DVI1`, `TV1`. + * Only the internal panel (`LVDS1`) is connected and it supports 4 + modes at 60 Hz, 1 mode at 56 Hz. + * The mode marked with a star (`*`) is the current mode. + * The one marked with a plus (`+`) is the preferred one. Most + monitors report a preferred mode to the driver. And the + server/driver will generally choose it by default. + +*FIXME: Mention output name conventions?* + +When manipulating `VGA1` output properties, you should use: + +---- +$ xrandr --output VGA1 +---- + +Adding/removing heads dynamically +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The old days where you had to restart X when plugging a new monitor +are gone. With `RandR` 1.2, you can plug/unplug monitors whenever you +want. Running the following line will query all outputs and enable +them with their default mode: + +---- +$ xrandr --auto +---- + +You may also disable one output using: + +---- +$ xrandr --output LVDS1 --off +---- + +This may be useful for some buggy application that don’t support +multiple outputs well. Also, due to CRTC limitations (see the Caveats +section below), it is often required to disable one output before +enabling another since most hardware only support 2 at the same time. + +Changing the mode +~~~~~~~~~~~~~~~~~ + +With the above `xrandr` output, you may change the `LVDS1` mode to +`1024x768` using: + +---- +$ xrandr --output LVDS1 --mode 1024x768 +---- + +The refresh rate may also be changed, either at the same time or +independently: + +---- +$ xrandr --output LVDS1 --mode 1024x768 --rate 75 +$ xrandr --output LVDS1 --rate 75 +---- + +To get back to the default mode: + +---- +$ xrandr --output LVDS1 --auto +---- + + +<<< +Placing outputs in a virtual screen +----------------------------------- + +A bit of configuration for non-KMS setups: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Let’s have a look at the maximal virtual screen size, we see +`4096x4096` in this example: + +---- +$ xrandr|head -1 +Screen 0: minimum 320 x 200, current 1280 x 800, maximum 4096 x 4096 +---- + +With KMS (*FIXME: Link to a page which explains what KMS is*), +there's no need to specify any `Virtual` option. With DRI and without +KMS, that might be needed. Indeed, drivers will often create a default +virtual screen with small dimensions, for instance `1600x1200`, to +reduce memory consumption. + +If you plan to use multiple outputs displaying different zones, you +should configure your `xorg.conf` by adding a `Virtual` line to the +`Display` subsection in the `Screen` section. + +---- +Section "Screen" + … + SubSection "Display" + Depth 24 + Virtual 3000 2000 + EndSubSection +EndSection +---- + +Place outputs +~~~~~~~~~~~~~ + +Outputs are placed using the following options: +`--right-of`/`--left-of`/`--above`/`--below`. For instance, to place +the `VGA1` output virtually-right of the internal panel (`LVDS1`): + +---- +$ xrandr --output VGA1 --right-of LVDS1 +---- + +Note that hardware and memory limitations may severely restrict the +size of your virtual screen, see the Caveats section below. + + +<<< +Adding new modes +---------------- + +Under some circumstances, some modes might be missing. For instance, +if the monitor does not report correct EDID information. Or if the +output didn't have a CRTC available at startup because another output +was using it and you disabled it in the meantime. + +If a mode exist, you may add it to one output with: + +---- +$ xrandr --addmode VGA1 800x600 +---- + +If the mode does not exist, you may first create it by passing a modeline: + +---- +$ xrandr --newmode +---- + +You may create a modeline using the `gtf` or `cvt` tools (shipped in +the `xserver-xorg-core` package). diff --git a/xsf-docs/howtos b/xsf-docs/howtos new file mode 120000 index 0000000..c953de0 --- /dev/null +++ b/xsf-docs/howtos @@ -0,0 +1 @@ +howto \ No newline at end of file diff --git a/xsf-docs/index.txt b/xsf-docs/index.txt new file mode 100644 index 0000000..48400e9 --- /dev/null +++ b/xsf-docs/index.txt @@ -0,0 +1,51 @@ +X Strike Force’s documentation +============================== + +_The “X Strike Force” takes care of packaging X.Org for Debian._ + +{nbsp} + +These documents are shipped in the +http://packages.debian.org/xserver-xorg&exact=1[xserver-xorg] +metapackage (under `/usr/share/doc/xorg`), starting with +`wheezy`. They are also available online at +http://x.debian.net/[x.debian.net], which is an alias for the +longer-to-type +http://pkg-xorg.alioth.debian.org/[pkg-xorg.alioth.debian.org]. + +Getting started +--------------- + + * link:faq/general.html[General FAQ] + +How to… +------- + + * link:howto/report-bugs.html[How to report bugs] + * link:howto/triage-bugs.html[How to triage bugs] + * link:howto/use-gdb.html[How to use GDB] + * link:howto/configure-input.html[How to configure input] + * link:howto/use-xrandr.html[How to configure outputs] + * link:howto/build-mesa.html[How to build mesa] + +Reference documentation +----------------------- + + * link:reference/git-usage.html[Using git for X repositories] + * link:reference/dependencies.html[Dependencies between server and drivers] + * link:reference/squeeze-backports.html[Backports of the whole X stack for squeeze] + * link:reference/upstream-contacts.html[Upstream contacts] + +Other documentation +------------------- + + * link:upstream-features.html[Upstream features] + +Feedback +-------- + + * Sources for these documents are available on + http://git.debian.org/?p=pkg-xorg/debian/xorg.git;a=shortlog;h=xsf-docs[git.debian.org]. + + * Patches, suggestions, flames, etc. are welcome, using the + http://lists.debian.org/debian-x/[debian-x] mailing list. diff --git a/xsf-docs/reference/dependencies.txt b/xsf-docs/reference/dependencies.txt new file mode 100644 index 0000000..4cdf7a9 --- /dev/null +++ b/xsf-docs/reference/dependencies.txt @@ -0,0 +1,260 @@ +Dependencies between server and drivers +======================================= +:toc: +Cyril Brulebois + + +Upstream-side: ABI version numbers +---------------------------------- + +The X server defines several +http://en.wikipedia.org/wiki/Application_binary_interface[ABI] version numbers in the +`hw/xfree86/common/xf86Module.h` header, through the +`SET_ABI_VERSION(maj,min)` macro. In this document, the focus is on +`ABI_VIDEODRV_VERSION` and `ABI_XINPUT_VERSION`, which are +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 +minors. + +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. + +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:1.8.99.904) +---- +To make sure we bump the `debian/serverminver` when there’s a minor +ABI change, there’s a `abibumpcheck` target (on which `clean` +depends), which extracts input and video ABI from the upstream header, +and compares them to the previous ones stored in +`debian/serverminver`, failing and diffing is something changed. + + +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 `2:1.9.4`, 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. + +To make it easy to compute substvars when using `dh`, a `dh` sequence +(`xsf.pm`) is shipped. As of `2:1.9.4-1`, it inserts +`dh_xsf_substvars` right before the `dh_gencontrol` call. Other +repetitive tasks could also be automated this way. + + +<<< +Sample driver packaging +----------------------- + +The following assumes: + + * The upstream build system is sane enough, which lets us run + `autoreconf` at build time. + * It is a `video` driver. For an `input` driver, replace both + `xviddriver` occurrences with `xinpdriver`. + +Sample debian/control file +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +---- +Build-Depends: + debhelper (>= 8), + dh-autoreconf, + quilt, + xserver-xorg-dev (>= 2:1.9.4), +---- + +---- +Depends: + ${shlibs:Depends}, + ${misc:Depends}, + ${xviddriver:Depends}, +Provides: + ${xviddriver:Provides} +---- + +Sample debian/rules file +~~~~~~~~~~~~~~~~~~~~~~~~ + +---- +#!/usr/bin/make -f + +# Configuration: +#override_dh_auto_configure: +# dh_auto_configure -- --with-FOO --without-BAR + +# Install in debian/tmp to retain control through dh_install: +override_dh_auto_install: + dh_auto_install --destdir=debian/tmp + +# Kill *.la files, and forget no-one: +override_dh_install: + find debian/tmp -name '*.la' -delete + dh_install --fail-missing + +## Debug package: +#override_dh_strip: +# dh_strip --dbg-package=xserver-xorg-video-DRIVER-dbg + +# That's a plugin, use appropriate warning level: +override_dh_shlibdeps: + dh_shlibdeps -- --warnings=6 + +%: + dh $@ --with quilt,autoreconf,xsf --builddirectory=build/ +---- + +Some comments: + + * `dh_auto_configure`: Commented out since there’s usually no + specific option to pass when building drivers. Sometimes needed to + get a related utility built. + * `dh_auto_install`: It behaves differently when operating on a + single package (it installs under `debian/PACKAGE` instead of + `debian/tmp`), so make it use `debian/tmp` in all cases. This way, + `dh_install` has to be used (see below). That also means that a + binary package (_e.g._ a debug package) can be added without + changing this part. + * `dh_install`: No point in keeping the `.la` files. Also, using + `--fail-missing` makes sure every file installed by upstream is + installed in some package, or explicitly ignored. + * `dh_strip`: Commented out, there’s only a few drivers shipping a + debug package. + * `dh_shlibdeps`: The comment really says it all. + * `dh`: The order is important! We want patching to happen before + autoreconfiguring (both `quilt` and `autoreconf` insert commands + before `dh_auto_configure`, and after `dh_clean`). Also, we build + out-of-tree. The `xsf` sequence is explained in the previous part. + +If one needs to build several flavours, +http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-fbdev.git;a=blob;f=debian/rules[++fbdev++’s rules file] +can be used as an example. + + +<<< +Handling a transition +--------------------- + +When a new major version of the server comes up, it can be updated +following its `README.source`. Usually, drivers can be rebuilt using +binNMUs. Be sure `xorg-server` is marked as `Installed` on all +buildds, or set a `dep-wait`. + +On the release team side, a transition page can be asked for, to track +fully rebuilt drivers. For the input 12→13 and video 10→11 +transitions, the settings are: + + * Affected: `.build-depends ~ /xserver-xorg-dev/` + * Good: `.depends ~ /xorg-input-abi-13/ | .depends ~ /xorg-video-abi-11/` + * Bad: `.depends ~ /xorg-input-abi-12/ | .depends ~ /xorg-video-abi-10/` + + +<<< +Staying tuned +------------- + +Staying informed of driver-related changes can be a bit difficult in +the following cases: + + * If one maintains a single driver within the X Strike Force, one + might not notice the few mails about drivers in the heavy mail flow + on `debian-x@`. + * If one maintains a driver outside the X Strike Force, one is + probably not subscribed to the mailing list at all. + +For those reasons, a mail alias is being set up to gather all +maintainers interested in receiving driver-related mails. diff --git a/xsf-docs/reference/experimental.txt b/xsf-docs/reference/experimental.txt new file mode 100644 index 0000000..522ef3f --- /dev/null +++ b/xsf-docs/reference/experimental.txt @@ -0,0 +1,98 @@ +Handling multiple server versions thanks to experimental +======================================================== +Cyril Brulebois + + +Context +------- + +A quick overview of how things work upstream for the server: + + * Patches get reviewed and merged into the `master` branch. + * After a few release candidates, `master` gets tagged (say: `1.10` + or `1.10.0`), and a stable branch (`server-1.10-branch` in this + case) is created to receive bug fixes. + * Those bug fixes usually are cherry-picks from commits in the + `master` branch. + * This leads to stable bugfix releases: `1.10.1`, `1.10.2`, and + so on. + +It doesn’t make much sense to try and package `master` on a continuous +fashion, since the ABI can be broken multiple times, without a bump +for the ABI version numbers every time. It’s usually done once a bunch +of major changes landed, and when things are supposed to be stable +for a while. On the packaging side, as explained on the +link:dependencies.html[dependencies between server and drivers] page, +a bump means the need for a rebuild of the relevant drivers (input +and/or video). + +That’s why the idea is to concentrate on upstream release candidates +and official releases. Depending on available developer time (both +upstream and in Debian), several branches can be developed/maintained +in parallel, so it can be worth having several versions available in +parallel, which is where `experimental` is handy. + +Keeping on with this example, with `1.9` in `unstable`, release +candidates for `1.10` can be uploaded to `experimental`, along with a +few drivers so that it’s actually useful. + + +Selecting drivers +----------------- + +To avoid repetitive and sometimes pointless work, it’s probably a good +idea to upload (to `experimental` as well) only a few drivers built +against the server in `experimental`. ABI might be bumped between +release candidates (that happened between `1.10rc3` and `1.10` for +example), so drivers would need to be rebuilt (even though binNMUs +might help). + +The proposed drivers can be seen on the +link:squeeze-backports.html[backports policy for squeeze] page, along +with a tiny description for each. + + +Building drivers in experimental +-------------------------------- + +Having a driver in `experimental` doesn’t change much: It is sufficient +to declare a build-dependency against `xserver-xorg-dev (>= +$serverminver)`, where `$serverminver` can be seen in: + + * `debian/serverminver` in the `xorg-server` source package: see its + first line. + * `/usr/share/xserver-xorg/inputdrvdep`: see the needed version of + `xserver-xorg-core`. + * `/usr/share/xserver-xorg/videodrvdep`: ditto. + +So, for a given version of a driver in `unstable`, bumping the +build-dep version and uploading to `experimental` should be enough, +providing it doesn’t require further changes (source code changes are +sometimes needed to support building against a newer server). When +that happens, the revision number can be constructed by appending +`+exp1`. The idea here is to avoid things like: + + * `1.42-1` to `unstable`. + * `1.42-2` to `experimental`: bump the build-dep. + * `1.42-3` to `unstable`: revert the build-dep bump, add a bugfix. + * `1.42-4` to `experimental`: build the build-dep again, keep the bugfix. + * etc. + +Instead, that seems more natural: + + * `1.42-1` to `unstable`. + * `1.42-1+exp1` to `experimental`: bump the build-dep. + * `1.42-2` to `unstable`: add a bugfix to ++unstable++’s version. + * `1.42-2+exp1` to `experimental`: rebuild against experimental + (merging or rebasing the build-dep bump). + +**** +.Note + +Remember `experimental` is special. With the above sequence of +uploads, if the `1.42-2+exp1` version isn’t uploaded, the +`1.42-1+exp1` upload might disappear from `experimental` after some +time, since the version in `unstable` is more recent: the “obsolete” +package goes away. That’s why it’s important to remember uploading to +`experimental` as well when uploading a new driver to `unstable`. +**** diff --git a/xsf-docs/reference/git-usage.txt b/xsf-docs/reference/git-usage.txt new file mode 100644 index 0000000..f2adb1f --- /dev/null +++ b/xsf-docs/reference/git-usage.txt @@ -0,0 +1,200 @@ +Git usage +========= +:toc: +Cyril Brulebois + + +[NOTE] +The old documentation is still available on the wiki: +http://wiki.debian.org/XStrikeForce/git-usage[wiki.debian.org/XSF/git-usage]; +this documentation is just a draft for now. + + +Getting started +--------------- + +Upstream repositories are hosted on +http://cgit.freedesktop.org/[git.freedesktop.org] + +Debian repositories are hosted on +http://git.debian.org/[git.debian.org] under the `pkg-xorg/*` +namespace. Each repository is about a single Debian source package. + +We have two types of repositories: + +* *regular* packages: 1 upstream repository → 1 Debian repository → 1 + Debian source package (non-native). +* *bundle* packages: multiple upstream repositories → 1 Debian + repository → 1 Debian source package (native). + +A local git repository can have several remotes. In the context of +Debian packaging, one usually starts by cloning the Debian repository, +so `origin` will likely point to `git.debian.org`. One can use +`upstream` to point to `anongit.freedesktop.org`. The following +documentation assumes this convention. + +The following bits in `~/.gitconfig` will make it possible to fetch +updates using the `git` protocol (anonymously), and to push updates +through `ssh` without having to fiddle with the remote’s URL (in other +words: using `git://git.debian.org` everywhere): + +---- +[url "ssh://git.debian.org"] + pushInsteadOf = "git://git.debian.org" +---- + +To get the repository from `git.debian.org` one can run `debcheckout +$package` (or `debcheckout $package $package.git`), which will use the +`Vcs-Git` fields in the APT cache to pick the appropriate git +location. To add the `upstream` remote (using the info stored in +`debian/watch`), one can use `xsf-remote-add-upstream` script from the +http://git.debian.org/?p=pkg-xorg/debian/xsf-tools.git[pkg-xorg/debian/xsf-tools.git] +repository. + +**TODO:** There will be more information about how to deal with the +many repositories maintained by the X Strike Force in a later chapter. + +The usual workflow is to keep the target suite in `debian/changelog` +to `UNRELEASED` until the upload happens, the last commit before a +commit being only `dch -r`. To achieve that, and to avoid noise since +those packages are comaintained, it’s advised to set the following +variable in `~/.devscripts`: + +---- +DEBCHANGE_RELEASE_HEURISTIC=changelog +---- + + +Regular packages +---------------- + +For most packages (exceptions include `xorg-server`), development is +linear, and happens in a `master` branch. That `master` branch is +pushed in the Debian repository as `upstream-$suite` +(e.g. `upstream-unstable`), depending on the target suite. Usually, +`upstream-unstable` tracks `upstream/master`. + +The packaging is kept in `debian-$suite` branches, branched from +`upstream-$suite`. When cloning a Debian repository, the default +branch is `debian-unstable`. + +To create the initial packaging from the `upstream-unstable` branch, +just run `git checkout -b debian-unstable`, add packaging files +(`changelog`, `control`, `copyright`, `rules` etc. under `debian/`), +and that’s it. + +Here’s how to merge from upstream (`$foo` being a tag or +`upstream/master`): + +---- + git checkout upstream-unstable + git merge $foo + git log $foo > ChangeLog + dch -v $debianrevision + git commit -am 'Bump changelogs.' +---- + +`$debianrevision` is usually `$foo` with `-1` appended (first upload), +and sometimes prepended with a epoch (for example `2:`). Passing +`$foo-1` is usually a good rule of thumb, since `dch` will complain if +the epoch is missing (given the specified version string wouldn’t be +newer than the current one). + +When development isn’t linear +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For packages like `xorg-server` and `libx11`, there are stable +branches which receive updates for a while. Trying to switch from +`1.10.2` to `1.11.0` might trigger a lot of conflicts. But in the end +what matters is the changes between `upstream-$suite` and +`debian-$suite`. Here’s an example, supposing `upstream-unstable` and +`debian-unstable` are pointing to the “old” branches, and supposing +the new branch is `upstream/master`: + +---- +git checkout -b debian-unstable-new upstream/master +git merge -s ours upstream-unstable +git merge debian-unstable +git branch -d debian-unstable +git branch -m debian-unstable +---- + +Subtitles: + +* Create a `debian-unstable-new` branch starting with the upstream + `master` branch, and switch to it. +* “Merge” the old `upstream-unstable` branch, actually keeping only + the new upstream branch. +* Merge the old packaging on top of it. +* Remove the old branch (so that the name can be reused). +* Rename the current `debian-unstable-new` branch into + `debian-unstable`. + +Since the tip of the new `debian-unstable` branch is a descendant of +the tip of the old `debian-unstable` one, it can be pushed normally. + +Since old `upstream-unstable` and new `upstream-unstable` diverged, +this branch has to be pushed with a `-f` to force the update (it’s not +a fast-forward). + + +Bundle packages +--------------- + +One bundle package is a Debian native package, with just a (Debian) +tarball, instead of an upstream tarball plus a Debian diff. + +There is no upstream branches here, only `debian-$suite`. + +The repository contains a `debian/` directory for the packaging, and +one directory per upstream source. Merging a new upstream release +means updating the contents of the relevant directory with the +contents of the new upstream tarball. Fetching new tarballs is +automated through a specific target: `make -f debian/rules +get-tarballs` + +To perform an update, first run `dch -i` to create a new changelog +entry if the previous commit was an upload (the new entry targets the +`UNRELEASED` suite, see “Foreword”). + +Assuming `get-tarballs` made `foo-bar.tar.gz` appear in the top-level +directory, here’s how to update (trailing slashes are not needed, just +there to clarify we’re working on directories): + +---- +git rm -r foo/ +tar xf foo-bar.tar.gz +mv foo-bar/ foo/ +git add foo/ +dch "foo bar" +debcommit -a +---- + +Using the `xsf-remote-add-upstream` script will create several +`upstream-$foo` remotes, using info stored in `debian/watch*`. This +helps browsing the history of a given repository (rather than having +to look at a big fat diff with autogenerated files in the middle). + + +Upgrade checklist +----------------- + +[NOTE] +Since it’s likely for a reader of this page to be on her way to update +a package, here’s a tiny upgrade checklist. + +Basic checks include looking into what happened to those files since +the last packaging update: + +* `COPYING`: Update `debian/copyright` accordingly. +* `configure.ac` (or `configure.in`): Update (build-)dependencies + accordingly. + +About xorg macros (they show up very often in the diff), they’re +shipped in the `xutils-dev` package, which contains a file to help map +macro versions and package versions: +`/usr/share/doc/xutils-dev/versions` + +Some packages might have more specific instructions. That’s the case +for at least `xorg-server`. See its `debian/README.source`, below the +generic “how to use quilt” blurb. diff --git a/xsf-docs/reference/squeeze-backports.txt b/xsf-docs/reference/squeeze-backports.txt new file mode 100644 index 0000000..20fb996 --- /dev/null +++ b/xsf-docs/reference/squeeze-backports.txt @@ -0,0 +1,70 @@ +Backports for squeeze +===================== +Cyril Brulebois + + +Bird’s-eye view +--------------- + +If one forgets about libraries and clients, a whole X stack boils down +to: the server itself, input and video drivers, libdrm, and mesa. + +To keep things simple, the idea is to backport all of those to +`squeeze` through `squeeze-backports`, along with some of the +additional packages which might be involved (like `libxfont` or +`x11proto-fixes-dev`). + +The backports were prepared so that it’s possible to upgrade the +`input-all` and `video-all` meta packages on `amd64` and `i386`. If +specific drivers (maintained by the X Strike Force) are wanted, +requesting them on the `debian-backports@` / `debian-x@` mailing lists +should do the trick. For other drivers, please contact the relevant +package maintainers. + + +Instructions +------------ + +The usual link:http://backports-master.debian.org/[backports instructions] +apply. But let’s gather everything in a single place. + +Add that to your `sources.list`: +---- +deb http://backports.debian.org/debian-backports squeeze-backports main +---- + +Update your cache: +---- +apt-get update +---- + +If you’re interested in just upgrading the usual `mesa` packages: +---- +apt-get install -t squeeze-backports libgl1-mesa-dri libgl1-mesa-glx +---- + +If you want the whole stack, we should distinguish between two +cases. + +In the usual case, both the `xserver-xorg-input-all` and +`xserver-xorg-video-all` meta packages were installed, and pulled a +lot of packages, which should work for most users. +Specifying a few packages to upgrade should pull +everything from `squeeze-backports`. + +---- +apt-get install -t squeeze-backports xorg xserver-xorg xserver-xorg-core xserver-xorg-input-all xserver-xorg-video-all +apt-get install -t squeeze-backports libgl1-mesa-dri libgl1-mesa-glx +---- + +In case only the needed packages were installed, like the `synaptics` +input driver and the `intel` video driver, the following should be +sufficient: +---- +apt-get install -t squeeze-backports xorg xserver-xorg xserver-xorg-core xserver-xorg-input-synaptics xserver-xorg-video-intel +apt-get install -t squeeze-backports libgl1-mesa-dri libgl1-mesa-glx +---- + +It is probably a very good idea to install the Linux kernel from +`squeeze-backports` as well. It is even required for the `nouveau` +video driver. diff --git a/xsf-docs/reference/upstream-contacts.txt b/xsf-docs/reference/upstream-contacts.txt new file mode 100644 index 0000000..8857bbb --- /dev/null +++ b/xsf-docs/reference/upstream-contacts.txt @@ -0,0 +1,46 @@ +Upstream contacts +================= +:toc: +Cyril Brulebois + + +Getting announcements +--------------------- + + * Almost everything: `xorg-announce@lists.freedesktop.org` + * Mesa: `mesa-announce@lists.freedesktop.org` + +_(Source: http://wiki.x.org/wiki/XorgMailingLists[XorgMailingLists])_ + + +Developer lists +--------------- + + +Almost everything: + + * `xorg-devel@lists.freedesktop.org` — doc: + http://wiki.x.org/wiki/Development/Documentation/SubmittingPatches[SubmittingPatches] + — module maintainers: + http://cgit.freedesktop.org/xorg/doc/xorg-docs/tree/MAINTAINERS[MAINTAINERS] + +Driver-specific: + + * ATI: `xorg-driver-ati@lists.x.org` + * Intel: `intel-gfx@lists.freedesktop.org` — doc: + http://intellinuxgraphics.org/how_to_report_bug.html[How to file a good bug report] + * Nouveau: `nouveau@lists.freedesktop.org` + * VMMouse & VMWare: `thellstrom@vmware.com` — source: + http://wiki.x.org/wiki/vmware[vmware wikipage] + +Other: + + * DRM: `dri-devel@lists.freedesktop.org` + * Mesa: `mesa-dev@lists.freedesktop.org` + * Pixman: `pixman@lists.freedesktop.org` + * Wayland: `wayland-devel@lists.freedesktop.org` + * XCB: `xcb@lists.freedesktop.org` + * XKeyboardConfig/xkb-data: `xkb@listserv.bat.ru` — source: + http://www.freedesktop.org/wiki/Software/XKeyboardConfig/Development[XKeyboardConfig] + +_(Source: http://wiki.x.org/wiki/XorgMailingLists[XorgMailingLists])_ diff --git a/xsf-docs/upstream-features.txt b/xsf-docs/upstream-features.txt new file mode 100644 index 0000000..c944cf1 --- /dev/null +++ b/xsf-docs/upstream-features.txt @@ -0,0 +1,17 @@ +Upstream features +================= +Cyril Brulebois + + +Let’s collect links where one can learn more about features. It might +make sense to ask permission to (re)use those and merge them into this +package, in case the hosting sites go offline. + +Multitouch/touchpads +-------------------- + +Touchpad features, by Peter Hutterer: + +→ http://who-t.blogspot.com/2010/06/incomplete-roundup-of-touchpad-features.html + +What multitouch really is about, by Peter Hutterer: + +→ http://who-t.blogspot.com/2010/10/thoughts-on-linux-multitouch.html diff --git a/xsf-docs/xsf.css b/xsf-docs/xsf.css new file mode 100644 index 0000000..855416f --- /dev/null +++ b/xsf-docs/xsf.css @@ -0,0 +1,8 @@ +@import url("asciidoc-xhtml11.css"); + +h1 { + background-image: url("xsf.svg"); + background-repeat: no-repeat; + background-position: center right; + background-size: auto 95%; +} diff --git a/xsf-docs/xsf.png b/xsf-docs/xsf.png new file mode 100644 index 0000000000000000000000000000000000000000..19c1ec27bab1c3b1c58b3332c413a149b12f423f GIT binary patch literal 3914 zcmV-Q54G@#P)0Hgl~%qs-8Bxnl(=Vu+urGR@q)WSEjc|?wq zflnvVb-SxrE(MstyBuIJb}5LcY!&SvxZ-Z3!n zt|YvRa}qm80?+GxuemX>9XS0cnm3jH-L8#5!QYI5y+VKCp%$(K{HbE^rlw#WGYUVZ z#;+h*Xet5rCU6}FN^^DH(o5tSB4Pq>17FXy%qS^fvJ7LgF^o%%(Vvf%L5C6A1vS)? z%?7&DLc+i79>eO3}ZZvo#(pq;I%E4*HBA5X3f z1Q3yNz$WY#uOCXJfJ=?hoMQ~^4*sd&Coq4(thl6M=k}al5e_ zu9wA-7t6brzvosU!2$~`a`~PDvVdraSG!UJ!PkMTs}q$3j_VUPYxA6 z5Vanv=y~N;H`ndiz=opQ5{X3a6Zk%m=afH$#eVIkMSFP7+D(1*GlKMcnnJ(@s=7WK zEh6%J;FbU;ml!2{+Z@X`jgqhr!%>&OM#Z`}TO&Og*jP~gT~VIEo*qhxFc$Av`&k{` z!`s$gy89cJ44(jJt7=CknMLGA>`_rHUSGw9HD!U3HLBbXjCBm8EVV+uc~x4M8Lt}y z8>H56=0_H)UF#%8wg}MlCu{$xy6C4P-n2f?ng@7BRlnzyNkk?B?-PF`cVpjx0|0xZ zwxH7=zC%TR3KTg++%A?}TOL}r&XL>6z^1{~CtB^kVBZ~)`;ErHrWZx2O%ZaZs`Yy_ zKf0u>ZPfu0IT_eYimputxL#FXNO=Jw#lVL^c}#K`n5wFOPR!p>R9j+1A`5|P2i|s7 zE~pHy*qSbrR9YFV|8-g0ssjM3x*NE~ zi6;%75Ruc;{Jw~I^8kL5%shaqj=Fsn!82<>7o?0Rv;rLnbsJ??+8dwoBivXp`zBF+ zjQ%ZbJIMW=!QqefwUWt*M3w+^Ga~Dc4}gnQH7>r0%mW@x$osOYrg%Ey(Ud>ypAq?G zLh_c1o)wcC0y9eu%tiZxt(RS_Z%0za$jHFv!s?4Gi?;xOY`QAX;gh>6JD2ZuiXkFJ zz(+u-BVi2u7>t)9E-^}8`LX$xbqW&@J@}E;DvP7dKiZ>R=I7c)J7KUVN2jQ2d#3Rl z^Q)f~;f93d{fK_Yvb4oCtnTveRXbCaPr0z(=%0P|{_w%gqXNUmh_ZqN^8{U85v;#4 zQ=zKbAtKiSYt!)p6qCozzB0aTjNwGdXRCFH9olx)T5Z{LzA@sZMm=1xFxvQ37|R?h zgMSp;4(CwWKiAcvQtoG;ky;cUA@Kr#DFLuyo~9UWgHnd~z`tTTRxc z7ZFAz{QMUr`h#qQ0;uYTB62T~_}BoDkI4<@Y0NcGXM=vp{73_9tbKIR_XJG@egv!r zMkW-$StI&fgVYXdklLb5yCLPFW$T&()oXx@W0FN+FCtQIaBg!ox_0}cImRdfO80#{>i#fZgX zRlUiL9)PAm^>iSi11&qPpjlC+b)j@+Q?|mN%G>~GznY>dbKRO}msbn80cbsvHrG6z zNAkYPdi|1`(3)iC0o)3lguSF1i;Y0mPeYt02qsA#ZRS~%oXVy&@DyFzW5@n01a?;j zm)E<{7%xqA5AY8F(~Xn)iEkp!+QvQM4TQ0h6FV|ReMr#H4naWcm{$7 zB}omaM8`W7b?OK1isP|c(VRe4mjO#|^Hm_gqDV76$%lBGfFA>OK%yBxSJfTqcp_o* zOeZZOGBt_9*DHec%bm(P85sY96gD~q%o6hgm|-Bcp@>Br_6DE_u(y;X;${&^JFQjK zUH_J&3f032DSz<6ZOHwO0}ZDPadSdyY0hdOfU0($DEWuLeh((WO~7RAmNyyB1Rm~} zDkAIU7RMQwJ{=-w#e9tzmM$voso&9D@bPG;vQ7rZy^stw_hc$6Q{<`f8o)$jC?`qW zq|O5D$9J(qh}%VET5Q6${OTEng$Eqpea(fnW40B{dO%?2ku*W)m4)g**j`*a;`8n= z_B+LJGVnm`7d5S9FI!Kj39VV)qCMnevM}#FdM83Zz;11qVXr%wwIewE zznn%#+hk_3rIF35@{8W27D4Bi_tZaui1<1NwWk}x9YI*!6-wt8heK=sJt)e zf{xILI;Yy|cpYhHV??Aef7ZtWl}D0PsH^N=ag8TZk?FuHdS|nJ7(}q%dADHN4a2R1 z>3_Bk%z4*pIk!X#xY9hC;@+i}&$N>*+R7HIm5=ohiZTR0gC&o__!%O3j3V&GRmS)? zOffD1J++rI1gueHWuC#R(yrw>YYZKyv$hpf&sAkfOi~EZX%*e|Yg`eEoC0hBVi$>9 zfXS-57hsiKGV~c^=h`x3NM!(%DaMJsXSGm($ygc07%60g1TcHoeE|#v3uT{n(@o^F z2{L%K*y}3IzF^NgrMkM!jb6v=aWb$$YW+rjWHa%zzJ~=}YAOE{4t4$aBz?UzBQm?w z`z|mgCfNeMrK)cw;1pI_mO*jE;Jh_pIC|@Eu4pSXCJp4n;0?iqSinnrPk|z`v#{qpB}M-0S17 zzme8FuypTzfJPf9*gKDsk%2JQi;8C7TXcu1Dtha*)gR+kwMt+ z%(9Gy#v^6dCKt%+uwiA-^7#mJ=s$lp*1(vzMlR_$!`*AZa^lU40M|H~2ljXwxDI=% z(hVLFkt&yE9g+2E&5G_7PpcspW4~i!AU_-(IN_lrMV=z28`O)tRdsEqoV{B-ex9Au zJ`?~iI?dX+h3l;y&4smNq8eEt%DFMgmMHg@hkU<6>!KoZE0Fm3tW?#jvKDHe7<~h{ z%#~o6ud4s#vTRCt+gv2IW>bFnR*;8?Z=v6NGSa;8$!OEkZlbYwekb;J3+H2`$>>Bz zWAAcso@MTjqtdm>$@aFbMKed`g^hnxdxK9OUW)GI!N?{oyS)qo7iPQTDiIFncDHDv%Mdy1+T?nZ`8Tk4#+v{m zCBRK)*_YRwr}Y@fn7(|-uL(vTD%X`6Z^1~yH4)pyfQ#aBvo>Ck%VQ2D*sFFWG09!n zhYGiD^Itv1GIgfdE$~Djg0c>SHKObd8&>_qu2*(v$@v59sed=v44kW~N!En3(2xrQ z)11keqpD9Q=HDKeH6e;zVJTk~;Vhs6h=^*PCGu=#(D%nochQT;tH5-Z(mi)=a%JGd z*#GJgi;TBh?2+1nwt~V$pwE#i+;Z6Zf!(K6I`5toLBzZO7Wc$CHS7?0A?Lqp2MGG?NfGU0|t7;fPo${V4z3* YA7qgnSpgAf(EtDd07*qoM6N<$f{ + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + +