Gentoo Logo

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


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.

Code Listing 2.1: Backing up the old xorg-x11

# 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.

Code Listing 2.2: Unmerging the monolitic installation

# 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.

Code Listing 2.3: Make a package list

# 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:

Code Listing 2.4: Finding what drivers you need

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

Code Listing 2.5: Checking available drivers

# 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:

Code Listing 2.6: Installing the modular metabuild

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

Note: If you really want a minimal installation, just install xorg-server. This will pull in only what you need to start an X server.

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.

Note: With modular installed, external drivers such as nvidia-glx and wacom as well as some vnc apps may not work if they install things to /usr/lib/modules instead of /usr/lib/xorg/modules. Many of these will have modular X detection added to the installation process and thus will need to be re-merged after modular X install. In addition, many external drivers have a dlloader USE flag that you must enable and then rebuild the drivers.

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:

USE flag What happens in 7.0?
3dfx In 7.0, pulls in glide-v3 from the xorg-x11 metabuild
3dnow, mmx, sse Enabled by default at build time, because there are runtime checks
bitmap-fonts, truetype-fonts, type1-fonts The xorg-x11 metabuild pulls in a small selection of the most used or required fonts. You may additionally install any others in media-fonts/.
cjk USE=nls on font-misc-misc and font-sony-misc to get Japanese JISX0201 fonts. More are in font-jis-misc. Chinese fonts are in font-isas-misc. Korean fonts are in font-daewoo-misc.
dlloader 7.0 uses the dlloader by default, and the elfloader doesn't work.
doc Moved to app-doc/xorg-docs
dmx Built in xorg-server unless USE=minimal
font-server You may manually install xfs.
ipv6 Moved to individual packages using it. Set globally if you want it.
minimal To get the same effect, install just xorg-server rather than xorg-x11. USE=minimal on xorg-server to avoid building Xdmx, Xvfb and Xnest. If you require something more minimal, look into x11-base/kdrive.
nls In 7.0, USE=nls installs all non-ISO8859-1 versions of fonts.
nocxx Not yet an equivalent in 7.0
opengl Changed names to "dri," which enables direct rendering in xorg-server and many drivers. Whether USE=dri is on or off, you should still get software 3D via Mesa.
pam Moved to individual packages using it, such as xorg-server and xdm
sdk 7.0 must install the SDK as a consequence of modularization.
static Mostly doesn't make much sense to try building a static server in a modular world, because the driver can't be built into it.
xprint On metabuild, pulls in libXp. On other applications, builds in xprint support. Most people will not want to enable this.
xv No longer optional because it doesn't save much size and causes other issues with some packages expecting it.

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:

Code Listing 3.1: Customizing the initialization of XDM

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 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

Note: On 64-bit multilib systems with the no-symlink profile, you need to change lib to lib64.

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.

Code Listing 3.2: Customizing app-defaults/XTerm-color globally

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

# 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

Code Listing 3.3: Customizing app-defaults/XTerm-color locally

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

Note: See for more details on setting XFILESEARCHPATH and XUSERFILESEARCHPATH. See for more details on .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:

Code Listing 3.4: Getting some debug info

# 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.

Code Listing 3.5: Packages that install to /usr/X11R6

# 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.

Code Listing 3.6: Tracking down XKB changes

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 
# 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*
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 
# setxkbmap -model logibik -layout us -variant dvorak -option 
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 
# 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 -model logiik -layout us -variant dvorak -option 
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.


Page updated November 5, 2006

Summary: This guide shows you how to migrate to modular X.Org.

Donnie Berkholz

Joshua Baergen

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.