/[gentoo]/xml/htdocs/doc/en/xorg-config.xml
Gentoo

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.22 - (hide annotations) (download) (as text)
Sat Jun 9 12:40:12 2007 UTC (7 years, 2 months ago) by jkt
Branch: MAIN
Changes since 1.21: +6 -5 lines
File MIME type: application/xml
clarify status of the radeon driver

1 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2    
3 jkt 1.22 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.21 2007/02/17 19:12:14 nightmorph Exp $ -->
4 swift 1.1
5     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6    
7 yoswink 1.15 <guide link="/doc/en/xorg-config.xml">
8 swift 1.1
9     <title>The X Server Configuration HOWTO</title>
10    
11     <author title="Author">
12 nightmorph 1.20 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
13 swift 1.1 </author>
14    
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>
20    
21     <!-- The content of this document is licensed under the CC-BY-SA license -->
22 fox2mike 1.17 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23 swift 1.1 <license/>
24    
25 jkt 1.22 <version>1.16</version>
26     <date>2007-06-09</date>
27 swift 1.1
28     <chapter>
29     <title>What is the X Window Server?</title>
30     <section>
31     <title>Graphical vs Command-Line</title>
32     <body>
33    
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>
41    
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>
48    
49     <p>
50     As standards are important, a standard for drawing and moving windows on a
51 fox2mike 1.16 screen, interacting with the user through mouse, keyboard and other basic, yet
52 swift 1.1 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>
56    
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 swift 1.8 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 swift 1.1 </p>
64    
65     </body>
66     </section>
67     <section>
68     <title>The X.org Project</title>
69     <body>
70    
71     <p>
72     The <uri link="http://www.x.org">X.org</uri> project created and
73 fox2mike 1.16 maintains a freely redistributable, open-source implementation of the X11
74     system. It is an open source X11-based desktop infrastructure.
75 swift 1.1 </p>
76    
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>
83    
84     </body>
85     </section>
86     </chapter>
87 fox2mike 1.16
88 swift 1.1 <chapter>
89     <title>Installing Xorg</title>
90     <section>
91     <title>Using emerge</title>
92     <body>
93    
94     <p>
95     Enough chitchat, let's get to business shall we? To install Xorg, you just
96     need to run <c>emerge xorg-x11</c>. Installing Xorg does take a while
97     though, so you might want to grab a snack while you are waiting.
98     </p>
99    
100 rane 1.18 <p>
101     Before installing Xorg you have to configure two important variables in the
102     <path>/etc/make.conf</path> file.
103     </p>
104    
105     <p>
106     The first one is <c>VIDEO_CARDS</c>. This is used to set the video drivers that
107     you intend to use and is usually based on the kind and brand of card you have.
108     The most common settings are <c>nvidia</c> for Nvidia cards or <c>fglrx</c> for
109     ATI Radeon cards. Those are the proprietary drivers from Nvidia and ATI
110     respectively. If you would like to use the open source versions, use <c>nv</c>
111     rather than <c>nvidia</c> in the variable, but bear in mind that using this
112 jkt 1.22 driver means no 3d acceleration at all. The free <c>radeon</c> driver for ATI
113     cards supports full 3D acceleration on older Radeons but doesn't work at all
114     with the newer ones. <c>VIDEO_CARDS</c> may contain more than one driver, in
115 rane 1.18 this case list of them should be separated with spaces.
116     </p>
117    
118     <p>
119     The second variable is <c>INPUT_DEVICES</c> and is used to determine which
120     drivers are to be built for input devices. In most cases setting it to
121     <c>keyboard mouse</c> should work just fine.
122     </p>
123    
124     <p>
125     Now you should decide which drivers you will use and add necessary settings to
126     the <path>/etc/make.conf</path> file:
127     </p>
128    
129     <pre caption="Sample make.conf entries">
130     <comment>(For mouse and keyboard support)</comment>
131     INPUT_DEVICES="keyboard mouse"
132     <comment>(For Nvidia cards)</comment>
133     VIDEO_CARDS="nvidia"
134     <comment>(OR, for ATI Radeon cards)</comment>
135     VIDEO_CARDS="fglrx"
136     </pre>
137    
138     <p>
139     More instructions on how to configure Nvidia and ATI cards can be found in
140     <uri link="/doc/en/nvidia-guide.xml">Gentoo Linux nVidia Guide</uri> and in
141     <uri link="/doc/en/ati-faq.xml">Gentoo Linux ATI FAQ</uri>. If you don't know
142     which drivers you should choose, refer to these guides for more information.
143     </p>
144    
145     <note>
146     If the suggested settings don't work for you, you should run <c>emerge -pv
147     xorg-x11</c>, check all the options available and choose those which
148     apply to your system. In different versions of Xorg and on different
149     architectures displaying these variables can be done with <c>emerge -pv
150     xorg-server</c> command rather than the one above. The example is for x86
151     architecture and xorg-x11-7.0.
152     </note>
153    
154     <pre caption="Displaying all the driver options available">
155     # <i>emerge -pv xorg-x11</i>
156    
157     These are the packages that would be merged, in order:
158    
159     Calculating dependencies... done!
160     [ebuild R ] x11-base/xorg-x11-7.0-r1 USE="-3dfx" INPUT_DEVICES="keyboard
161     mouse -acecad -aiptek -calcomp -citron -digitaledge -dmc -dynapro -elo2300
162     -elographics -evdev -fpit -hyperpen -jamstudio -joystick -magellan -magictouch
163     -microtouch -mutouch -palmax -penmount -spaceorb -summa -synaptics -tek4957
164     -ur98 -vmmouse -void -wacom" VIDEO_CARDS="nvidia -apm -ark -chips -cirrus
165     -cyrix -dummy -fbdev -fglrx -glint -i128 -i740 -i810 -imstt -mach64 -mga
166     -neomagic -nsc -nv -r128 -radeon -rendition -s3 -s3virge -savage -siliconmotion
167     -sis -sisusb -tdfx -tga -trident -tseng -v4l -vesa -vga -via -vmware -voodoo" 0
168     kB
169     </pre>
170    
171     <p>
172     After setting all the necessary variables you can install the Xorg package.
173     </p>
174    
175 swift 1.1 <pre caption="Installing Xorg">
176     # <i>emerge xorg-x11</i>
177     </pre>
178    
179     <p>
180 rane 1.18 When the installation is finished, you might need to re-initialise some
181 swift 1.1 environment variables before you continue. Just run <c>env-update</c> followed
182 rane 1.18 by <c>source /etc/profile</c> and you're all set.
183 swift 1.1 </p>
184    
185 rane 1.18 <pre caption="Re-initialising the environment variables">
186 swift 1.1 # <i>env-update</i>
187     # <i>source /etc/profile</i>
188     </pre>
189    
190     </body>
191     </section>
192     </chapter>
193     <chapter>
194     <title>Configuring Xorg</title>
195     <section>
196     <title>The xorg.conf File</title>
197     <body>
198    
199     <p>
200 neysx 1.2 The configuration file of Xorg is called <path>xorg.conf</path> and it
201 swift 1.1 resides in <path>/etc/X11</path>. The Xorg-X11 package provides an example
202     configuration as <path>/etc/X11/xorg.conf.example</path> which you can use to
203     create your own configuration. It is heavily commented, but if you are in need
204     of more documentation regarding the syntax, don't hesitate to read the man page:
205     </p>
206    
207     <pre caption="Reading the xorg.conf man page">
208     # <i>man 5 xorg.conf</i>
209     </pre>
210    
211     <p>
212     Happy reading for those of you willing to. We surely don't so we'll continue
213     with checking out how we can create the file automatically.
214     </p>
215    
216     </body>
217     </section>
218     <section>
219     <title>Default: Automatic Generation of xorg.conf</title>
220     <body>
221    
222     <p>
223     Xorg itself is able to guess most parameters for you. In most cases, you
224     will only have to change some lines to get the resolution you want up and
225     running. If you are interested in more in-depth tweaking, be sure to check the
226     resources at the end of this chapter. But first, let us generate a (hopefully
227     working) Xorg configuration file.
228     </p>
229    
230     <pre caption="Generating an xorg.conf file">
231     # <i>Xorg -configure</i>
232     </pre>
233    
234     <p>
235     Be sure to read the last lines printed on your screen when Xorg has finished
236     probing your hardware. If it tells you it failed at some point, you're forced to
237     manually write an <path>xorg.conf</path> file. Assuming that it didn't fail, it
238     will have told you that it has written <path>/root/xorg.conf.new</path> ready
239     for you to test. So let's test :)
240     </p>
241    
242     <pre caption="Testing the xorg.conf.new file">
243 swift 1.6 # <i>X -config /root/xorg.conf.new</i>
244 swift 1.1 </pre>
245    
246     <p>
247 nightmorph 1.21 If all goes well, you should see a simple black and white pattern. Verify if
248     your mouse works correctly and if the resolution is good. If you received errors
249     about "/dev/mouse", try changing your mouse device to <c>/dev/input/mice</c> in
250     the "InputDevice" section of <path>xorg.conf</path>. You might not be able to
251     deduce the exact resolution, but you should be able to see if it's too low. You
252     can exit any time by pressing Ctrl-Alt-Backspace.
253 swift 1.7 </p>
254    
255 swift 1.1 </body>
256     </section>
257     <section>
258     <title>Alternative: Semi-Automatic Generation of xorg.conf</title>
259     <body>
260    
261     <p>
262     Xorg provides a tool called <c>xorgconfig</c> which will ask you for various
263     information regarding your system (graphical adapter, keyboard, ...). Based on
264     your input it will create a <path>xorg.conf</path> file.
265     </p>
266    
267     <pre caption="Semi-Automatic Generation of xorg.conf">
268     # <i>xorgconfig</i>
269     </pre>
270    
271 swift 1.10 <p>
272     Another tool, also provided by Xorg, is <c>xorgcfg</c>, which will first
273 fox2mike 1.16 attempt to run <c>Xorg -configure</c> and then start the X server for more
274 swift 1.10 final tweaking.
275     </p>
276    
277     <pre caption="Using xorgcfg">
278     # <i>xorgcfg</i>
279 swift 1.13 <comment>(In case X crashes or the configuration fails, try:)</comment>
280     # <i>xorgcfg -textmode</i>
281 swift 1.10 </pre>
282    
283 swift 1.1 </body>
284     </section>
285     <section>
286     <title>Copying over xorg.conf</title>
287     <body>
288    
289     <p>
290 swift 1.9 Let us copy over the <path>xorg.conf.new</path> to
291     <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run
292     <c>X -config</c> -- typing just <c>X</c> or <c>startx</c> is far more easy :)
293 swift 1.1 </p>
294    
295     <pre caption="Copying over xorg.conf">
296     # <i>cp /root/xorg.conf.new /etc/X11/xorg.conf</i>
297     </pre>
298    
299 swift 1.9 </body>
300     </section>
301     <section id="using_startx">
302     <title>Using startx</title>
303     <body>
304    
305 swift 1.1 <p>
306 swift 1.9 Now try <c>startx</c> to start up your X server. <c>startx</c> is a script
307     that executes an <e>X session</e>, that is, it starts the X servers and some
308     graphical applications on top of it. It decides which applications to run
309     using the following logic:
310 swift 1.1 </p>
311    
312 swift 1.9 <ul>
313     <li>
314     If a file named <path>.xinitrc</path> exists in the home directory, it will
315     execute the commands listed there.
316     </li>
317     <li>
318     Otherwise, it will read the value of the XSESSION variable and will execute
319     one of the sessions available in <path>/etc/X11/Sessions/</path>
320     accordingly (you can set the value of XSESSION in <path>/etc/rc.conf</path>
321     to make it a default for all the users on the system).
322     </li>
323     <li>
324     If all of the above fail, it will fall back to a simple window manager,
325     usually <c>twm</c>.
326     </li>
327     </ul>
328    
329 swift 1.1 <pre caption="Starting X">
330     # <i>startx</i>
331     </pre>
332    
333 swift 1.9 <p>
334     If you see an ugly, loathsome, repulsive, deformed window manager, that's
335     <c>twm</c>. To finish the twm session, type in <c>exit</c> or Ctrl-D in the
336     upcoming xterms. You can also kill the X session using the Ctrl-Alt-Backspace
337 fox2mike 1.16 combination. This will however make X exit disgracefully -- something that you
338 swift 1.9 might not always want. It doesn't hurt though :)
339     </p>
340    
341 swift 1.1 </body>
342     </section>
343 swift 1.9 </chapter>
344     <chapter>
345     <title>Tweaking xorg.conf</title>
346 swift 1.1 <section>
347     <title>Setting your Resolution</title>
348     <body>
349    
350     <p>
351     If you feel that the screen resolution is wrong, you will need to check two
352     sections in your configuration. First of all, you have the <e>Screen</e> section
353 fox2mike 1.16 which lists the resolutions, if any that your X server will run at. By
354 swift 1.1 default, this section might not list any resolutions at all. If this is the
355     case, Xorg will estimate the resolutions based on the information in the
356     second section, <e>Monitor</e>.
357     </p>
358    
359     <p>
360     What happens is that Xorg checks the settings of <c>HorizSync</c> and
361     <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions.
362     For now, leave these settings as-is. Only when the changes to the <e>Screen</e>
363     section (which we will describe in a minute) don't work, then you will need to
364     look up the specs for your monitor and fill in the correct values. You can also
365     use a tool that searches for your monitor's specs, such as
366     <c>sys-apps/ddcxinfo-knoppix</c>.
367     </p>
368    
369     <warn>
370 fox2mike 1.16 Do <b>not</b> "just" change the values of these two monitor related variables
371 swift 1.1 without consulting the technical specifications of your monitor. Setting
372     incorrect values lead to out-of-sync errors at best and smoked up screens at
373     worst.
374     </warn>
375    
376     <p>
377     Now let us change the resolutions. In the next example from
378     <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the
379     <c>DefaultDepth</c> so that our X server starts with 24 bits at 1024x768 by
380 fox2mike 1.16 default. Don't mind the given strings -- they are examples and will most likely
381 swift 1.1 differ from the settings on your system.
382     </p>
383    
384     <pre caption="Changing the Screen section in /etc/X11/xorg.conf">
385     Section "Screen"
386     Identifier "Default Screen"
387     Device "S3 Inc. ProSavage KN133 [Twister K]"
388     Monitor "Generic Monitor"
389     <i>DefaultDepth 24</i>
390     <comment># Skipping some text to improve readability</comment>
391     SubSection "Display"
392     Depth 24
393     <i>Modes "1024x768"</i>
394     EndSubSection
395     EndSection
396     </pre>
397    
398     <p>
399     Run X (<c>startx</c>) to discover it uses the resolution you want :)
400     </p>
401    
402     </body>
403     </section>
404     <section>
405     <title>Configuring your Keyboard</title>
406     <body>
407    
408     <p>
409     To setup X to use an international keyboard, search for the <e>InputDevice</e>
410     section that configures the keyboard and add the <c>XkbLayout</c> option to
411     point to the keyboard layout you want. As an example, we show you how to apply
412     for the Belgian layout. Just substitute the country-keycode with yours:
413     </p>
414    
415     <pre caption="Changing the keyboard layout">
416     Section "InputDevice"
417     Identifier "Generic Keyboard"
418     Driver "keyboard"
419     Option "CoreKeyboard"
420 swift 1.3 Option "XkbRules" "xorg"
421 swift 1.1 Option "XkbModel" "pc105"
422     <i>Option "XkbLayout" "be"</i>
423     EndSection
424     </pre>
425    
426     </body>
427     </section>
428     <section>
429     <title>Configuring your Mouse</title>
430     <body>
431    
432     <p>
433     If your mouse isn't working, you will first need to find out if it is detected
434 neysx 1.12 by the kernel at all. Mice are (device-wise) seen as
435 swift 1.11 <path>/dev/input/mouse0</path> (or <path>/dev/input/mice</path> if you want to
436 swift 1.14 use several mice). In some cases <path>/dev/psaux</path> is used. In either
437     case you can check if the devices do represent
438 fox2mike 1.17 your mouse by checking the output of those files when you move your mouse. You
439     will usually see some junk on your screen. To end the session press
440     <c>Ctrl-C</c>.
441 swift 1.1 </p>
442    
443     <pre caption="Checking the device files">
444 swift 1.11 # <i>cat /dev/input/mouse0</i>
445 swift 1.1 <comment>(Don't forget to press Ctrl-C to end this)</comment>
446     </pre>
447    
448     <p>
449     If your mouse isn't detected, verify if all the necessary modules are loaded.
450     </p>
451    
452     <p>
453     If your mouse is detected, fill in the device in the appropriate
454     <e>InputDevice</e> section. In the next example you'll see we also set two other
455 fox2mike 1.16 options: <c>Protocol</c> (which lists the mouse protocol to be used -- most
456     users will use PS/2 or IMPS/2) and <c>ZAxisMapping</c> (which allows for the
457 swift 1.1 mousewheel (if applicable) to be used).
458     </p>
459    
460     <pre caption="Changing the mouse settings in Xorg">
461     Section "InputDevice"
462     Identifier "TouchPad Mouse"
463     Driver "mouse"
464     Option "CorePointer"
465 swift 1.11 <i>Option "Device" "/dev/input/mouse0"</i>
466 swift 1.1 <i>Option "Protocol" "IMPS/2"</i>
467     <i>Option "ZAxisMapping" "4 5"</i>
468     EndSection
469     </pre>
470    
471     <p>
472     Run <c>startx</c> and be happy about the result :) Congratulations, you now
473     (hopefully) have a working Xorg on your system. The next step is to remove this
474     ugly lightweight window manager and use a high-feature one (or even a desktop
475     environment) such as KDE or GNOME, but that's not part of this guide :)
476     </p>
477    
478     </body>
479     </section>
480     </chapter>
481     <chapter>
482     <title>Resources</title>
483     <section>
484     <title>Creating and Tweaking xorg.conf</title>
485     <body>
486    
487     <p>
488     First of all, <c>man 5 xorg.conf</c> provides a quick yet complete reference
489     about the syntaxis used by the configuration file. Be sure to have it open on a
490     terminal near you when you edit your configuration file!
491     </p>
492    
493     <p>
494     A second point of resources on your system is the
495     <path>/usr/X11R6/lib/X11/doc</path> directory with various <path>README</path>'s
496     for individual graphical chipsets.
497     </p>
498    
499     <p>
500     There are also many online resources on editing <path>xorg.conf</path>. We only
501     list few of them here, be sure to <uri link="http://www.google.com">Google</uri>
502     for more :) As <path>xorg.conf</path> and <path>XF86Config</path> (the
503     configuration file for the XFree86 project) use the
504     same syntaxis for most configuration options and more information about
505     <path>XF86Config</path> is available, we'll list those resources as well.
506     </p>
507    
508     <ul>
509     <li>
510     <uri link="http://tldp.org/HOWTO/XFree-Local-multi-user-HOWTO/">The XFree
511     Local Multi-User HOWTO</uri>
512     </li>
513     <li>
514     <uri
515     link="http://www-106.ibm.com/developerworks/edu/os-dw-linuxxwin-i.html">An
516     Introduction to XFree 4.x</uri> by Chris Houser
517     </li>
518     </ul>
519    
520     </body>
521     </section>
522 rane 1.18 <section>
523     <title>Other resources</title>
524     <body>
525    
526     <p>
527     If you want to update your system from the old monolithic Xorg to the newer,
528     modular Xorg 7, you should refer to the <uri
529     link="/proj/en/desktop/x/x11/modular-x-howto.xml">Migrating to Modular X
530     HOWTO</uri>.
531     </p>
532    
533     <p>
534     More information about configuring different packages to work in X environment
535     can be found in the <uri link="/doc/en/?catid=desktop">Gentoo Desktop
536     Documentation Resources</uri> section of our documentation.
537     </p>
538    
539     </body>
540     </section>
541 swift 1.1 </chapter>
542     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20