Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 267769 - X server installation guide need to be updated
Summary: X server installation guide need to be updated
Status: RESOLVED FIXED
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Installation Handbook (show other bugs)
Hardware: All Linux
: High normal (vote)
Assignee: nm (RETIRED)
URL: http://www.gentoo.org/doc/en/xorg-con...
Whiteboard:
Keywords:
: 268383 270565 275270 284075 (view as bug list)
Depends on: 229769
Blocks: 275338
  Show dependency tree
 
Reported: 2009-04-28 11:30 UTC by yarma
Modified: 2010-03-16 20:09 UTC (History)
9 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description yarma 2009-04-28 11:30:18 UTC
since the new release of xorg-server using evdev, there is a great upgrade guide (http://www.gentoo.org/proj/en/desktop/x/x11/xorg-server-1.5-upgrade-guide.xml), but the installation guide does not take the changes in account ... 

The new users didn't know they are making a wrong config and didn't unterstand why xorg is not working properly.
There is a strong need to merge the upgrade guide into the installation guide!

Reproducible: Always

Actual Results:  
installation guide for xorg-server-1.2

Expected Results:  
installation guide with xorg-server-1.5 full explanation
Comment 1 nm (RETIRED) gentoo-dev 2009-04-28 23:20:38 UTC
We're not going to merge the two guides, but we do need to update the installation guide.

CCing the X11 team -- we need your help, guys. Can you do a quick rundown of the changes that should be made to the install guide? Thanks.
Comment 2 Tomáš Chvátal (RETIRED) gentoo-dev 2009-04-28 23:30:10 UTC
Hi,
nowdays mostly user should keep empty xorg.conf and put stuff in there only if they really need to switch some default variable.
So systems should be still working peachy with no xorg.conf at all.
Most of the tweaking parts we can see there for input devices is done by HAL itself so it should describe how to create correct fdi files.
And for the tweaking graphic there should be some example how to write section in xorg.conf and what should it look like.
#BOF
Section "Driver"
Identifier "ATI"
Driver "radeon"
Option "BusType" "PCIE"
EndSection
#EOF
Should work as only thing in xorg.conf as whole.

@remi: did i forget something or wrote something wrongly?
Comment 3 Rémi Cardona (RETIRED) gentoo-dev 2009-04-29 09:14:47 UTC
@Tomas, that's basically it (except I'm not even sure if BusType is of any use... ;) )

@all, we should really clean up our docs, whether they be in the X area or the doc area, I think it's high time we did something about it.

Among other things, here's what I think needs to be cleaned up :
 - xorgconfig and xorgcfg are gone from newer versions of Xorg, let's stop referencing them even for 1.5
 - X -configure is mostly useless, no need to recommend it
 - the DRI guide should be merged into the X configuration guide as more and more drivers are going to be unusable without DRI anyway.
 - the nvidia guide should *definitely* stop recommending using a framebuffer driver
 - maybe we should have a bigger HAL guide somewhere?

Yeah, in any case, if we want to get this right, it's going to require some man-hours.

I'm thinking maybe we should actually have a "desktop handbook" instead of having various "guides", so we can do more cross-referencing...

Anyway, that's just wishful thinking.

Cheers
Comment 4 Donnie Berkholz (RETIRED) gentoo-dev 2009-04-30 00:47:58 UTC
`X -configure` is useful for this case: You want the default configuration so you can make a small modification to it, perhaps setting a few options.
Comment 5 nm (RETIRED) gentoo-dev 2009-05-03 07:42:19 UTC
*** Bug 268383 has been marked as a duplicate of this bug. ***
Comment 6 Serkan Kaba (RETIRED) gentoo-dev 2009-05-20 14:07:19 UTC
*** Bug 270565 has been marked as a duplicate of this bug. ***
Comment 7 Vítor Brandão (noisebleed) 2009-05-20 14:29:59 UTC
I like the idea of a "desktop handbook", merging info from the dri howto, nvidia/ati,etc. and making the transition between the gentoo install handbook and the kde/gnome/etc. guide.
Comment 8 nm (RETIRED) gentoo-dev 2009-05-20 19:34:55 UTC
(In reply to comment #3)
>  - the DRI guide should be merged into the X configuration guide as more and
> more drivers are going to be unusable without DRI anyway.

This might be possible. Lots of work, but it might be possible.

>  - the nvidia guide should *definitely* stop recommending using a framebuffer
> driver

Why? What does that have to do with the Xserver-1.5 update? uvesafb is a good idea if you're on nvidia-drivers, as it's not like it interferes with KMS the way intelfb does with xf86-video-intel. I can't think of a single reason to run without a framebuffer when using nvidia-drivers. My 1440x900 screen *needs* uvesafb (or similar) running so that I get decent resolution and fonts before X is running, or if X is not running at all. Otherwise it's almost useless.

Can you elaborate? :)

> I'm thinking maybe we should actually have a "desktop handbook" instead of
> having various "guides", so we can do more cross-referencing...

Dunno . . . seems like it would lead to more confusion than anything else. There are so many hardware-specific instructions that trying to cram them all into one handbook is a bad idea.

Also is really, really hard to do in general. SwifT tried to do this for a number of years, but even that wasn't enough time to get all the kinks worked out:

http://www.gentoo.org/doc/en/handbook/draft/complete/handbook.xml
Comment 9 Rémi Cardona (RETIRED) gentoo-dev 2009-05-22 12:31:43 UTC
(In reply to comment #8)
> Can you elaborate? :)

It's not related to KMS at all. Having 2 video drivers for the same hardware is just doomed to failure. For now, it looks like nvidia is doing an OK job at cleaning up their registers on VT switch but experience shows that no X driver should (yet) be trusted to do that properly.

I guess then that I don't mind documenting (u)vesafb in a separate section with all the appropriate warnings and disclaimers :)

> Dunno . . . seems like it would lead to more confusion than anything else.
> There are so many hardware-specific instructions that trying to cram them all
> into one handbook is a bad idea.

Well, my plan was to have an overall "Desktop Handbook" with a specific page for each hardware family : Intel, AMD/ATi, nVidia, Wacom, Synaptics, ...

My "approach" is to now do this by hardware type, rather than by software pieces, because more and more, configuring a graphics card will require fiddling with at least 1) the kernel 2) the X drivers and Xorg, and 3) mesa

I'm thinking that such an organization would make more sense for our users.

> Also is really, really hard to do in general. SwifT tried to do this for a
> number of years, but even that wasn't enough time to get all the kinks worked
> out:
> 
> http://www.gentoo.org/doc/en/handbook/draft/complete/handbook.xml

Wow, that's just waaay beyond anything I had in mind. I just want to have something that makes sense for Desktop Users. I'm not planning to replace anything from the Installation Handbook (which IMHO is perfectly fine the way it is).

Basically, I just would like to merge in a coherent set some of the existing documentation we already have lying around on our servers (and clean them up a bit).

Hope that makes more sense :)

Cheers
Comment 10 Xavier Neys (RETIRED) gentoo-dev 2009-06-24 16:01:14 UTC
*** Bug 275270 has been marked as a duplicate of this bug. ***
Comment 11 мамонт 2009-06-24 23:49:45 UTC
Even if the doc wouldn't be perfect, just a few changes would at least make it not useless.  It's two months after the fact now, when this should've been done before 1.5 even went stable.

Could someone just make the minimal changes necessary to yield a working X?

Even a mere notice like "This document requires revision; for the time being you will need to also read and follow the *1.5 upgrade guide* even if you are installing xorg for the first time." would help so many people.

Based on my IRC log I'd conservatively estimate a new person needing this information comes into #gentoo once or twice every hour.  Those are just the people who don't give up, & who don't use the forums or some other medium for bug resolution instead.
Comment 12 nm (RETIRED) gentoo-dev 2009-06-25 00:00:49 UTC
X11 team:

Please get together and give us a coherent list of changes. ASAP would be nice. Doesn't have to be a GuideXML patch if you lack the expertise, can just be a plain-text list of "this says this but should say this" changes. Right now there's nothing concrete we can use to update the guide. And we'd like to get the guide updated soon. Otherwise we'll get more whiners like comment #11.

However, make sure it's for xserver 1.5 only, nothing from xserver 1.6. See below . . .

(In reply to comment #11)
> this should've been done before 1.5 even went stable.

Wrong. We don't document ~arch in our stable guides, as that would cause mass confusion. We track only the stable tree.
Comment 13 мамонт 2009-06-25 01:55:32 UTC
(In reply to comment #12)
> We don't document ~arch in our stable guides, as that would cause mass
> confusion. We track only the stable tree.

I meant it should've been _ready_ before 1.5 went stable, of course.
What good is "stable" software that people don't know how to configure...
Comment 14 Xavier Neys (RETIRED) gentoo-dev 2009-09-08 16:02:29 UTC
*** Bug 284075 has been marked as a duplicate of this bug. ***
Comment 15 nm (RETIRED) gentoo-dev 2009-10-02 09:05:29 UTC
Okay, I've been rewriting the guide myself, without really checking the comments here (yet).

There's an insanely crazy amount of stuff to do and discuss, like:

1. The guide mentions Ctrl-Alt-Bksp a LOT during the initial config sections just to make sure the server is working. What to do with these? That combo doesn't work in xserver 1.6 unless it's enabled via HAL FDI files or via setxkb magic.

2. Do we just mention one way of configuring Xorg? The 1.5 upgrade guide mentions both with and without evdev, but that's for upgrading. Our guide is for an Xorg install from scratch. It *would be much simpler* to just follow the default HAL setup and ONLY that setup, but I'm not sure if this is the best idea given the corner cases where HAL/evdev do not work on users' systems.

3. Balancing out HAL/evdev and the desired "no xorg.conf" setup with using HAL/evdev and a minimal Xorg.conf. For example, both my workstation and my laptop have a minimal xorg.conf, if only to specify a few things like video card options/tweaks and setting proper screen resolution & color depth. How can these things be written into a guide that's trying to avoid using xorg.conf at all? This is not just a weird case for me, but fairly widespread; check forums.gentoo.org.

- - -

These issues and everything else in the comments for this bug need to be addressed, so let's get to thinkin'.

I've already started rewriting the xorg-config guide and have a draft available on my devspace:

http://dev.gentoo.org/~nightmorph/draft/xorg-config.xml

It doesn't yet cover all the points made earlier, and I've tried to cover stuff not mentioned elsewhere, like the constantly changing status of the FOSS drivers for ATI/nVidia cards. Especially ATI, since now users are *required* to use FOSS drivers for X1000 series and older, as fglrx only works for RadeonHD cards. And a few other issues besides those.

So: read my draft, read this comment, and the previous comments, and let's hammer out a fully up-to-date guide. Please.
Comment 16 Rémi Cardona (RETIRED) gentoo-dev 2009-10-02 09:46:01 UTC
(In reply to comment #15)
> Okay, I've been rewriting the guide myself, without really checking the
> comments here (yet).
> 
> There's an insanely crazy amount of stuff to do and discuss, like:
> 
> 1. The guide mentions Ctrl-Alt-Bksp a LOT during the initial config sections
> just to make sure the server is working. What to do with these? That combo
> doesn't work in xserver 1.6 unless it's enabled via HAL FDI files or via setxkb
> magic.

Actually, with HAL, input can and should be checked without running X. Users should be looking at "lshal" output to see if their mice/keyboards have the correct properties.

And the doc should add the zapping options, maybe with an xml comment pointing out that this enables ctrl-alt-backspace which can be dangerous if left on all the time.

> 2. Do we just mention one way of configuring Xorg? The 1.5 upgrade guide
> mentions both with and without evdev, but that's for upgrading. Our guide is
> for an Xorg install from scratch. It *would be much simpler* to just follow the
> default HAL setup and ONLY that setup, but I'm not sure if this is the best
> idea given the corner cases where HAL/evdev do not work on users' systems.

The xorg 1.5 upgrade guide was meant to show that users didn't have to completely change their setups if they wanted to.

New users should definitely be shown only the HAL/evdev way, it's the way forward. Only synaptics (and maybe wacom) is the other major drivers we should document.

So yeah, full ACK there.

> 3. How can
> these things be written into a guide that's trying to avoid using xorg.conf at
> all? This is not just a weird case for me, but fairly widespread; check
> forums.gentoo.org.

Indeed, we're getting close to no xorg.conf, but we're not _quite_ there yet. The best is probably to use a dead simple xorg.conf like Ubuntu ships [1]. Users then only need to add one or two lines at most for specific drivers such as nvidia or fglrx.

[1] http://forum.ubuntu-fr.org/viewtopic.php?pid=2942931

> So: read my draft, read this comment, and the previous comments, and let's
> hammer out a fully up-to-date guide. Please.

Looking at it NOW! :)

Thanks
Comment 17 matt 2009-10-14 18:29:38 UTC
still red tape?  suggestions:

*) add a notice at the top that its outdated.  

*) change INPUT_DEVICES="keyboard mouse"

*) add info about using radeon for older cards and it might work for newer ?

*) use nvidia-xconfig, for proprietary nvidia, use ati-xconfig for proprietary ati drivers, and none for open source driver.

if this can not be agreed upon, at least add a notice that the current docs are old, and may not work, and provide the new way.
Comment 18 Tomáš Chvátal (RETIRED) gentoo-dev 2009-10-14 18:41:46 UTC
(In reply to comment #17)
> *) add info about using radeon for older cards and it might work for newer ?
> 
As radeon/ati-drivers maintainer i can answer this one to be facticaly correct:
ati-drivers - support for cards of HD line. R600 chipset and newer.
xf86-video-ati - any card you find with ati logo (or amd :p) and using the name radeon
xf86-video-radeonhd - probably same as the ati-drivers, i recomend to use -ati one.
Comment 19 Pacho Ramos gentoo-dev 2009-10-15 20:32:19 UTC
(In reply to comment #17)

> *) use nvidia-xconfig, for proprietary nvidia, use ati-xconfig for proprietary

I think it's not needed, with current stable I can configure properly X on my computers with nvidia driver with only a few lines for specifying, for example, 75Hz to be used by X, but driver is autodetected and works fine :-/
Comment 20 nm (RETIRED) gentoo-dev 2009-12-09 01:38:25 UTC
Done.

From the commit 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."

Should satisfy Remi's thoughts on comment #16, and the other stuff that's been brought up. I tried to leave out xorg.conf as much as possible, as things like keyboard/mouse management are really, really complicated when HAL/evdev are available. I just stuck to changing display resolution, and focused on using HAL/evdev for input config.

Of course, now that X upstream has confirmed they'll be moving away from HAL (and evdev?) in upcoming releases, I'll probably have to rewrite the doc yet again. So who knows what that'll look like.

In the mean time, this bug is FIXED as far as I can tell. Please do review the new guide:

http://www.gentoo.org/doc/en/xorg-config.xml
Comment 21 yarma 2009-12-09 08:21:18 UTC
nice job ;)
Comment 22 Rémi Cardona (RETIRED) gentoo-dev 2009-12-09 16:45:48 UTC
(In reply to comment #20)
> Done.

Wow, thanks for doing this! /me owes Josh a pint.

> Should satisfy Remi's thoughts on comment #16, and the other stuff that's been
> brought up. I tried to leave out xorg.conf as much as possible, as things like
> keyboard/mouse management are really, really complicated when HAL/evdev are
> available. I just stuck to changing display resolution, and focused on using
> HAL/evdev for input config.
> 
> Of course, now that X upstream has confirmed they'll be moving away from HAL
> (and evdev?) in upcoming releases, I'll probably have to rewrite the doc yet
> again. So who knows what that'll look like.

A few things I can tell you so far on this topic :

 - HAL is indeed being phased out (it won't be removed though)
 - Xorg will now use libudev instead of libhal to get a list of input hardware
 - xf86-input-evdev will still be the "one-stop Linux input driver" that works on pretty much all devices (keyboards and mice, but also touchscreens, joysticks, tablets, etc)
 - Xorg will be able to pick up configuration options from udev, through custom udev rules
 - Xorg will also include a xorg.conf.d/ configuration directory where users and packagers will be able to split xorg.conf into separate but mergeable bits using matching options (kind of like HAL's fdi <merge> option)

So upstream is indeed going back to xorg.conf, but it'll be 10x more flexible than what we've had for the past 20 years. Overall, it won't require _that_ much change to the guide since the procedure is very similar.

> In the mean time, this bug is FIXED as far as I can tell. Please do review the
> new guide:

Ah ha, I already have some suggestions and comments, but maybe I can provide a patch :

 - the 4th paragraph (about the XFree86/Xorg fork) is useless info these days :)
 - I think there's a little confusion about input. The X driver is called xf86-input-evdev and it uses the "evdev" (which is an interface to the kernel, like v4l for example)
 - By default, Xorg uses xf86-input-evdev if built with USE=hal, or -keyboard and -mouse if built with -hal.
 - Not all drivers have an entry in VIDEO_CARDS or INPUT_DEVICE. Users can install whatever driver they want without touching those 2 variables.
 - Mentioning fglrx for ATI users is probably not such a good idea. Only the very latest chips still work with it...
 - (we should probably have a bigger hardware list somewhere...)
 - The note about xorg-x11 is useless as well, it's just a meta we use to do bumps, most users will never ever need all the crap it pulls in :)
 - Users shouldn't edit fdi files from /usr/share/hal (which you've correctly written) but they should copy them either. Some of those files are just too big. Users should just copy sample fdi files from /usr/share/doc/hal and adapt them instead. If needs be we can add more samples. (Moar! :) )
 - Since HAL is on the way out (Gnome 2.28 barely uses it anymore and 2.30 won't use it at all), I suggest keeping the HAL stuff to a minimum : configuring X input option and nothing more.
 - "Xorg -configure" isn't a good idea and has been the cause of many headaches with recent servers, I think it's best to give users a nearly empty xorg.conf istead (Ubuntu does something like this IIRC, I'll look it up)
 - Users should probably use "/etc/init.d/xdm restart" instead of "startx" to test whether their X works, as xinit now doesn't pull in twm and xterm anymore, there's a good chance users won't see much.
 - Don't mention HorizSync and VertRefresh, now X uses DCC to see which resolutions are available. Monitors that still require those options are now very rare. Users should look at Xorg.0.log to see which resolutions Xorg detected and set the "Modes" option accordingly.
 - The keyboard section should definitely be merged with the earlier HAL section

Hum, so that's longer than I thought, but the current guide _is_ a huge improvement over the previous one. We should probably discuss these things on IRC so that we can gauge it all.

Cheers :)
Comment 23 Paulo Neves 2010-03-16 15:07:36 UTC
(In reply to comment #22)
Just a comment on X -config
When i first got X up i wanted to just test X and startx failed. So i followed Code Listing 3.5 to check with a custom X configuration file. The problem was that as i didn't have any window manager installed only a black screen appeared and i was wrongfully led to believe something was failing. I later read on http://forums.gentoo.org/viewtopic-t-818231.html?sid=642980c8701309945111ba2461d46d91 that i needed the -retro argument for the X server to show the black white/stipple pattern meaning that everything was ok with X.
In conclusion, to be sure that the X server is well configured i suggest the insertion in the guide of the -retro flag on Code Listing 3.5

Paulo Neves
Comment 24 nm (RETIRED) gentoo-dev 2010-03-16 20:09:20 UTC
(In reply to comment #23)
Fixed. The -retro flag is a good idea.

Next time, though, please open a new bug, instead of commenting on an old closed bug. This way you can be sure that your request will receive attention.