Migrating to Modular X HOWTO

1.  Introduction

Why modular?

You may be wondering, why in the world did one nice, easy xorg-x11 package turn into almost 300 separate ones? And you'd certainly be justified in this. =) It's not something Gentoo is doing independently of upstream X.Org; they're splitting up all the packages into separate releases, and we're just following along.

The reasoning behind the split and changing build system is at least threefold:

• X is too difficult to get into for new devs, so thus the move to autotools, a system more people are comfortable with if not happy with.
• Along with that move, splitting out the source is possible with autotools, and this also makes it more developer-friendly.
• Things have been unnecessarily tied together in the past, and this has made getting bugfixes out often impossible. If they were able to get out fixes, it required rebuilding all of XOrg. For example, a bug in the ati driver would either need to wait 6 months until the next release, or you'd have to rebuild your fonts to get it, for absolutely no reason.

2.  Migrating to Modular X

Introduction

To keep old packages from getting in the way, we're going to clean out all the old xorg-x11 cruft before installing modular X. This isn't absolutely crucial, but it will help ensure a smooth migration.

First step: Clean out your old X

Create a backup copy of the monolithic xorg-x11 in case modular X works poorly for you, and you want to revert to 6.x. You may wish to install a text-mode browser such as links or lynx to view this howto with when X is not available.

# emerge gentoolkit
# quickpkg xorg-x11

Get rid of the monolithic installation. To avoid the possibility of crashes or hard locking your system, you may want to quit any running X sessions before uninstalling X.Org.

# emerge -Ca xorg-x11 virtual/x11

If your /usr/X11R6 isn't a symlink to /usr, delete it and start from scratch. But first, save a list of all the packages installing there. The gentoolkit package provides equery.

# if [[ ! -L /usr/X11R6 ]]; \
    then equery belongs /usr/X11R6 > ~/usr-x11r6-packages \
    && rm -rf /usr/X11R6; fi

Finally, if /usr/lib/X11/xkb (/usr/lib64/X11/xkb for 64-bit users) exists, it should be removed. This is a requirement for the xkeyboard-config package to install.

Second step: Installing modular X

For direct rendering, check that the dri USE flag is active. It should be on by default.

Next, decide which drivers you need to install. This will vary depending on your input and video hardware. If you already have a working /etc/X11/xorg.conf, then just run this command to get an idea of what drivers you need:

# grep Driver /etc/X11/xorg.conf
        Driver      "kbd"
        Driver      "mouse"
        Driver      "radeon"

# emerge --verbose --pretend xorg-x11
[ebuild   R   ] x11-base/xorg-x11-7.0-r1  USE="-xprint" INPUT_DEVICES="keyboard
mouse -acecad -aiptek -calcomp -citron -digitaledge -dmc -dynapro -elo2300
-elographics -evdev -fpit -hyperpen -jamstudio -joystick -magellan -magictouch
-microtouch -mutouch -palmax -penmount -spaceorb -summa -synaptics% -tek4957
-ur98 -vmmouse -void" VIDEO_CARDS="i128 mga radeon savage -apm -ark -chips
-cirrus -cyrix -dummy -fbdev -fglrx% -glint -i740 -i810 -imstt -mach64 -neomagic
-newport -nsc -nv -nvidia% -r128 -rendition -s3 -s3virge -siliconmotion -sis
-sisusb -sunbw2 -suncg14 -suncg3 -suncg6 -sunffb -sunleo -suntcx -tdfx -tga
-trident -tseng -v4l -vesa -vga -via -vmware -voodoo" 0 kB

Set INPUT_DEVICES and VIDEO_CARDS to what you need in /etc/make.conf. The minimal setting for the above example would be INPUT_DEVICES="keyboard mouse" VIDEO_CARDS="radeon". If you don't set one or the other variable, xorg-x11 will pull in all possible drivers of that type. For backup drivers, you may also want to add vesa and fbdev to VIDEO_CARDS.

Now, install the metabuild. This will install the server and popular applications, giving you a working desktop implementation of X:

# emerge xorg-x11
# etc-update
# revdep-rebuild
# [[ -e ~/usr-x11r6-packages ]] && emerge 
$(<~/usr-x11r6-packages)

This install tries to be rather minimal, so things like xcursor-themes are not installed by default. In that particular example, you would want xcursor-themes if you changed your cursor setting to whiteglass, redglass or handhelds. If you use the gentoo, gentoo-blue or gentoo-silver cursor themes, install gentoo-xcursors.

3.  Caveats/Common Problems

'emerge -u world' wants to install xorg-x11 6.x or virtual/x11

This is because the tree isn't fixed for modular dependencies yet. You can help the porting effort by reading the Porting to Modular X HOWTO and filing bugs with patches to the individual package maintainers. The maintainers will be listed in metadata.xml in the same directory as the package and the herdstat package will speed up querying for them.

Particularly if you are running modular X on an otherwise stable system, you may run into issues with this. Many packages only work with modular X in their ~arch versions, so you may need to add additional packages to /etc/portage/package.keywords.

What happened to all the USE flags?

Many USE flags in the xorg-x11-6.8 series vanished or moved in 7.0. Some new USE flags appeared. Here's why:

What happened to all the config files?

In Gentoo's X.Org 6.8 package, all of the configuration files and scripts were stored in /etc/X11. In modular X.Org, the upstream locations for these files have been changed -- that is, configuration files are still in /etc/X11, but scripts and default configurations are now in /usr/lib/X11 (or /usr/lib64/X11) and /usr/share/X11.

Because of configuration protection (CONFIG_PROTECT), you will probably have all of your old configuration files from X.Org 6.8 still in /etc/X11, taking up space and looking useful.

Since these new directories are not in CONFIG_PROTECT, it is important that any changes to default configurations be done by copying the relevant files to /etc/X11 and updating the appropriate configuration file there. Alternatively, but not recommended, the new location can be config-protected. Below are some examples:

First, copy the Xsetup_0 file to /etc so it is config-protected.

# cp -a /usr/lib/X11/xdm/Xsetup_0 /etc/X11/xdm/

Edit the file and customize as you wish.


Then, edit xdm-config to update the path to this file.

# nano /etc/X11/xdm/xdm-config

Change the following from this:

    ! The following three resources set up display :0 as the console.
    DisplayManager._0.setup:        /usr/lib/X11/xdm/Xsetup_0
    DisplayManager._0.startup:      /usr/lib/X11/xdm/GiveConsole
    DisplayManager._0.reset:        /usr/lib/X11/xdm/TakeConsole

...to this:

    ! The following three resources set up display :0 as the console.
    DisplayManager._0.setup:        /etc/X11/xdm/Xsetup_0
    DisplayManager._0.startup:      /usr/lib/X11/xdm/GiveConsole
    DisplayManager._0.reset:        /usr/lib/X11/xdm/TakeConsole

In this example submitted by Joe Womack, we'll customize some xterm settings. This can either be done globally or on a per-user basis.

Similar to above, create a copy of the file in /etc so that it is
config-protected:

# cp -a /usr/share/X11/app-defaults/XTerm-color /etc/X11/app-defaults/

Customize the file as you wish.  Now, we need to tell Xt where to find the
files through XFILESEARCHPATH.  Put it in a file under /etc/env.d:

# echo '# This applies the customizations system-wide.' >> /etc/env.d/10xpaths
# echo 'XFILESEARCHPATH=/etc/X11/%T/%N:/usr/share/X11/%T/%N' >> /etc/env.d/10xpaths

There are two ways to do this:
1) Setup a per-user app-defaults directory:
# echo '# This applies user customizations in $HOME/app-defaults.' >> /etc/env.d/10xpaths 
# echo 'XUSERFILESEARCHPATH=$HOME/%T/%N' >> /etc/env.d/10xpaths


2) Create a .Xdefaults or .Xresources and copy the settings you want to
change. This example changes all XTerms to have an orange cursor, run as a
login shell, have a scroll bar decoration, and a 1000 line scroll back buffer:

# echo '! Xterm defaults'               >> .Xresources
# echo 'XTerm*CursorColor:      orange' >> .Xresources
# echo 'XTerm*loginShell:       true'   >> .Xresources
# echo 'XTerm*scrollBar:        true'   >> .Xresources
# echo 'XTerm*saveLines:        1000'   >> .Xresources


For these setting to take effect, the either re-start X or run:

# xrdb -merge $HOME/.Xresources

Driver problems

I've had reports that:

• vesa locks up box with a Matrox card
• vga produces a very weird-looking screen, divided into quarters

Getting 3D acceleration working again

To get some debugging info to help in getting direct rendering working:

# grep -e EE -e WW /var/log/Xorg.0.log
# LIBGL_DEBUG=verbose glxinfo

Mouse protocol autodetection

If you have "Protocol" "auto" set in xorg.conf for your mouse, it may not work. You may need to specify "Protocol" "ExplorerPS/2" or "IMPS/2" for your wheel to work.

I'm getting error messages about libbitmap or libpcidata not found

Make sure no ModulePath entry exists in /etc/X11/xorg.conf.

gdm/kdm don't work

If you installed modular X on a fresh Gentoo installation, you may not have a /usr/X11R6 -> /usr symlink. The x11-base/xorg-x11 package will ensure that the symlink exists during the emerge process.

You can help get things out of /usr/X11R6 by fixing the packages that install there and filing bugs. Also, remember to reinstall these packages.

# cat ~/usr-x11r6-packages
# emerge --pretend $(< ~/usr-x11r6-packages )

XKB doesn't work, I can't switch VTs, etc

• Many XKB layouts have moved around, consolidated or disappeared. Take a look in /usr/share/X11/xkb/symbols/ to see what happened to your old XkbLayout settings in xorg.conf. For example, to replace the old "us_intl" layout, you would put "XkbLayout" "latin", "XkbOptions" "lv3:ralt_switch". To replace the old "sk_qwerty" layout, you would put "XkbLayout" "sk", "XkbVariant" "qwerty". For a more advanced example, perhaps you have "XkbLayout" "us,sk_qwerty". To get that working, the new setting would be "XkbLayout" "us,sk", and the tricky part is in the comma here: "XkbVariant" ",qwerty", because you want the variant to apply to your second layout.

Check /var/log/Xorg.0.log for this message:
(WW) Couldn't load XKB keymap, falling back to pre-XKB keymap
If you do not have that error, your XKB works already.
# grep Xkb /etc/X11/xorg.conf
        Option "XkbModel"  "logibik"
        Option "XkbLayout"  "dvorak"
        Option "XkbOptions" "ctrl:swapcaps"
First, see what changed with your layout. This is in the symbols/pc 
directory.
# cd /usr/share/X11/xkb/symbols/
If you have xkbdata instead of xkeyboard-config installed, change to 
the pc/ subdirectory.
# ls *dvorak*
OK, nothing showed up.
Lots of old layouts moved into their country-coded keymaps.
# ls *us*
us
Now, we check for an xkb_symbols variant called dvorak.
# grep xkb_symbols.*dvorak us
xkb_symbols "dvorak" {
That means in xorg.conf, we need Option "XkbLayout" "us"
and Option "XkbVariant" "dvorak".

But when we try to test this with setxkbmap, we still get an 
error
# setxkbmap -model logibik -layout us -variant dvorak -option 
"ctrl:swapcaps"
Maybe the model changed, too.
# cd /usr/share/X11/xkb/rules/
# grep logibik xorg.lst
No output from that, so that model is gone. How about similar 
ones?
# grep logi* xorg.lst
  logiaccess      Logitech Access Keyboard
  logicdit        Logitech Cordless Desktop iTouch
  logicdp         Logitech Cordless Desktop Pro
  logicdpa        Logitech Cordless Desktop Pro (alternate option)
  logicdpa2       Logitech Cordless Desktop Pro (alternate option2)
  logicdo         Logitech Cordless Desktop Optical
  logicfn         Logitech Cordless Freedom/Desktop Navigator
  logicdn         Logitech Cordless Desktop Navigator
  logidak         Logitech Deluxe Access Keyboard
  logiitc         Logitech iTouch Cordless Keyboard (model Y-RB6)
  logiik          Logitech Internet Keyboard
  logiitc         Logitech iTouch Cordless Keyboard (model Y-RB6)
  logiik          Logitech Internet Keyboard
  logiink         Logitech Internet Navigator Keyboard
  logiultrax      Logitech Ultra-X Keyboard
Great! The "logiik" model looks similar, so test it out with 
setxkbmap.
# setxkbmap -model logiik -layout us -variant dvorak -option 
"ctrl:swapcaps"
It worked, so change the XkbModel entry to that.
After that, everything works

Other Issues

• The x11-base/xorg-x11 package now filters all ModulePath and RgbPath lines from your /etc/X11/xorg.conf, as both of these paths have changed since previous versions. Make sure you run etc-update to finalize these changes. If for some reason they weren't filtered, remove them yourself.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.