nightmorph 09/12/09 01:35:03 Modified: xorg-config.xml Log: The big Xorg HOWOTO rewrite. This should take into account all the xserver 1.5 and 1.6 changes. I emphasized HAL/evdev for device management and configuration. xorg.conf is really only used as a last resort for things like display resolution. bug 267769.
Revision Changes Path 1.32 xml/htdocs/doc/en/xorg-config.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xorg-config.xml?rev=1.32&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xorg-config.xml?rev=1.32&content-type=text/plain diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xorg-config.xml?r1=1.31&r2=1.32 Index: xorg-config.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v retrieving revision 1.31 retrieving revision 1.32 diff -u -r1.31 -r1.32 --- xorg-config.xml 2 Oct 2009 07:37:57 -0000 1.31 +++ xorg-config.xml 9 Dec 2009 01:35:03 -0000 1.32 @@ -1,8 +1,8 @@ <?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.31 2009/10/02 07:37:57 nightmorph Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.32 2009/12/09 01:35:03 nightmorph Exp $ --> -<guide link="/doc/en/xorg-config.xml"> +<guide> <title>The X Server Configuration HOWTO</title> <author title="Author"> @@ -22,8 +22,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>1.22</version> -<date>2009-10-02</date> +<version>1.23</version> +<date>2009-12-08</date> <chapter> <title>What is the X Window Server?</title> @@ -88,31 +88,53 @@ <chapter> <title>Installing Xorg</title> <section> +<title>Kernel configuration</title> <body> <p> -Before installing Xorg you have to configure two important variables in the +By default, Xorg uses <c>evdev</c>, a generic input driver. You'll need to +activate support for <c>evdev</c> by making a change to your kernel +configuration. (Read the +<uri link="/doc/en/kernel-config.xml">Kernel Configuration Guide</uri> if you +don't know how to setup your kernel.) +</p> + +<pre caption="Enabling evdev in the kernel"> +Device Drivers ---> + Input device support ---> + <*> Event interface +</pre> + +</body> +</section> +<section> +<title>make.conf configuration</title> +<body> + +<p> +Before you install Xorg, you have to configure two important variables in the <path>/etc/make.conf</path> file. </p> <p> -The first one is <c>VIDEO_CARDS</c>. This is used to set the video drivers that -you intend to use and is usually based on the kind and brand of card you have. -The most common settings are <c>nvidia</c> for Nvidia cards or <c>fglrx</c> for -ATI Radeon cards. Those are the proprietary drivers from Nvidia and ATI -respectively. If you would like to use the open source versions, use <c>nv</c> -rather than <c>nvidia</c> in the variable, but bear in mind that using this -driver means no 3D acceleration at all. The free <c>radeon</c> and -<c>radeonhd</c> drivers for ATI cards support 3D acceleration on older Radeons -but don't yet support all the features of the newer ones. <c>VIDEO_CARDS</c> may -contain more than one driver, in this case list of them should be separated with -spaces. +The first variable is <c>VIDEO_CARDS</c>. This is used to set the video drivers +that you intend to use and is usually based on the kind and brand of card you +have. The most common settings are <c>nvidia</c> for Nvidia cards or +<c>fglrx</c> for ATI Radeon cards. Those are the proprietary drivers from Nvidia +and ATI respectively. If you would like to use the open source nVidia driver, +use <c>nv</c> rather than <c>nvidia</c> in the variable, but bear in mind that +using this driver means no 3D acceleration at all. The free <c>radeon</c> and +<c>radeonhd</c> drivers are available for ATI cards, and are more or less the +equal of the proprietary <c>fglrx</c> driver. The <c>intel</c> driver may be +used for desktops or laptops with common Intel integrated graphics chipsets. +<c>VIDEO_CARDS</c> may contain more than one driver, in this case list of them +should be separated with spaces. </p> <p> The second variable is <c>INPUT_DEVICES</c> and is used to determine which drivers are to be built for input devices. In most cases setting it to -<c>keyboard mouse</c> should work just fine. If you use alternative input +<c>evdev</c> should work just fine. If you use alternative input devices, such as a Synaptics touchpad for a laptop, be sure to add it to <c>INPUT_DEVICES</c>. </p> @@ -123,27 +145,27 @@ </p> <pre caption="Sample make.conf entries"> -<comment>(For mouse and keyboard support)</comment> -INPUT_DEVICES="keyboard mouse" +<comment>(For mouse, keyboard, and Synaptics touchpad support)</comment> +INPUT_DEVICES="evdev synaptics" <comment>(For Nvidia cards)</comment> VIDEO_CARDS="nvidia" <comment>(OR, for ATI Radeon cards)</comment> -VIDEO_CARDS="fglrx" +VIDEO_CARDS="radeon" </pre> -<p> -More instructions on how to configure nVidia and ATI cards can be found in -<uri link="/doc/en/nvidia-guide.xml">Gentoo Linux nVidia Guide</uri> and in +<note> +More instructions on how to configure nVidia and ATI cards can be found in the +<uri link="/doc/en/nvidia-guide.xml">Gentoo Linux nVidia Guide</uri> and in the <uri link="/doc/en/ati-faq.xml">Gentoo Linux ATI FAQ</uri>. If you don't know which drivers you should choose, refer to these guides for more information. -</p> +</note> -<note> +<p> If the suggested settings don't work for you, you should run <c>emerge -pv xorg-server</c>, check all the options available and choose those which apply to -your system. The example is for the amd64 architecture and -<c>xorg-server-1.2</c>. -</note> +your system. This example is for a system with a keyboard, mouse, Synaptics +touchpad, and a Radeon video card. +</p> <pre caption="Displaying all the driver options available"> # <i>emerge -pv xorg-server</i> @@ -151,16 +173,17 @@ These are the packages that would be merged, in order: Calculating dependencies... done! -[ebuild R ] x11-base/xorg-server-1.2.0-r3 USE="dri nptl xorg (-3dfx) -debug --dmx -ipv6 -kdrive -minimal -sdl -xprint" INPUT_DEVICES="keyboard mouse -acecad --aiptek -calcomp -citron -digitaledge -dmc -dynapro -elo2300 -elographics -evdev --fpit -hyperpen -jamstudio -joystick -magellan -microtouch -mutouch -palmax --penmount -spaceorb -summa -synaptics -tek4957 -ur98 -vmmouse -void -wacom" -VIDEO_CARDS="nvidia -apm -ark -chips -cirrus -cyrix -dummy -epson -fbdev -fglrx --glint -i128 (-i740) -i810 (-impact) (-imstt) -mach64 -mga -neomagic (-newport) -(-nsc) -nv -r128 -radeon -rendition -s3 -s3virge -savage -siliconmotion -sis --sisusb (-sunbw2) (-suncg14) (-suncg3) (-suncg6) (-sunffb) (-sunleo) (-suntcx) --tdfx -tga -trident -tseng -v4l -vesa -vga -via -vmware -voodoo" 0 kB +[ebuild R ] x11-base/xorg-server-1.6.3.901-r2 USE="hal nptl xorg -debug +-dmx -ipv6 -kdrive -minimal -sdl -tslib" 0 kB +[ebuild R ] x11-base/xorg-drivers-1.6 INPUT_DEVICES="evdev synaptics +-acecad -aiptek -citron -elographics -fpit -hyperpen -joystick -keyboard -mouse +-mutouch -penmount -tslib -virtualbox -vmmouse -void -wacom" +VIDEO_CARDS="radeon -apm -ark -ast -chips -cirrus -dummy -epson -fbdev -fglrx +(-geode) -glint -i128 (-i740) (-impact) (-imstt) -intel -mach64 -mga -neomagic +(-newport) -nv -nvidia -r128 -radeonhd -rendition -s3 -s3virge -savage +-siliconmotion -sis -sisusb (-sunbw2) (-suncg14) (-suncg3) (-suncg6) (-sunffb) +(-sunleo) (-suntcx) -tdfx -tga -trident -tseng -v4l (-vermilion) -vesa -via +-virtualbox -vmware (-voodoo) (-xgi)" 0 kB </pre> <p> @@ -173,14 +196,14 @@ <note> You could install the <c>xorg-x11</c> metapackage instead of the more -lightweight xorg-server. Functionally, <c>xorg-x11</c> and <c>xorg-server</c> -are the same. However, <c>xorg-x11</c> brings in many more packages that -you probably don't need, such as a huge assortment of fonts in many different -languages. They're not necessary for a working desktop. +lightweight <c>xorg-server</c>. Functionally, <c>xorg-x11</c> and +<c>xorg-server</c> are the same. However, <c>xorg-x11</c> brings in many more +packages that you probably don't need, such as a huge assortment of fonts in +many different languages. They're not necessary for a working desktop. </note> <p> -When the installation is finished, you might need to re-initialise some +When the installation is finished, you will need to re-initialise some environment variables before you continue. Just run <c>env-update</c> followed by <c>source /etc/profile</c> and you're all set. </p> @@ -193,12 +216,126 @@ </body> </section> </chapter> + <chapter> <title>Configuring Xorg</title> <section> -<title>The xorg.conf File</title> +<title>Using HAL</title> +<body> + +<p> +Recent X server versions are designed to work out-of-the-box, with no need to +manually configure Xorg's configuration files. +</p> + +<p> +You should first try <uri link="#using_startx">starting X</uri> without creating +<path>/etc/X11/xorg.conf</path>. +</p> + +<p> +If Xorg won't start (if there's something wrong with the screen, or with your +keyboard/mouse), then you can try fixing problems by using the right +configuration files. +</p> + +<p> +By default, Xorg uses HAL (Hardware Abstraction Layer) to detect and configure +devices such as keyboards and mice. +</p> + +<p> +HAL comes with many premade device rules, also called policies. These policy +files are available in <path>/usr/share/hal/fdi/policy/</path>. Just find a few +that suit your needs most closely and copy them to +<path>/etc/hal/fdi/policy/</path>. +</p> + +<impo> +Do not edit the files in <path>/usr/share/hal/fdi/</path>! Just copy the ones +you need, and edit them once they're placed in the proper <path>/etc</path> +location. +</impo> + +<p> +For example, to get a basic working keyboard/mouse combination, you could copy +the following files to <path>/etc/hal/fdi/policy/</path>: +</p> + +<pre caption="Using HAL policy files"> +# <i>cp /usr/share/hal/fdi/policy/10osvendor/10-input-policy.fdi /etc/hal/fdi/policy</i> +# <i>cp /usr/share/hal/fdi/policy/10osvendor/10-x11-input.fdi /etc/hal/fdi/policy</i> +</pre> + +<p> +There are several other HAL policies in <path>/usr/share/hal/fdi/</path> that +may interest you, such as laptop configurations, storage device handling, power +management, and more. Just copy any of the policies to +<path>/etc/hal/fdi/policy/</path>. +</p> + +<p> +You can edit the policy files in <path>/etc/hal/fdi/policy</path> to your +liking. You may want to make a few tweaks or to expose additional +functionality. Let's go through an example of tweaking a HAL policy. +</p> + +<p> +One very convenient trick is to kill the X server entirely by pressing +Ctrl-Alt-Backspace. This is useful when your X server is malfunctioning, frozen, +etc. It's not as extreme as rebooting the whole machine with Ctrl-Alt-Del. +</p> + +<p> +Recent X server versions disabled this key combination by default. However, you +can reenable it by copying <path>10-x11-input.fdi</path> to +<path>/etc/hal/fdi/policy</path> and editing it. You'll need to add just one +line to the appropriate section, as shown below: +</p> + +<pre caption="Editing 10-x11-input.fdi"> +<comment>(Open the file in your preferred editor)</comment> +# <i>nano -w /etc/hal/fdi/policy/10-x11-input.fdi</i> +<comment>(Find the "input.keys" section)</comment> +<match key="info.capabilities" contains="input.keys"> +<comment>(Add the "terminate" merge string as shown)</comment> +<match key="info.capabilities" contains="input.keys"> + <merge key="input.x11_driver" type="string">keyboard</merge> + <i><merge key="input.xkb.options" type="string">terminate:ctrl_alt_bksp</merge>></i> + <match key="/org/freedesktop/Hal/devices/computer:system.kernel.name" + string="Linux"> + <merge key="input.x11_driver" type="string">evdev<merge> + </match> + </match> +</pre> + +<p> +There, now you have a handy way of killing an unresponsive X server. This is +useful when programs have frozen your display entirely, or when configuring and +tweaking your Xorg environment. Be careful when killing your desktop with this +key combination -- most programs really don't like it when you end them this +way, and you may lose some (or all) of what you were working on. +</p> + +<p> +Hopefully just working with the HAL policy files results in a working X desktop. +If Xorg still won't start, or there's some other problem, then you'll need to +manually configure <path>xorg.conf</path> as shown in the next section. +</p> + +</body> +</section> +<section> +<title>The xorg.conf file</title> <body> +<note> +Configuring <path>xorg.conf</path> should be seen as a "last resort" option. It +really desirable to run without one if possible, and to do all your +configuration via HAL policy files. If you still can't get a working +configuration, then read on. +</note> + <p> The configuration file of Xorg is called <path>xorg.conf</path> and it resides in <path>/etc/X11</path>. Xorg provides an example configuration as @@ -208,18 +345,13 @@ </p> <pre caption="Reading the xorg.conf man page"> -# <i>man 5 xorg.conf</i> +$ <i>man 5 xorg.conf</i> </pre> -<p> -Happy reading for those of you willing to. We surely don't so we'll continue -with checking out how we can create the file automatically. -</p> - </body> </section> <section> -<title>Default: Automatic Generation of xorg.conf</title> +<title>Automatic Generation of xorg.conf</title> <body> <p> @@ -248,41 +380,11 @@ <p> If all goes well, you should see a simple black and white pattern. Verify if -your mouse works correctly and if the resolution is good. If you received errors -about "/dev/mouse", try changing your mouse device to <c>/dev/input/mice</c> in -the "InputDevice" section of <path>xorg.conf</path>. You might not be able to -deduce the exact resolution, but you should be able to see if it's too low. You -can exit any time by pressing Ctrl-Alt-Backspace. -</p> - -</body> -</section> -<section> -<title>Alternative: Semi-Automatic Generation of xorg.conf</title> -<body> - -<p> -Xorg provides a tool called <c>xorgconfig</c> which will ask you for various -information regarding your system (graphical adapter, keyboard, ...). Based on -your input it will create a <path>xorg.conf</path> file. -</p> - -<pre caption="Semi-Automatic Generation of xorg.conf"> -# <i>xorgconfig</i> -</pre> - -<p> -Another tool, also provided by Xorg, is <c>xorgcfg</c>, which will first -attempt to run <c>Xorg -configure</c> and then start the X server for more -final tweaking. +your mouse works correctly and if the resolution is good. You might not be able +to deduce the exact resolution, but you should be able to see if it's too low. +You can exit any time by pressing Ctrl-Alt-Backspace. </p> -<pre caption="Using xorgcfg"> -# <i>xorgcfg</i> -<comment>(In case X crashes or the configuration fails, try:)</comment> -# <i>xorgcfg -textmode</i> -</pre> - </body> </section> <section> @@ -292,7 +394,7 @@ <p> Let us copy over the <path>xorg.conf.new</path> to <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run -<c>X -config</c> -- typing just <c>X</c> or <c>startx</c> is easier. :) +<c>X -config</c> -- typing just <c>startx</c> is easier. :) </p> <pre caption="Copying over xorg.conf"> @@ -306,9 +408,9 @@ <body> <p> -Now try <c>startx</c> to start up your X server. <c>startx</c> is a script +Now try <c>startx</c> to start up your X server. <c>startx</c> is a script that executes an <e>X session</e>, that is, it starts the X servers and some -graphical applications on top of it. It decides which applications to run +graphical applications on top of it. It decides which applications to run using the following logic: </p> @@ -341,25 +443,26 @@ <c>twm</c>. To finish the twm session, type in <c>exit</c> or Ctrl-D in the upcoming xterms. You can also kill the X session using the Ctrl-Alt-Backspace combination. This will however make X exit disgracefully -- something that you -might not always want. It doesn't hurt though. :) +might not always want. </p> </body> </section> </chapter> + <chapter> -<title>Tweaking xorg.conf</title> +<title>Tweaking X settings</title> <section> <title>Setting your Resolution</title> <body> <p> If you feel that the screen resolution is wrong, you will need to check two -sections in your configuration. First of all, you have the <e>Screen</e> section -which lists the resolutions, if any that your X server will run at. By -default, this section might not list any resolutions at all. If this is the -case, Xorg will estimate the resolutions based on the information in the -second section, <e>Monitor</e>. +sections in your <path>xorg.conf</path> configuration. First of all, you have +the <e>Screen</e> section which lists the resolutions, if any that your X server +will run at. By default, this section might not list any resolutions at all. If +this is the case, Xorg will estimate the resolutions based on the information in +the second section, <e>Monitor</e>. </p> <p> @@ -367,9 +470,7 @@ <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions. For now, leave these settings as-is. Only when the changes to the <e>Screen</e> section (which we will describe in a minute) don't work, then you will need to -look up the specs for your monitor and fill in the correct values. You can also -use a tool that searches for your monitor's specs, such as -<c>sys-apps/ddcxinfo-knoppix</c>. +look up the specs for your monitor and fill in the correct values. </p> <warn> @@ -382,7 +483,7 @@ <p> Now let us change the resolutions. In the next example from <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the -<c>DefaultDepth</c> so that our X server starts with 24 bits at 1024x768 by +<c>DefaultDepth</c> so that our X server starts with 24 bits at 1440x900 by default. Don't mind the given strings -- they are examples and will most likely differ from the settings on your system. </p> @@ -390,13 +491,13 @@ <pre caption="Changing the Screen section in /etc/X11/xorg.conf"> Section "Screen" Identifier "Default Screen" - Device "S3 Inc. ProSavage KN133 [Twister K]" + Device "RadeonHD 4550" Monitor "Generic Monitor" <i>DefaultDepth 24</i> <comment># Skipping some text to improve readability</comment> SubSection "Display" Depth 24 - <i>Modes "1024x768"</i> + <i>Modes "1440x900"</i> EndSubSection EndSection </pre> @@ -408,82 +509,47 @@ </body> </section> <section> -<title>Configuring your Keyboard</title> -<body> - -<p> -To setup X to use an international keyboard, search for the <e>InputDevice</e> -section that configures the keyboard and add the <c>XkbLayout</c> option to -point to the keyboard layout you want. As an example, we show you how to apply -for the Belgian layout. Just substitute the country-keycode with yours: -</p> - -<pre caption="Changing the keyboard layout"> -Section "InputDevice" - Identifier "Generic Keyboard" - Driver "keyboard" - Option "CoreKeyboard" - Option "XkbRules" "xorg" - Option "XkbModel" "pc105" - <i>Option "XkbLayout" "be"</i> -EndSection -</pre> - -</body> -</section> -<section> -<title>Configuring your Mouse</title> +<title>Configuring your keyboard</title> <body> <p> -If your mouse isn't working, you will first need to find out if it is detected -by the kernel at all. Mice are (device-wise) seen as -<path>/dev/input/mouse0</path> (or <path>/dev/input/mice</path> if you want to -use several mice). In some cases <path>/dev/psaux</path> is used. In either -case you can check if the devices do represent -your mouse by checking the output of those files when you move your mouse. You -will usually see some junk on your screen. To end the session press -<c>Ctrl-C</c>. +To setup X to use an international keyboard, you can copy the content of +<path>/usr/share/doc/hal-*/*/use-estonian-layout.fdi.bz2</path> to +<path>/etc/hal/fdi/policy/10-xinput-configuration.fdi</path>: </p> -<pre caption="Checking the device files"> -# <i>cat /dev/input/mouse0</i> -<comment>(Don't forget to press Ctrl-C to end this)</comment> +<pre caption="Using an existing config file"> +# <i>bzcat /usr/share/doc/hal-*/*/use-estonian-layout.fdi > /etc/hal/fdi/policy/10-xinput-configuration.fdi</i> </pre> <p> -If your mouse isn't detected, verify if all the necessary modules are loaded. +Now you can just edit <path>10-xinput-configuration.fdi</path> and change the +Estonian keyboard layout (<c>ee</c>) to your own, such as Great Britain +(<b>gb</b>) or Polish (<b>pl</b>). </p> <p> -If your mouse is detected, fill in the device in the appropriate -<e>InputDevice</e> section. In the next example you'll see we also set two other -options: <c>Protocol</c> (which lists the mouse protocol to be used -- most -users will use PS/2 or IMPS/2) and <c>ZAxisMapping</c> (which allows for the -mousewheel (if applicable) to be used). +When you're finished, run <c>/etc/init.d/hald restart</c> as root to make sure +that HAL picks up your configuration file changes. </p> -<pre caption="Changing the mouse settings in Xorg"> -Section "InputDevice" - Identifier "TouchPad Mouse" - Driver "mouse" - Option "CorePointer" - <i>Option "Device" "/dev/input/mouse0"</i> - <i>Option "Protocol" "IMPS/2"</i> - <i>Option "ZAxisMapping" "4 5"</i> -EndSection -</pre> +</body> +</section> +<section> +<title>Finishing up</title> +<body> <p> -Run <c>startx</c> and be happy about the result. :) Congratulations, you now +Run <c>startx</c> and be happy about the result. Congratulations, you now (hopefully) have a working Xorg on your system. The next step is to remove this -ugly lightweight window manager and use a high-feature one (or even a desktop -environment) such as KDE or GNOME, but that's not part of this guide. :) +ugly lightweight window manager (twm) and use a high-feature one (or even a +desktop environment) such as KDE or GNOME, but that's not part of this guide. </p> </body> </section> </chapter> + <chapter> <title>Resources</title> <section> @@ -491,9 +557,10 @@ <body> <p> -First of all, <c>man xorg.conf</c> provides a quick yet complete reference -about the syntax used by the configuration file. Be sure to have it open on a -terminal near you when you edit your configuration file! +First of all, <c>man xorg.conf</c> and <c>man evdev</c> provide quick yet +complete references about the syntax used by these configuration files. Be sure +to have them open on a terminal near you when you edit your configuration +files! </p> <p> @@ -510,24 +577,9 @@ <p> There are also many online resources on editing <path>xorg.conf</path>. We only list few of them here, be sure to <uri link="http://www.google.com";>Google</uri> -for more. :) As <path>xorg.conf</path> and <path>XF86Config</path> (the -configuration file for the XFree86 project) use the -same syntax for most configuration options and more information about -<path>XF86Config</path> is available, we'll list those resources as well. +for more. </p> -<ul> - <li> - <uri link="http://tldp.org/HOWTO/XFree-Local-multi-user-HOWTO/";>The XFree - Local Multi-User HOWTO</uri> - </li> - <li> - <uri - link="http://www-106.ibm.com/developerworks/edu/os-dw-linuxxwin-i.html";>An - Introduction to XFree 4.x</uri> by Chris Houser - </li> -</ul> - </body> </section> <section> @@ -542,9 +594,9 @@ </p> <p> -If you're upgrading to xorg-server-1.5 from an earlier version, then be sure to +If you're upgrading to xorg-server-1.6 from an earlier version, then be sure to read the <uri -link="/proj/en/desktop/x/x11/xorg-server-1.5-upgrade-guide.xml">migration +link="/proj/en/desktop/x/x11/xorg-server-1.6-upgrade-guide.xml">migration guide</uri>. </p>
