/[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.17 - (hide annotations) (download) (as text)
Fri Sep 9 06:01:15 2005 UTC (8 years, 11 months ago) by fox2mike
Branch: MAIN
Changes since 1.16: +6 -5 lines
File MIME type: application/xml
#101912 - Minor content change, make clear that the mouse output isn't meaningful. Fixed license to 2.5 as well.

1 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2    
3 fox2mike 1.17 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xorg-config.xml,v 1.16 2005/09/09 05:57:43 fox2mike 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     <mail link="swift@gentoo.org">Sven Vermeulen</mail>
13     </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 fox2mike 1.17 <version>1.13</version>
26 fox2mike 1.16 <date>2005-09-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     <pre caption="Installing Xorg">
101     # <i>emerge xorg-x11</i>
102     </pre>
103    
104     <p>
105     When the installation is finished, you might need to reinitialise some
106     environment variables before you continue. Just run <c>env-update</c> followed
107     by <c>source /etc/profile</c> and you're all set. This doesn't harm your system
108     in any way.
109     </p>
110    
111     <pre caption="Reinitialising the environment variables">
112     # <i>env-update</i>
113     # <i>source /etc/profile</i>
114     </pre>
115    
116     </body>
117     </section>
118     </chapter>
119     <chapter>
120     <title>Configuring Xorg</title>
121     <section>
122     <title>The xorg.conf File</title>
123     <body>
124    
125     <p>
126 neysx 1.2 The configuration file of Xorg is called <path>xorg.conf</path> and it
127 swift 1.1 resides in <path>/etc/X11</path>. The Xorg-X11 package provides an example
128     configuration as <path>/etc/X11/xorg.conf.example</path> which you can use to
129     create your own configuration. It is heavily commented, but if you are in need
130     of more documentation regarding the syntax, don't hesitate to read the man page:
131     </p>
132    
133     <pre caption="Reading the xorg.conf man page">
134     # <i>man 5 xorg.conf</i>
135     </pre>
136    
137     <p>
138     Happy reading for those of you willing to. We surely don't so we'll continue
139     with checking out how we can create the file automatically.
140     </p>
141    
142     </body>
143     </section>
144     <section>
145     <title>Default: Automatic Generation of xorg.conf</title>
146     <body>
147    
148     <p>
149     Xorg itself is able to guess most parameters for you. In most cases, you
150     will only have to change some lines to get the resolution you want up and
151     running. If you are interested in more in-depth tweaking, be sure to check the
152     resources at the end of this chapter. But first, let us generate a (hopefully
153     working) Xorg configuration file.
154     </p>
155    
156     <pre caption="Generating an xorg.conf file">
157     # <i>Xorg -configure</i>
158     </pre>
159    
160     <p>
161     Be sure to read the last lines printed on your screen when Xorg has finished
162     probing your hardware. If it tells you it failed at some point, you're forced to
163     manually write an <path>xorg.conf</path> file. Assuming that it didn't fail, it
164     will have told you that it has written <path>/root/xorg.conf.new</path> ready
165     for you to test. So let's test :)
166     </p>
167    
168     <pre caption="Testing the xorg.conf.new file">
169 swift 1.6 # <i>X -config /root/xorg.conf.new</i>
170 swift 1.1 </pre>
171    
172     <p>
173 swift 1.9 If all goes well, you should see a simple black and white pattern. Verify if
174     your mouse works correctly and if the resolution is good. You might not be able
175     to deduce the exact resolution, but you should be able to see if it's too low.
176     You can exit any time by pressing Ctrl-Alt-Backspace.
177 swift 1.7 </p>
178    
179 swift 1.1 </body>
180     </section>
181     <section>
182     <title>Alternative: Semi-Automatic Generation of xorg.conf</title>
183     <body>
184    
185     <p>
186     Xorg provides a tool called <c>xorgconfig</c> which will ask you for various
187     information regarding your system (graphical adapter, keyboard, ...). Based on
188     your input it will create a <path>xorg.conf</path> file.
189     </p>
190    
191     <pre caption="Semi-Automatic Generation of xorg.conf">
192     # <i>xorgconfig</i>
193     </pre>
194    
195 swift 1.10 <p>
196     Another tool, also provided by Xorg, is <c>xorgcfg</c>, which will first
197 fox2mike 1.16 attempt to run <c>Xorg -configure</c> and then start the X server for more
198 swift 1.10 final tweaking.
199     </p>
200    
201     <pre caption="Using xorgcfg">
202     # <i>xorgcfg</i>
203 swift 1.13 <comment>(In case X crashes or the configuration fails, try:)</comment>
204     # <i>xorgcfg -textmode</i>
205 swift 1.10 </pre>
206    
207 swift 1.1 </body>
208     </section>
209     <section>
210     <title>Copying over xorg.conf</title>
211     <body>
212    
213     <p>
214 swift 1.9 Let us copy over the <path>xorg.conf.new</path> to
215     <path>/etc/X11/xorg.conf</path> now, so we won't have to continuously run
216     <c>X -config</c> -- typing just <c>X</c> or <c>startx</c> is far more easy :)
217 swift 1.1 </p>
218    
219     <pre caption="Copying over xorg.conf">
220     # <i>cp /root/xorg.conf.new /etc/X11/xorg.conf</i>
221     </pre>
222    
223 swift 1.9 </body>
224     </section>
225     <section id="using_startx">
226     <title>Using startx</title>
227     <body>
228    
229 swift 1.1 <p>
230 swift 1.9 Now try <c>startx</c> to start up your X server. <c>startx</c> is a script
231     that executes an <e>X session</e>, that is, it starts the X servers and some
232     graphical applications on top of it. It decides which applications to run
233     using the following logic:
234 swift 1.1 </p>
235    
236 swift 1.9 <ul>
237     <li>
238     If a file named <path>.xinitrc</path> exists in the home directory, it will
239     execute the commands listed there.
240     </li>
241     <li>
242     Otherwise, it will read the value of the XSESSION variable and will execute
243     one of the sessions available in <path>/etc/X11/Sessions/</path>
244     accordingly (you can set the value of XSESSION in <path>/etc/rc.conf</path>
245     to make it a default for all the users on the system).
246     </li>
247     <li>
248     If all of the above fail, it will fall back to a simple window manager,
249     usually <c>twm</c>.
250     </li>
251     </ul>
252    
253 swift 1.1 <pre caption="Starting X">
254     # <i>startx</i>
255     </pre>
256    
257 swift 1.9 <p>
258     If you see an ugly, loathsome, repulsive, deformed window manager, that's
259     <c>twm</c>. To finish the twm session, type in <c>exit</c> or Ctrl-D in the
260     upcoming xterms. You can also kill the X session using the Ctrl-Alt-Backspace
261 fox2mike 1.16 combination. This will however make X exit disgracefully -- something that you
262 swift 1.9 might not always want. It doesn't hurt though :)
263     </p>
264    
265 swift 1.1 </body>
266     </section>
267 swift 1.9 </chapter>
268     <chapter>
269     <title>Tweaking xorg.conf</title>
270 swift 1.1 <section>
271     <title>Setting your Resolution</title>
272     <body>
273    
274     <p>
275     If you feel that the screen resolution is wrong, you will need to check two
276     sections in your configuration. First of all, you have the <e>Screen</e> section
277 fox2mike 1.16 which lists the resolutions, if any that your X server will run at. By
278 swift 1.1 default, this section might not list any resolutions at all. If this is the
279     case, Xorg will estimate the resolutions based on the information in the
280     second section, <e>Monitor</e>.
281     </p>
282    
283     <p>
284     What happens is that Xorg checks the settings of <c>HorizSync</c> and
285     <c>VertRefresh</c> in the <e>Monitor</e> section to compute valid resolutions.
286     For now, leave these settings as-is. Only when the changes to the <e>Screen</e>
287     section (which we will describe in a minute) don't work, then you will need to
288     look up the specs for your monitor and fill in the correct values. You can also
289     use a tool that searches for your monitor's specs, such as
290     <c>sys-apps/ddcxinfo-knoppix</c>.
291     </p>
292    
293     <warn>
294 fox2mike 1.16 Do <b>not</b> "just" change the values of these two monitor related variables
295 swift 1.1 without consulting the technical specifications of your monitor. Setting
296     incorrect values lead to out-of-sync errors at best and smoked up screens at
297     worst.
298     </warn>
299    
300     <p>
301     Now let us change the resolutions. In the next example from
302     <path>/etc/X11/xorg.conf</path> we add the <c>Modes</c> lines and the
303     <c>DefaultDepth</c> so that our X server starts with 24 bits at 1024x768 by
304 fox2mike 1.16 default. Don't mind the given strings -- they are examples and will most likely
305 swift 1.1 differ from the settings on your system.
306     </p>
307    
308     <pre caption="Changing the Screen section in /etc/X11/xorg.conf">
309     Section "Screen"
310     Identifier "Default Screen"
311     Device "S3 Inc. ProSavage KN133 [Twister K]"
312     Monitor "Generic Monitor"
313     <i>DefaultDepth 24</i>
314     <comment># Skipping some text to improve readability</comment>
315     SubSection "Display"
316     Depth 24
317     <i>Modes "1024x768"</i>
318     EndSubSection
319     EndSection
320     </pre>
321    
322     <p>
323     Run X (<c>startx</c>) to discover it uses the resolution you want :)
324     </p>
325    
326     </body>
327     </section>
328     <section>
329     <title>Configuring your Keyboard</title>
330     <body>
331    
332     <p>
333     To setup X to use an international keyboard, search for the <e>InputDevice</e>
334     section that configures the keyboard and add the <c>XkbLayout</c> option to
335     point to the keyboard layout you want. As an example, we show you how to apply
336     for the Belgian layout. Just substitute the country-keycode with yours:
337     </p>
338    
339     <pre caption="Changing the keyboard layout">
340     Section "InputDevice"
341     Identifier "Generic Keyboard"
342     Driver "keyboard"
343     Option "CoreKeyboard"
344 swift 1.3 Option "XkbRules" "xorg"
345 swift 1.1 Option "XkbModel" "pc105"
346     <i>Option "XkbLayout" "be"</i>
347     EndSection
348     </pre>
349    
350     </body>
351     </section>
352     <section>
353     <title>Configuring your Mouse</title>
354     <body>
355    
356     <p>
357     If your mouse isn't working, you will first need to find out if it is detected
358 neysx 1.12 by the kernel at all. Mice are (device-wise) seen as
359 swift 1.11 <path>/dev/input/mouse0</path> (or <path>/dev/input/mice</path> if you want to
360 swift 1.14 use several mice). In some cases <path>/dev/psaux</path> is used. In either
361     case you can check if the devices do represent
362 fox2mike 1.17 your mouse by checking the output of those files when you move your mouse. You
363     will usually see some junk on your screen. To end the session press
364     <c>Ctrl-C</c>.
365 swift 1.1 </p>
366    
367     <pre caption="Checking the device files">
368 swift 1.11 # <i>cat /dev/input/mouse0</i>
369 swift 1.1 <comment>(Don't forget to press Ctrl-C to end this)</comment>
370     </pre>
371    
372     <p>
373     If your mouse isn't detected, verify if all the necessary modules are loaded.
374     </p>
375    
376     <p>
377     If your mouse is detected, fill in the device in the appropriate
378     <e>InputDevice</e> section. In the next example you'll see we also set two other
379 fox2mike 1.16 options: <c>Protocol</c> (which lists the mouse protocol to be used -- most
380     users will use PS/2 or IMPS/2) and <c>ZAxisMapping</c> (which allows for the
381 swift 1.1 mousewheel (if applicable) to be used).
382     </p>
383    
384     <pre caption="Changing the mouse settings in Xorg">
385     Section "InputDevice"
386     Identifier "TouchPad Mouse"
387     Driver "mouse"
388     Option "CorePointer"
389 swift 1.11 <i>Option "Device" "/dev/input/mouse0"</i>
390 swift 1.1 <i>Option "Protocol" "IMPS/2"</i>
391     <i>Option "ZAxisMapping" "4 5"</i>
392     EndSection
393     </pre>
394    
395     <p>
396     Run <c>startx</c> and be happy about the result :) Congratulations, you now
397     (hopefully) have a working Xorg on your system. The next step is to remove this
398     ugly lightweight window manager and use a high-feature one (or even a desktop
399     environment) such as KDE or GNOME, but that's not part of this guide :)
400     </p>
401    
402     </body>
403     </section>
404     </chapter>
405     <chapter>
406     <title>Resources</title>
407     <section>
408     <title>Creating and Tweaking xorg.conf</title>
409     <body>
410    
411     <p>
412     First of all, <c>man 5 xorg.conf</c> provides a quick yet complete reference
413     about the syntaxis used by the configuration file. Be sure to have it open on a
414     terminal near you when you edit your configuration file!
415     </p>
416    
417     <p>
418     A second point of resources on your system is the
419     <path>/usr/X11R6/lib/X11/doc</path> directory with various <path>README</path>'s
420     for individual graphical chipsets.
421     </p>
422    
423     <p>
424     There are also many online resources on editing <path>xorg.conf</path>. We only
425     list few of them here, be sure to <uri link="http://www.google.com">Google</uri>
426     for more :) As <path>xorg.conf</path> and <path>XF86Config</path> (the
427     configuration file for the XFree86 project) use the
428     same syntaxis for most configuration options and more information about
429     <path>XF86Config</path> is available, we'll list those resources as well.
430     </p>
431    
432     <ul>
433     <li>
434     <uri link="http://tldp.org/HOWTO/XFree-Local-multi-user-HOWTO/">The XFree
435     Local Multi-User HOWTO</uri>
436     </li>
437     <li>
438     <uri
439     link="http://www-106.ibm.com/developerworks/edu/os-dw-linuxxwin-i.html">An
440     Introduction to XFree 4.x</uri> by Chris Houser
441     </li>
442     </ul>
443    
444     </body>
445     </section>
446     </chapter>
447     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20