Differences between revisions 20 and 21
Revision 20 as of 2008-07-25 11:26:58
Size: 12093
Editor: host120-254-dynamic
Comment: Added screencast on Phase 1
Revision 21 as of 2008-07-25 11:29:58
Size: 12099
Editor: host120-254-dynamic
Deletions are marked like this. Additions are marked like this.
Line 49: Line 49:
UPDATE: the Python part is complete. '''UPDATE:''' the Python part is complete.


Implements an xorg.conf editor for adding/removing/changing driver and server options. This is done in two phases: The first phase simply establishes the foundations (parser, backend, etc.) and provides for setting the "Virtual" Option. The second phase implements the full GUI editing capability.


Xorg's configuration system has matured greatly in recent years, to the point that editing xorg.conf is usually unnecessary: the X server autodetects pretty much everything, and distro install scripts can largely take care of the remainder. With the introduction of Xrandr, many common configuration tasks (like setting resolutions) that used to be done by editing xorg.conf and restarting can now be done at run-time using GUI tools like Screen Resolution.

However, there are still many little corner cases where the user will need or wish to make adjustments to X that can currently only be done in xorg.conf; largely, these cases involve setting one or more Options either in a Device section or in the ServerFlags section. For example, we may wish them to turn off certain things for testing purposes, or they may wish to experiment with settings to attain better performance or stability than they get with the defaults.

A GUI tool makes these settings more accessible to users, which will make Ubuntu's users better able to participate in troubleshooting X problems and in getting the most out of their systems.


This is not a general purpose "fix broken X" tool. In many cases where setting Options is required to fix X, it's needed because X won't start up at all, and therefore the user isn't in a GUI environment anyway. Thus this spec isn't concerned with providing functionality for selecting the driver, altering monitor settings, and so on.

This is not considered to be a tool that very many users will need to use, and thus is intended to be available only via an "Advanced..." button or the like.

Use Cases

  • Terri wishes to set up a dual-head display on Intrepid, but this requires setting Option "Virtual" "3840 1200" in xorg.conf, which she is not comfortable editing. Instead she uses the X Options Editor to specify it.

  • Sarah reads in a bug report that using Option "VideoKey" "0x01" resolved a problem very similar to hers. She uses X Options Editor to add this option, restarts, and can easily test it out.

  • Leann wishes to report an X bug, but reads that she should enable Option "NoTrapSignals"  "true" first so she collects correct debug info.

  • Kirsten hates how ctrl+alt+backspace exits her system. She shuts it off by toggling the Option "DontZap" "true" option.


The editor's overall architecture will be split into frontend and backend modules, with the idea of sharing the backend with other tools which need to modify xorg.conf. The philosophy is that the fewer chunks of code we have that are modifying xorg.conf, the more consistent the result will be. Also, obviously this allows sharing code maintenance of this part. (As an example, we could use the same parser/writer lib with Jockey and in the installer.)

The GUI editor itself will be composed of a list of xorg.conf sections with options available for modification (e.g. Device and ServerFlags). Selecting a section will display a table of options and their values that the user can modify. On hitting Apply, the xorg.conf will be backed up and modified, and the user prompted to restart X for the changes to take effect.

Phase 1: Foundations + Option "Virtual"

The first portion of the project will focus on a single goal: Providing a mechanism to add "Virtual" option settings to xorg.conf without requiring the user to edit that file directly. Ideally, this should be hooked into the Screen Resolution tool to set the option automatically when the user chooses a dual head layout beyond the limits of the current virtual framebuffer size.

This means the focus will be first on the implementation of the backend xorg.conf parser/writer, not on the GUI editor.

Phase 1 is to be delivered for Intrepid by Alpha 1. Depending on the complexity of its implementation, it may be appropriate to SRU this feature to Hardy as well.

UPDATE: the Python part is complete. [http://www.albertomilone.com/screen_resolution.ogg Here] it is possible to see a screencast of the Python part (still WIP) in action. The screencast doesn't reflect the current status however it gives an idea of how this will work in practice. The Python script can be called with:

python multiscreen.py 0,0:1024x768 1024,0:1280x1024 0,768:1024x768

i.e. "x_position","y_position":"h_resolution"x"v_resolution"

Phase 2: GUI Editor

The remainder of the work to implement the GUI will be done in the second phase, and is a much lower priority than phase 1.

Phase 2 is to be delivered by Intrepid+1's feature freeze date. If there is an implementation considered "ready" enough prior to Intrepid's feature freeze, it would be nice to ship it in Intrepid for testing purposes.


The backend (X-Kit) consists of the following:

  • A simple xorg.conf parser and writer. This could be inspired/derived from Guidance's "xorgconfig", but its API should be made easier for developer use, easier to extend, and easier to maintain.) See https://launchpad.net/xorgparser

  • An xorg.conf validator. Given an xorg.conf it should perform a sanity-check of the file. The idea is to allow xorg-conf-editing applications to detect if the user's xorg.conf is in a form that can be successfully edited, and to bail out gracefully if not.

  • An options data store. This provides the listing of available options, default values, and so on.

The frontend is a GUI dialog allowing the user to browse the xorg.conf sections that have modifiable options, to modify them, and apply the settings.

Implementation of xorg.conf Parser and Writer

XorgParser doesn't depend on any other Python module (apart from the 'sys' module) and provides a transparent way to read and write the xorg.conf. It is very easy to extend by reusing its methods which are widely documented.

XorgParser allows to get and set options, create and remove new sections, subsections, get, set and remove references to other sections, etc.

Simple API. A small set of methods should be enough to create more advanced functionalities. The main metaphor here is that each entry (e.g. driver entries, references, etc.) is an option. Only the names of the sections are hardcoded.

Easy to extend: xutils.py is an extension of xorgparser.py. It would be easy to either extend xutils or ignore xutils and extend xorgparser so as to implement more advanced features.

The code of the first release is available [https://launchpad.net/xorgparser/0.1 here].

Implementation of xorg.conf Validator

Validator should look for references to other sections inside of section. For example it would be interesting to see what references to other Device and Monitor sections are located in a Screen section (when available) or if references to Screen sections are available in the ServerLayout section.

Validator would have to make sense of the xorg.conf and see if it has a coherent structure and maybe try to fix it.

Validator should prevent the XorgOptionsEditor from making the xorg.conf unusable.

Implementation of Options Data Store

The Options Data Store is a collection of options available for each driver and the server. This data should be kept in an easily parsed/written XML format, with the following structure:

  • Option name
  • Option type: none | boolean | number | string
  • Short one sentence description

Much of this data can simply be extracted from the man pages. A script will be implemented to perform this conversion and output the XML data format. If any errors are found in the man pages from this conversion, the fixes need to be forwarded upstream for the appropriate man page.

An experimental implementation of the Options Data Store is available as of June 8 2008.

GTK GUI Frontend

A quick mockup based on the meeting which took place at the UDS:


[Note: In the above mockup, two column headers are included; obviously it should list only one at most.]

UPDATE: A screenshot of the prototype (July 07 2008)


UPDATE: A screenshot of the real application (July 25 2008)


[http://www.albertomilone.com/xorgoptionsedit.ogg Here] it is possible to see a screencast of the prototype in action. I uses XKit's parser already.

[http://www.albertomilone.com/xorgoptionseditor.ogg Here] it is possible to see a screencast of the real application (still WIP) in action (July 25 2008).

The GUI frontend will consist of a page showing the current xorg.conf's sections and all available options with their current settings (or their defaults if not set). A visual indicator (such as a checkbox or graying out) should be used to distinguish between options which are listed in xorg.conf vs. those that are not yet. Perhaps only active options should be listed, with an 'Add' button that pops up a secondary dialog to select options, and a Delete button rather than a checkbox for removing them?

The GUI should also permit setting the driver. This could be done either via a separate dropdown. If the xorg.conf omits the driver entirely (thus allowing the xserver to auto-select it), Xorg Options Editor will perform hardware detection and select the appropriate driver as the xserver does.

The GUI should hide all the details of the sections from users so that they will only have to click on a device in the treeView on the left and simply add, remove, enable or disable an option without having to care about which section such option belongs to. For example the user will remove "Virtual" without knowing that it belongs to the Display subsection of a Screen section.

When the user clicks on a device in the treeview, a treeview on the right will display the identifier of its respective Screen section (if available). A 'Misc' section will also be included for setting ServerFlags options (not shown in mockup).

The Description column will store only the 1st line of each description of the options. The full description might be provided in a tooltip when the user moves the mouse cursor over an option. Ideally, this should be implemented in a mechanism that won't require horizontal scrolling (see mockup).

An Apply button will back up the current xorg.conf and apply the changes when pressed. Notification should be made that the user needs to reboot.

The use of PolicyKit is a good idea since it enables us to run the application with user's privileges instead of root's.

If no xorg.conf is available, the program should automatically:

  • create a new xorg.conf
  • create a new Device, Screen and Monitor section (the Screen section should contain references to the other 2 sections) for each card
  • set a driver in the Device section by detecting the pci_id of the graphics card(s) (with lspci -n | grep 300 ) and looking up the id in /usr/share/xserver-xorg/pci/ so that, for example, a GeForce 7300 GT would be assigned the "nv" driver.

Qt GUI Frontend

As soon as the GTK frontend (XorgOptionsEditorGtk) is complete it will be easy to port it to QT4 or KDE4 since the tools used (i.e. the Parser, the Validator and the Options Data Store) are desktop agnostic.

Outstanding Issues

BoF agenda and discussion


X/OptionsEditor (last edited 2008-12-19 16:49:37 by host65-93-dynamic)