Contents of /xml/htdocs/doc/en/xorg-config.xml

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.34 - (show annotations) (download) (as text)
Thu Dec 17 04:41:24 2009 UTC (8 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.33: +8 -11 lines
File MIME type: application/xml
more fixes from bug 297245

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.33 2009/12/17 04:37:10 nightmorph Exp $ -->
5 <guide>
6 <title>The X Server Configuration HOWTO</title>
8 <author title="Author">
9 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
10 </author>
11 <author title="Author">
12 <mail link="nightmorph"/>
13 </author>
15 <abstract>
16 Xorg is the X Window server which allows users to have a graphical
17 environment at their fingertips. This HOWTO explains what Xorg is, how to
18 install it and what the various configuration options are.
19 </abstract>
21 <!-- The content of this document is licensed under the CC-BY-SA license -->
22 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23 <license/>
25 <version>1.24</version>
26 <date>2009-12-16</date>
28 <chapter>
29 <title>What is the X Window Server?</title>
30 <section>
31 <title>Graphical vs Command-Line</title>
32 <body>
34 <p>
35 The average user may be frightened at the thought of having to type in commands.
36 Why wouldn't he be able to point and click his way through the freedom provided
37 by Gentoo (and Linux in general)? Well, *big smile*, of course you are able to
38 do this. :-) Linux offers a wide variety of flashy user interfaces and
39 environments which you can install on top of your existing installation.
40 </p>
42 <p>
43 This is one of the biggest surprises new users come across: a graphical user
44 interface is nothing more than an application which runs on your system. It is
45 <e>not</e> part of the Linux kernel or any other internals of the system. It is
46 a powerful tool that fully enables the graphical abilities of your workstation.
47 </p>
49 <p>
50 As standards are important, a standard for drawing and moving windows on a
51 screen, interacting with the user through mouse, keyboard and other basic, yet
52 important aspects has been created and named the <e>X Window System</e>,
53 commonly abbreviated as <e>X11</e> or just <e>X</e>. It is used on Unix, Linux
54 and Unix-like operating systems throughout the world.
55 </p>
57 <p>
58 The application that provides Linux users with the ability to run graphical
59 user interfaces and that uses the X11 standard is Xorg-X11, a fork of
60 the XFree86 project. XFree86 has decided to use a license that might not be
61 compatible with the GPL license; the use of Xorg is therefore recommended.
62 The official Portage tree does not provide an XFree86 package anymore.
63 </p>
65 </body>
66 </section>
67 <section>
68 <title>The X.org Project</title>
69 <body>
71 <p>
72 The <uri link="http://www.x.org">X.org</uri> project created and
73 maintains a freely redistributable, open-source implementation of the X11
74 system. It is an open source X11-based desktop infrastructure.
75 </p>
77 <p>
78 Xorg provides an interface between your hardware and the graphical software
79 you want to run. Besides that, Xorg is also fully network-aware, meaning you
80 are able to run an application on one system while viewing it on a different
81 one.
82 </p>
84 </body>
85 </section>
86 </chapter>
88 <chapter>
89 <title>Installing Xorg</title>
90 <section>
91 <title>Kernel configuration</title>
92 <body>
94 <p>
95 By default, Xorg uses <c>evdev</c>, a generic input driver. You'll need to
96 activate support for <c>evdev</c> by making a change to your kernel
97 configuration. (Read the
98 <uri link="/doc/en/kernel-config.xml">Kernel Configuration Guide</uri> if you
99 don't know how to setup your kernel.)
100 </p>
102 <pre caption="Enabling evdev in the kernel">
103 Device Drivers ---&gt;
104 Input device support ---&gt;
105 &lt;*&gt; Event interface
106 </pre>
108 </body>
109 </section>
110 <section>
111 <title>make.conf configuration</title>
112 <body>
114 <p>
115 Before you install Xorg, you have to configure two important variables in the
116 <path>/etc/make.conf</path> file.
117 </p>
119 <p>
120 The first variable is <c>VIDEO_CARDS</c>. This is used to set the video drivers
121 that you intend to use and is usually based on the kind and brand of card you
122 have. The most common settings are <c>nvidia</c> for Nvidia cards or
123 <c>fglrx</c> for ATI Radeon cards. Those are the proprietary drivers from Nvidia
124 and ATI respectively. If you would like to use the open source nVidia driver,
125 use <c>nv</c> rather than <c>nvidia</c> in the variable, but bear in mind that
126 using this driver means no 3D acceleration at all. The free <c>radeon</c> and
127 <c>radeonhd</c> drivers are available for ATI cards, and are more or less the
128 equal of the proprietary <c>fglrx</c> driver. The <c>intel</c> driver may be
129 used for desktops or laptops with common Intel integrated graphics chipsets.
130 <c>VIDEO_CARDS</c> may contain more than one driver, in this case list of them
131 should be separated with spaces.
132 </p>
134 <p>
135 The second variable is <c>INPUT_DEVICES</c> and is used to determine which
136 drivers are to be built for input devices. In most cases setting it to
137 <c>evdev</c> should work just fine. If you use alternative input
138 devices, such as a Synaptics touchpad for a laptop, be sure to add it to
139 <c>INPUT_DEVICES</c>.
140 </p>
142 <p>
143 Now you should decide which drivers you will use and add necessary settings to
144 the <path>/etc/make.conf</path> file:
145 </p>
147 <pre caption="Sample make.conf entries">
148 <comment>(For mouse, keyboard, and Synaptics touchpad support)</comment>
149 INPUT_DEVICES="evdev synaptics"
150 <comment>(For Nvidia cards)</comment>
151 VIDEO_CARDS="nvidia"
152 <comment>(OR, for ATI Radeon cards)</comment>
153 VIDEO_CARDS="radeon"
154 </pre>
156 <note>
157 More instructions on how to configure nVidia and ATI cards can be found in the
158 <uri link="/doc/en/nvidia-guide.xml">Gentoo Linux nVidia Guide</uri> and in the
159 <uri link="/doc/en/ati-faq.xml">Gentoo Linux ATI FAQ</uri>. If you don't know
160 which drivers you should choose, refer to these guides for more information.
161 </note>
163 <p>
164 If the suggested settings don't work for you, you should run <c>emerge -pv
165 xorg-server</c>, check all the options available and choose those which apply to
166 your system. This example is for a system with a keyboard, mouse, Synaptics
167 touchpad, and a Radeon video card.
168 </p>
170 <pre caption="Displaying all the driver options available">
171 # <i>emerge -pv xorg-server</i>
173 These are the packages that would be merged, in order:
175 Calculating dependencies... done!
176 [ebuild R ] x11-base/xorg-server- USE="hal nptl xorg -debug
177 -dmx -ipv6 -kdrive -minimal -sdl -tslib" 0 kB
178 [ebuild R ] x11-base/xorg-drivers-1.6 INPUT_DEVICES="evdev synaptics
179 -acecad -aiptek -citron -elographics -fpit -hyperpen -joystick -keyboard -mouse
180 -mutouch -penmount -tslib -virtualbox -vmmouse -void -wacom"
181 VIDEO_CARDS="radeon -apm -ark -ast -chips -cirrus -dummy -epson -fbdev -fglrx
182 (-geode) -glint -i128 (-i740) (-impact) (-imstt) -intel -mach64 -mga -neomagic
183 (-newport) -nv -nvidia -r128 -radeonhd -rendition -s3 -s3virge -savage
184 -siliconmotion -sis -sisusb (-sunbw2) (-suncg14) (-suncg3) (-suncg6) (-sunffb)
185 (-sunleo) (-suntcx) -tdfx -tga -trident -tseng -v4l (-vermilion) -vesa -via
186 -virtualbox -vmware (-voodoo) (-xgi)" 0 kB
187 </pre>
189 <p>
190 After setting all the necessary variables you can install the Xorg package.
191 </p>
193 <pre caption="Installing Xorg">
194 # <i>emerge xorg-server</i>
195 </pre>
197 <note>
198 You could install the <c>xorg-x11</c> metapackage instead of the more
199 lightweight <c>xorg-server</c>. Functionally, <c>xorg-x11</c> and
200 <c>xorg-server</c> are the same. However, <c>xorg-x11</c> brings in many more
201 packages that you probably don't need, such as a huge assortment of fonts in
202 many different languages. They're not necessary for a working desktop.
203 </note>
205 <p>
206 When the installation is finished, you will need to re-initialise some
207 environment variables before you continue. Just run <c>env-update</c> followed
208 by <c>source /etc/profile</c> and you're all set.
209 </p>
211 <pre caption="Re-initialising the environment variables">
212 # <i>env-update</i>
213 # <i>source /etc/profile</i>
214 </pre>
216 </body>
217 </section>
218 </chapter>
220 <chapter>
221 <title>Configuring Xorg</title>
222 <section>
223 <title>Using HAL</title>
224 <body>
226 <p>
227 Recent X server versions are designed to work out-of-the-box, with no need to
228 manually configure Xorg's configuration files.
229 </p>
231 <p>
232 You should first try <uri link="#using_startx">starting X</uri> without creating
233 <path>/etc/X11/xorg.conf</path>.
234 </p>
236 <p>
237 If Xorg won't start (if there's something wrong with the screen, or with your
238 keyboard/mouse), then you can try fixing problems by using the right
239 configuration files.
240 </p>
242 <p>
243 By default, Xorg uses HAL (Hardware Abstraction Layer) to detect and configure
244 devices such as keyboards and mice.
245 </p>
247 <p>
248 HAL comes with many premade device rules, also called policies. These policy
249 files are available in <path>/usr/share/hal/fdi/policy/</path>. Just find a few
250 that suit your needs most closely and copy them to
251 <path>/etc/hal/fdi/policy/</path>.
252 </p>
254 <impo>
255 Do not edit the files in <path>/usr/share/hal/fdi/</path>! Just copy the ones
256 you need, and edit them once they're placed in the proper <path>/etc</path>
257 location.
258 </impo>
260 <p>
261 For example, to get a basic working keyboard/mouse combination, you could copy
262 the following files to <path>/etc/hal/fdi/policy/</path>:
263 </p>
265 <pre caption="Using HAL policy files">
266 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-input-policy.fdi /etc/hal/fdi/policy</i>
267 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-x11-input.fdi /etc/hal/fdi/policy</i>
268 </pre>
270 <p>
271 There are several other HAL policies in <path>/usr/share/hal/fdi/</path> that
272 may interest you, such as laptop configurations, storage device handling, power
273 management, and more. Just copy any of the policies to
274 <path>/etc/hal/fdi/policy/</path>.
275 </p>
277 <p>
278 You can edit the policy files in <path>/etc/hal/fdi/policy</path> to your
279 liking. You may want to make a few tweaks or to expose additional
280 functionality. Let's go through an example of tweaking a HAL policy.
281 </p>
283 <p>
284 One very convenient trick is to kill the X server entirely by pressing
285 Ctrl-Alt-Backspace. This is useful when your X server is malfunctioning, frozen,
286 etc. It's not as extreme as rebooting the whole machine with Ctrl-Alt-Del.
287 </p>
289 <p>
290 Recent X server versions disabled this key combination by default. However, you
291 can reenable it by copying <path>10-x11-input.fdi</path> to
292 <path>/etc/hal/fdi/policy</path> and editing it. You'll need to add just one
293 line to the appropriate section, as shown below:
294 </p>
296 <pre caption="Editing 10-x11-input.fdi">
297 <comment>(Open the file in your preferred editor)</comment>
298 # <i>nano -w /etc/hal/fdi/policy/10-x11-input.fdi</i>
299 <comment>(Find the "input.keys" section)</comment>
300 &lt;match key="info.capabilities" contains="input.keys"&gt;
301 <comment>(Add the "terminate" merge string as shown)</comment>
302 &lt;match key="info.capabilities" contains="input.keys"&gt;
303 &lt;merge key="input.x11_driver" type="string"&gt;keyboard&lt;/merge&gt;
304 <i>&lt;merge key="input.xkb.options" type="string"&gt;terminate:ctrl_alt_bksp&lt;/merge&gt;</i>
305 &lt;match key="/org/freedesktop/Hal/devices/computer:system.kernel.name"
306 string="Linux"&gt;
307 &lt;merge key="input.x11_driver" type="string"&gt;evdev&lt;merge&gt;
308 &lt;/match&gt;
309 &lt;/match&gt;
310 </pre>
312 <p>
313 There, now you have a handy way of killing an unresponsive X server. This is
314 useful when programs have frozen your display entirely, or when configuring and
315 tweaking your Xorg environment. Be careful when killing your desktop with this
316 key combination -- most programs really don't like it when you end them this
317 way, and you may lose some (or all) of what you were working on.
318 </p>
320 <p>
321 Hopefully just working with the HAL policy files results in a working X desktop.
322 If Xorg still won't start, or there's some other problem, then you'll need to
323 manually configure <path>xorg.conf</path> as shown in the next section.
324 </p>
326 </body>
327 </section>
328 <section>
329 <title>The xorg.conf file</title>
330 <body>
332 <note>
333 Configuring <path>xorg.conf</path> should be seen as a "last resort" option. It
334 really desirable to run without one if possible, and to do all your
335 configuration via HAL policy files. If you still can't get a working
336 configuration, then read on.
337 </note>
339 <p>
340 The configuration file of Xorg is called <path>xorg.conf</path> and it resides
341 in <path>/etc/X11</path>. Xorg provides an example configuration as
342 <path>/etc/X11/xorg.conf.example</path> which you can use to create your own
343 configuration. It is heavily commented, but if you are in need of more
344 documentation regarding the syntax, don't hesitate to read the man page:
345 </p>
347 <pre caption="Reading the xorg.conf man page">
348 $ <i>man 5 xorg.conf</i>
349 </pre>
351 </body>
352 </section>
353 <section>
354 <title>Automatic Generation of xorg.conf</title>
355 <body>
357 <p>
358 Xorg itself is able to guess most parameters for you. In most cases, you
359 will only have to change some lines to get the resolution you want up and
360 running. If you are interested in more in-depth tweaking, be sure to check the
361 resources at the end of this chapter. But first, let us generate a (hopefully
362 working) Xorg configuration file.
363 </p>
365 <pre caption="Generating an xorg.conf file">
366 # <i>Xorg -configure</i>
367 </pre>
369 <p>
370 Be sure to read the last lines printed on your screen when Xorg has finished
371 probing your hardware. If it tells you it failed at some point, you're forced to
372 manually write an <path>xorg.conf</path> file. Assuming that it didn't fail, it
373 will have told you that it has written <path>/root/xorg.conf.new</path> ready
374 for you to test. So let's test. :)
375 </p>
377 <pre caption="Testing the xorg.conf.new file">
378 # <i>X -config /root/xorg.conf.new</i>
379 </pre>
381 <p>
382 If all goes well, you should see a simple black and white pattern. Verify if
383 your mouse works correctly and if the resolution is good. You might not be able
384 to deduce the exact resolution, but you should be able to see if it's too low.
385 You can exit any time by pressing Ctrl-Alt-Backspace.
386 </p>
388 </body>
389 </section>
390 <section>
391 <title>Copying over xorg.conf</title>
392 <body>
394 <p>
395 Let us copy over the <path>xorg.conf.new</path> to
396 <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run
397 <c>X -config</c> -- typing just <c>startx</c> is easier. :)
398 </p>
400 <pre caption="Copying over xorg.conf">
401 # <i>cp /root/xorg.conf.new /etc/X11/xorg.conf</i>
402 </pre>
404 </body>
405 </section>
406 <section id="using_startx">
407 <title>Using startx</title>
408 <body>
410 <p>
411 Now try <c>startx</c> to start up your X server. <c>startx</c> is a script
412 that executes an <e>X session</e>, that is, it starts the X servers and some
413 graphical applications on top of it. It decides which applications to run
414 using the following logic:
415 </p>
417 <ul>
418 <li>
419 If a file named <path>.xinitrc</path> exists in the home directory, it will
420 execute the commands listed there.
421 </li>
422 <li>
423 Otherwise, it will read the value of the XSESSION variable and will execute
424 one of the sessions available in <path>/etc/X11/Sessions/</path>
425 accordingly. You can set the value of XSESSION in
426 <path>/etc/env.d/90xsession</path> to make it a default for all the users on
427 the system. For example, as root, run <c>echo XSESSION="Xfce4" >
428 /etc/env.d/90xsession</c>. This will create the <path>90xsession</path> file
429 and set the default X session to Xfce4.
430 </li>
431 <li>
432 If all of the above fail, it will fall back to a simple window manager,
433 usually <c>twm</c>.
434 </li>
435 </ul>
437 <pre caption="Starting X">
438 # <i>startx</i>
439 </pre>
441 <p>
442 You can kill the X session using the Ctrl-Alt-Backspace combination. This will
443 however make X exit disgracefully -- something that you might not always want.
444 </p>
446 </body>
447 </section>
448 </chapter>
450 <chapter>
451 <title>Tweaking X settings</title>
452 <section>
453 <title>Setting your Resolution</title>
454 <body>
456 <p>
457 If you feel that the screen resolution is wrong, you will need to check two
458 sections in your <path>xorg.conf</path> configuration. First of all, you have
459 the <e>Screen</e> section which lists the resolutions, if any that your X server
460 will run at. By default, this section might not list any resolutions at all. If
461 this is the case, Xorg will estimate the resolutions based on the information in
462 the second section, <e>Monitor</e>.
463 </p>
465 <p>
466 What happens is that Xorg checks the settings of <c>HorizSync</c> and
467 <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions.
468 For now, leave these settings as-is. Only when the changes to the <e>Screen</e>
469 section (which we will describe in a minute) don't work, then you will need to
470 look up the specs for your monitor and fill in the correct values.
471 </p>
473 <warn>
474 Do <b>not</b> "just" change the values of these two monitor related variables
475 without consulting the technical specifications of your monitor. Setting
476 incorrect values lead to out-of-sync errors at best and smoked up screens at
477 worst.
478 </warn>
480 <p>
481 Now let us change the resolutions. In the next example from
482 <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the
483 <c>DefaultDepth</c> so that our X server starts with 24 bits at 1440x900 by
484 default. Don't mind the given strings -- they are examples and will most likely
485 differ from the settings on your system.
486 </p>
488 <pre caption="Changing the Screen section in /etc/X11/xorg.conf">
489 Section "Screen"
490 Identifier "Default Screen"
491 Device "RadeonHD 4550"
492 Monitor "Generic Monitor"
493 <i>DefaultDepth 24</i>
494 <comment># Skipping some text to improve readability</comment>
495 SubSection "Display"
496 Depth 24
497 <i>Modes "1440x900"</i>
498 EndSubSection
499 EndSection
500 </pre>
502 <p>
503 Run X (<c>startx</c>) to discover it uses the resolution you want. :)
504 </p>
506 </body>
507 </section>
508 <section>
509 <title>Configuring your keyboard</title>
510 <body>
512 <p>
513 To setup X to use an international keyboard, you can copy the content of
514 <path>/usr/share/doc/hal-*/*/use-estonian-layout.fdi.bz2</path> to
515 <path>/etc/hal/fdi/policy/10-xinput-configuration.fdi</path>:
516 </p>
518 <pre caption="Using an existing config file">
519 # <i>bzcat /usr/share/doc/hal-*/*/use-estonian-layout.fdi > /etc/hal/fdi/policy/10-xinput-configuration.fdi</i>
520 </pre>
522 <p>
523 Now you can just edit <path>10-xinput-configuration.fdi</path> and change the
524 Estonian keyboard layout (<c>ee</c>) to your own, such as Great Britain
525 (<b>gb</b>) or Polish (<b>pl</b>).
526 </p>
528 <p>
529 When you're finished, run <c>/etc/init.d/hald restart</c> as root to make sure
530 that HAL picks up your configuration file changes.
531 </p>
533 </body>
534 </section>
535 <section>
536 <title>Finishing up</title>
537 <body>
539 <p>
540 Run <c>startx</c> and be happy about the result. Congratulations, you now
541 (hopefully) have a working Xorg on your system. The next step is to install a
542 useful window manager (or even a desktop environment) such as KDE or GNOME, but
543 that's not part of this guide.
544 </p>
546 </body>
547 </section>
548 </chapter>
550 <chapter>
551 <title>Resources</title>
552 <section>
553 <title>Creating and Tweaking xorg.conf</title>
554 <body>
556 <p>
557 First of all, <c>man xorg.conf</c> and <c>man evdev</c> provide quick yet
558 complete references about the syntax used by these configuration files. Be sure
559 to have them open on a terminal near you when you edit your configuration
560 files!
561 </p>
563 <p>
564 Also, be sure to look at <path>/etc/X11/xorg.conf.example</path>; you may wish
565 to copy this and use it as a foundation for writing your own
566 <path>xorg.conf</path>.
567 </p>
569 <p>
570 You may find the X.org <uri link="http://www.x.org/wiki/FAQ">FAQ</uri> provided
571 on their website, in addition to their other documentation.
572 </p>
574 <p>
575 There are also many online resources on editing <path>xorg.conf</path>. We only
576 list few of them here, be sure to <uri link="http://www.google.com">Google</uri>
577 for more.
578 </p>
580 </body>
581 </section>
582 <section>
583 <title>Other resources</title>
584 <body>
586 <p>
587 More information about installing and configuring various graphical desktop
588 environments and applications can be found in the <uri
589 link="/doc/en/?catid=desktop">Gentoo Desktop Documentation Resources</uri>
590 section of our documentation.
591 </p>
593 <p>
594 If you're upgrading to xorg-server-1.6 from an earlier version, then be sure to
595 read the <uri
596 link="/proj/en/desktop/x/x11/xorg-server-1.6-upgrade-guide.xml">migration
597 guide</uri>.
598 </p>
600 </body>
601 </section>
602 </chapter>
603 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20