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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.37 - (show annotations) (download) (as text)
Tue Mar 16 20:07:43 2010 UTC (9 years ago) by nightmorph
Branch: MAIN
Changes since 1.36: +23 -8 lines
File MIME type: application/xml
added the -retro option per bug 267769. also added a bit on installing twm and xterm only for testing purposes, since otherwise startx will just display a black screen. having a few open xterm windows makes it easier to verify that X is setup correctly.

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.36 2010/01/02 03:02:40 nightmorph Exp $ -->
5 <guide>
6 <title>The X Server Configuration HOWTO</title>
8 <author title="Author">
9 <mail link="swift"/>
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.27</version>
26 <date>2010-03-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 <p>
217 Now it's time to start the Hardware Abstraction Layer (HAL) daemon and set it to
218 automatically start each time you boot. This is necessary to get a working X
219 environment, otherwise your input devices won't be detected and you'll probably
220 just get a blank screen. We'll cover HAL more in the <uri
221 link="#using_hal">next section</uri>.
222 </p>
224 <pre caption="Starting HAL">
225 # <i>/etc/init.d/hald start</i>
226 # <i>rc-update add hald default</i>
227 </pre>
229 </body>
230 </section>
231 </chapter>
233 <chapter>
234 <title>Configuring Xorg</title>
235 <section id="using_hal">
236 <title>Using HAL</title>
237 <body>
239 <p>
240 Recent X server versions are designed to work out-of-the-box, with no need to
241 manually edit Xorg's configuration files.
242 </p>
244 <p>
245 You should first try <uri link="#using_startx">starting X</uri> without creating
246 <path>/etc/X11/xorg.conf</path>.
247 </p>
249 <p>
250 If Xorg won't start (if there's something wrong with the screen, or with your
251 keyboard/mouse), then you can try fixing problems by using the right
252 configuration files.
253 </p>
255 <p>
256 By default, Xorg uses HAL (Hardware Abstraction Layer) to detect and configure
257 devices such as keyboards and mice.
258 </p>
260 <p>
261 HAL comes with many premade device rules, also called policies. These policy
262 files are available in <path>/usr/share/hal/fdi/policy/</path>. Just find a few
263 that suit your needs most closely and copy them to
264 <path>/etc/hal/fdi/policy/</path>.
265 </p>
267 <impo>
268 Do not edit the files in <path>/usr/share/hal/fdi/</path>! Just copy the ones
269 you need, and edit them once they're placed in the proper <path>/etc</path>
270 location.
271 </impo>
273 <p>
274 For example, to get a basic working keyboard/mouse combination, you could copy
275 the following files to <path>/etc/hal/fdi/policy/</path>:
276 </p>
278 <pre caption="Using HAL policy files">
279 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-input-policy.fdi /etc/hal/fdi/policy</i>
280 # <i>cp /usr/share/hal/fdi/policy/10osvendor/10-x11-input.fdi /etc/hal/fdi/policy</i>
281 </pre>
283 <p>
284 There are several other HAL policies in <path>/usr/share/hal/fdi/</path> that
285 may interest you, such as laptop configurations, storage device handling, power
286 management, and more. Just copy any of the policies to
287 <path>/etc/hal/fdi/policy/</path>.
288 </p>
290 <impo>
291 Remember, <e>every</e> time you finish making changes to HAL policy files, you
292 need to restart the HAL daemon by running <c>/etc/init.d/hald restart</c>.
293 </impo>
295 <p>
296 You can edit the policy files in <path>/etc/hal/fdi/policy</path> to your
297 liking. You may want to make a few tweaks or to expose additional
298 functionality. Let's go through an example of tweaking a HAL policy.
299 </p>
301 <p>
302 One very convenient trick is to kill the X server entirely by pressing
303 Ctrl-Alt-Backspace. This is useful when your X server is malfunctioning, frozen,
304 etc. It's not as extreme as rebooting the whole machine with Ctrl-Alt-Del.
305 </p>
307 <p>
308 Recent X server versions disabled this key combination by default. However, you
309 can reenable it by copying <path>10-x11-input.fdi</path> to
310 <path>/etc/hal/fdi/policy</path> and editing it. You'll need to add just one
311 line to the appropriate section, as shown below:
312 </p>
314 <pre caption="Editing 10-x11-input.fdi">
315 <comment>(Open the file in your preferred editor)</comment>
316 # <i>nano -w /etc/hal/fdi/policy/10-x11-input.fdi</i>
317 <comment>(Find the "input.keys" section)</comment>
318 &lt;match key="info.capabilities" contains="input.keys"&gt;
319 <comment>(Add the "terminate" merge string as shown)</comment>
320 &lt;match key="info.capabilities" contains="input.keys"&gt;
321 &lt;merge key="input.x11_driver" type="string"&gt;keyboard&lt;/merge&gt;
322 <i>&lt;merge key="input.xkb.options" type="string"&gt;terminate:ctrl_alt_bksp&lt;/merge&gt;</i>
323 &lt;match key="/org/freedesktop/Hal/devices/computer:system.kernel.name"
324 string="Linux"&gt;
325 &lt;merge key="input.x11_driver" type="string"&gt;evdev&lt;merge&gt;
326 &lt;/match&gt;
327 &lt;/match&gt;
328 </pre>
330 <p>
331 Once you're done, run <c>/etc/init.d/hald restart</c> so that HAL picks up your
332 changes.
333 </p>
335 <p>
336 There, now you have a handy way of killing an unresponsive X server. This is
337 useful when programs have frozen your display entirely, or when configuring and
338 tweaking your Xorg environment. Be careful when killing your desktop with this
339 key combination -- most programs really don't like it when you end them this
340 way, and you may lose some (or all) of what you were working on.
341 </p>
343 <p>
344 Hopefully just working with the HAL policy files results in a working X desktop.
345 If Xorg still won't start, or there's some other problem, then you'll need to
346 manually configure <path>xorg.conf</path> as shown in the next section.
347 </p>
349 </body>
350 </section>
351 <section>
352 <title>The xorg.conf file</title>
353 <body>
355 <note>
356 Configuring <path>xorg.conf</path> should be seen as a "last resort" option. It
357 really desirable to run without one if possible, and to do all your
358 configuration via HAL policy files. If you still can't get a working
359 configuration, then read on.
360 </note>
362 <p>
363 The configuration file of Xorg is called <path>xorg.conf</path> and it resides
364 in <path>/etc/X11</path>. Xorg provides an example configuration as
365 <path>/etc/X11/xorg.conf.example</path> which you can use to create your own
366 configuration. It is heavily commented, but if you are in need of more
367 documentation regarding the syntax, don't hesitate to read the man page:
368 </p>
370 <pre caption="Reading the xorg.conf man page">
371 $ <i>man 5 xorg.conf</i>
372 </pre>
374 </body>
375 </section>
376 <section>
377 <title>Automatic Generation of xorg.conf</title>
378 <body>
380 <p>
381 Xorg itself is able to guess most parameters for you. In most cases, you
382 will only have to change some lines to get the resolution you want up and
383 running. If you are interested in more in-depth tweaking, be sure to check the
384 resources at the end of this chapter. But first, let us generate a (hopefully
385 working) Xorg configuration file.
386 </p>
388 <pre caption="Generating an xorg.conf file">
389 # <i>Xorg -configure</i>
390 </pre>
392 <p>
393 Be sure to read the last lines printed on your screen when Xorg has finished
394 probing your hardware. If it tells you it failed at some point, you're forced to
395 manually write an <path>xorg.conf</path> file. Assuming that it didn't fail, it
396 will have told you that it has written <path>/root/xorg.conf.new</path> ready
397 for you to test. So let's test. :)
398 </p>
400 <pre caption="Testing the xorg.conf.new file">
401 # <i>X -config -retro /root/xorg.conf.new</i>
402 </pre>
404 <p>
405 If all goes well, you should see a simple black and white pattern. Verify if
406 your mouse works correctly and if the resolution is good. You might not be able
407 to deduce the exact resolution, but you should be able to see if it's too low.
408 You can exit any time by pressing Ctrl-Alt-Backspace.
409 </p>
411 </body>
412 </section>
413 <section>
414 <title>Copying over xorg.conf</title>
415 <body>
417 <p>
418 Let us copy over the <path>xorg.conf.new</path> to
419 <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run
420 <c>X -config</c> -- typing just <c>startx</c> is easier. :)
421 </p>
423 <pre caption="Copying over xorg.conf">
424 # <i>cp /root/xorg.conf.new /etc/X11/xorg.conf</i>
425 </pre>
427 </body>
428 </section>
429 <section id="using_startx">
430 <title>Using startx</title>
431 <body>
433 <p>
434 Now try <c>startx</c> to start up your X server. <c>startx</c> is a script
435 that executes an <e>X session</e>, that is, it starts the X servers and some
436 graphical applications on top of it. It decides which applications to run
437 using the following logic:
438 </p>
440 <ul>
441 <li>
442 If a file named <path>.xinitrc</path> exists in the home directory, it will
443 execute the commands listed there.
444 </li>
445 <li>
446 Otherwise, it will read the value of the XSESSION variable and will execute
447 one of the sessions available in <path>/etc/X11/Sessions/</path>
448 accordingly. You can set the value of XSESSION in
449 <path>/etc/env.d/90xsession</path> to make it a default for all the users on
450 the system. For example, as root, run <c>echo XSESSION="Xfce4" >
451 /etc/env.d/90xsession</c>. This will create the <path>90xsession</path> file
452 and set the default X session to Xfce4.
453 </li>
454 </ul>
456 <pre caption="Starting X">
457 $ <i>startx</i>
458 </pre>
460 <p>
461 You can kill the X session by using the Ctrl-Alt-Backspace combination. This
462 will, however, make X exit disgracefully -- something that you might not always
463 want.
464 </p>
466 <p>
467 If you haven't yet installed a window manager, all you'll see is a black screen.
468 Since this can also be a sign that something's wrong, you may want to emerge
469 <c>twm</c> and <c>xterm</c> <e>only to test X</e>.
470 </p>
472 <p>
473 Once those two programs are installed, run <c>startx</c> again. A few xterm
474 windows should appear, making it easier to verify that X is working correctly.
475 Once you're satisfied with the results, run <c>emerge --unmerge twm xterm</c> as
476 root to get rid of the testing packages. You won't need them once you've setup a
477 proper desktop environment.
478 </p>
480 </body>
481 </section>
482 </chapter>
484 <chapter>
485 <title>Tweaking X settings</title>
486 <section>
487 <title>Setting your Resolution</title>
488 <body>
490 <p>
491 If you feel that the screen resolution is wrong, you will need to check two
492 sections in your <path>xorg.conf</path> configuration. First of all, you have
493 the <e>Screen</e> section which lists the resolutions, if any that your X server
494 will run at. By default, this section might not list any resolutions at all. If
495 this is the case, Xorg will estimate the resolutions based on the information in
496 the second section, <e>Monitor</e>.
497 </p>
499 <p>
500 What happens is that Xorg checks the settings of <c>HorizSync</c> and
501 <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions.
502 For now, leave these settings as-is. Only when the changes to the <e>Screen</e>
503 section (which we will describe in a minute) don't work, then you will need to
504 look up the specs for your monitor and fill in the correct values.
505 </p>
507 <warn>
508 Do <b>not</b> "just" change the values of these two monitor related variables
509 without consulting the technical specifications of your monitor. Setting
510 incorrect values lead to out-of-sync errors at best and smoked up screens at
511 worst.
512 </warn>
514 <p>
515 Now let us change the resolutions. In the next example from
516 <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the
517 <c>DefaultDepth</c> so that our X server starts with 24 bits at 1440x900 by
518 default. Don't mind the given strings -- they are examples and will most likely
519 differ from the settings on your system.
520 </p>
522 <pre caption="Changing the Screen section in /etc/X11/xorg.conf">
523 Section "Screen"
524 Identifier "Default Screen"
525 Device "RadeonHD 4550"
526 Monitor "Generic Monitor"
527 <i>DefaultDepth 24</i>
528 <comment># Skipping some text to improve readability</comment>
529 SubSection "Display"
530 Depth 24
531 <i>Modes "1440x900"</i>
532 EndSubSection
533 EndSection
534 </pre>
536 <p>
537 Run X (<c>startx</c>) to discover it uses the resolution you want.
538 </p>
540 </body>
541 </section>
542 <section>
543 <title>Configuring your keyboard</title>
544 <body>
546 <p>
547 To setup X to use an international keyboard, you can copy the content of
548 <path>/usr/share/doc/hal-*/*/use-estonian-layout.fdi.bz2</path> to
549 <path>/etc/hal/fdi/policy/10-xinput-configuration.fdi</path>:
550 </p>
552 <pre caption="Using an existing config file">
553 # <i>bzcat /usr/share/doc/hal-*/*/use-estonian-layout.fdi > /etc/hal/fdi/policy/10-xinput-configuration.fdi</i>
554 </pre>
556 <p>
557 Now you can just edit <path>10-xinput-configuration.fdi</path> and change the
558 Estonian keyboard layout (<c>ee</c>) to your own, such as Great Britain
559 (<b>gb</b>) or Polish (<b>pl</b>).
560 </p>
562 <p>
563 When you're finished, run <c>/etc/init.d/hald restart</c> as root to make sure
564 that HAL picks up your configuration file changes.
565 </p>
567 </body>
568 </section>
569 <section>
570 <title>Finishing up</title>
571 <body>
573 <p>
574 Run <c>startx</c> and be happy about the result. Congratulations, you now
575 (hopefully) have a working Xorg on your system. The next step is to install a
576 useful window manager (or even a desktop environment) such as KDE or GNOME, but
577 that's not part of this guide.
578 </p>
580 </body>
581 </section>
582 </chapter>
584 <chapter>
585 <title>Resources</title>
586 <section>
587 <title>Creating and Tweaking xorg.conf</title>
588 <body>
590 <p>
591 First of all, <c>man xorg.conf</c> and <c>man evdev</c> provide quick yet
592 complete references about the syntax used by these configuration files. Be sure
593 to have them open on a terminal near you when you edit your configuration
594 files!
595 </p>
597 <p>
598 Also, be sure to look at <path>/etc/X11/xorg.conf.example</path>; you may wish
599 to copy this and use it as a foundation for writing your own
600 <path>xorg.conf</path>.
601 </p>
603 <p>
604 You may find the X.org <uri link="http://www.x.org/wiki/FAQ">FAQ</uri> provided
605 on their website, in addition to their other documentation.
606 </p>
608 <p>
609 There are also many online resources on editing <path>xorg.conf</path>. We only
610 list few of them here, be sure to <uri link="http://www.google.com">Google</uri>
611 for more.
612 </p>
614 </body>
615 </section>
616 <section>
617 <title>Other resources</title>
618 <body>
620 <p>
621 More information about installing and configuring various graphical desktop
622 environments and applications can be found in the <uri
623 link="/doc/en/?catid=desktop">Gentoo Desktop Documentation Resources</uri>
624 section of our documentation.
625 </p>
627 <p>
628 If you're upgrading to xorg-server-1.6 from an earlier version, then be sure to
629 read the <uri
630 link="/proj/en/desktop/x/x11/xorg-server-1.6-upgrade-guide.xml">migration
631 guide</uri>.
632 </p>
634 </body>
635 </section>
636 </chapter>
637 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20