Xorg/Guide

Xorg is the X Window server which allows users to have a graphical environment at their fingertips. This guide Article description::explains what Xorg is, how to install it, and the various configuration options.

Graphical vs command-line
An average user may be frightened at the thought of having to type in commands at a command-line interface (CLI). Why wouldn't they be able to point-and-click their way through the freedom provided by Gentoo (and Linux in general)? Well, of course they can!

Gentoo offers a wide variety of flashy graphical interfaces such as window managers and desktop environments which can be installed on top of an existing installation.

One of the biggest surprises users who are new to Linux come across: graphical user interfaces are nothing more than an application (or in some cases a suite of applications) which are run on a system. It is not part of the Linux kernel or any other internals of the system. That said, GUIs are powerful tools that unlock the graphical abilities of a workstation.

As standards are important, a standard for drawing and moving windows on a screen, interacting with the user through mouse, keyboard, and other basic, yet important aspects has been created and named the X Window System, commonly abbreviated as X11 or just X. It is used on Unix, Linux, and Unix-like operating systems throughout the world.

The application that provides Linux users with the ability to run graphical user interfaces and that uses the X11 standard is Xorg-X11, a fork of the XFree86 project. XFree86 has decided to use a license that might not be compatible with the GPL license; the use of Xorg is therefore recommended. XFree86 packages are no longer provided through the Gentoo repository.

The X.org project
The X.org project created and maintains a freely redistributable, open-source implementation of the X11 system. It is an open source X11-based desktop infrastructure.

Xorg provides an interface between your hardware and the graphical software you want to run. Besides that, Xorg is also fully network-aware, meaning you are able to run an application on one system while viewing it on a different one.

USE flags
Portage knows the  USE flag for enabling support for X in other packages (default in all desktop profiles). Make sure this USE flag is added to the USE flag list to ensure X compatibility system wide:

Before you can install Xorg, you need to prepare your system for it. First, we'll set up the kernel to support input devices and video cards. Then we'll prepare so that the right drivers and Xorg packages are built and installed.

Input driver support
Support for Event interface ( CONFIG_INPUT_EVDEV ) needs to be activated by making a change to the kernel configuration. Read the Kernel Configuration Guide if you don't know how to setup your kernel.

Kernel modesetting
Modern open source video drivers rely on kernel mode setting (KMS). KMS provides an improved graphical boot with less flickering, faster user switching, a built-in framebuffer console, seamless switching from the console to Xorg, and other features.

Verify legacy framebuffer drivers have been disabled
First prepare the kernel for KMS. This step regardless of which Xorg video driver will be used:

Next configure the kernel to use the proper KMS driver for the video card. Intel, NVIDIA, and AMD/ATI are the most common cards, so follow code listing for each card below.

Intel
For Intel cards see the kernel section of the Intel article.

NVIDIA
For NVIDIA cards, two driver options are available. For a full open source system, an open source driver entitled Nouveau is suggested. The second option is the closed source NVIDIA driver, which is officially supported by NVIDIA. This article recommends the Nouveau driver, however be aware not all functionally for certain cards may be supported using the open source driver.

In addition to the kernel driver, certain cards require closed source firmware to be built-in to the Linux kernel. Depending on the selected driver, readers should visit each respective article to check to see if firmware (from the is necessary for their specific card.

AMD/ATI
For newer AMD/ATI cards (RadeonHD 2000 and up), emerge (the package includes firmware for radeon and amdgpu drivers). Once one of these packages has been installed, make the Radeon driver a module in the kernel or, optionally, configure the kernel as detailed in the firmware section of the Radeon article or, for newer AMD graphics cards (GCN1.1+), the firmware section of the AMDGPU article.

Older cards:

Newer cards:

Exit the kernel configuration, rebuild the kernel, and reboot.

Now that KMS has been set up, continue preparing in the next section.

make.conf
Now that the kernel is prepared, two important variables in the file must be configured before installing Xorg.

The first variable is VIDEO_CARDS. This is used to set the video drivers that you intend to use and is usually based on the kind of video card you have. The most common settings are  for NVIDIA cards or   for ATI cards. Both have actively developed, well-supported open-source drivers. If you have a newer AMD video card (Southern Islands and up), you may also try the new open-source  driver. See the AMDGPU article for more details.

The  driver may be used for desktops or laptops with common Intel integrated graphics chipsets. See Intel X Drivers for more details.

The second variable is INPUT_DEVICES  and is used to determine which drivers are to be built for input devices.

make.defaults has Libinput as the default input device driver.

To check what is presently set, run:

In case alternative input devices, such as a Synaptics touchpad for a laptop are needed, be sure to add them to INPUT_DEVICES the file:

If the suggested settings does not work emerge the package (see the step below). Check all the options available and choose those which apply to the system. This example is for a system with a keyboard, mouse, Synaptics touchpad, and a Radeon video card.

After setting all the necessary variables Xorg can be installed:

When the installation is finished, some environment variables will need to re-initialized before continuing. Source the profile with this command:

Configuration
The X server is designed to work out-of-the-box, with no need to manually edit Xorg's configuration files. It should detect and configure devices such as displays, keyboards, and mice.

Try using startx without editing any configuration files. If Xorg will not start, or there is some other problem, then manual configuration of Xorg will be needed. This is explained in the following section.

The directory
Most of the configuration files for Xorg are stored in. Each file is given a unique name and ends in. The file names in Xorg's configuration directory will be read in alpha numeric order. For example, will be read before ;  will be read before, and so on. The files in this directory are not required to be numbered, but doing so will help to keep them organized. Organization is helpful when debugging faulty configuration files.

Using startx
Try to start up the X server. is a script (it's installed by ) that executes an X session; that is, it starts the X server and some graphical applications on top of it. It decides which applications to run using the following logic:


 * If a file named exists in the home directory, it will execute the commands listed there.


 * Otherwise, it will read the value of the XSESSION variable from the file and execute the relevant session accordingly. Values for XSESSION are available in . To set a system wide default session run:




 * This will create the file and set the default X session to Xfce. Remember to run  after making changes to.

If no window manager has been installed a solid black screen will appear. Since this can also be a sign that something is wrong, the and  packages can be installed only to test X.

Once the programs are installed, run again. A few windows should appear, making it easy to verify the X server is working correctly. Once satisfied with the results, unmerge and  if installed in the step above to remove the testing packages. They will not be needed to setup a proper desktop environment.

The session (program to start) could also be given as an argument to :

You can also pass X11 server options, by preceding them with a double dash:

Setting the screen resolution
If the screen resolution looks to be wrong, you will need to check two sections in your configuration. First of all, you have the Screen section which lists the resolutions that your X server will run at. This section might not list any resolutions at all. If this is the case, Xorg will estimate the resolutions based on the information in the second section, Monitor.

Now let us change the resolution. In the next example from we add the   line so that our X server starts at 1440x900 by default. The  in the   section must match the name of your monitor, which can be obtained by running. Install  just long enough to get this information. The argument after the monitor name (in the  section) must match the   in the   section.

Run X to discover it uses the desired resolution.

Multiple monitors
More than one monitor in can be established in. Give each monitor a unique identifier, then list its physical position, such as "RightOf" or "Above" another monitor. The following example shows how to configure a DVI and a VGA monitor, with the VGA monitor as the right-hand screen:

Configuring the keyboard
To setup X to use an international keyboard create the appropriate config file in. This example features a Czech keyboard layout:

For methods of switching the keyboard layout see the Keyboard layout switching article.

The "terminate" command lets users kill the X session by using the ++ key combination. This will, however, make X exit disgracefully -- something that users might want to avoid. It can be useful when programs have frozen the display entirely, or when configuring and tweaking the Xorg environment. Be careful when killing the desktop with this key combination - most programs really do not like it when they are ended this way. Some, if not all, of the information that has not been written to the disk (information stored in "open documents") will be lost.

For more information about  and , consult  and.

Finishing up
Run and be happy about the result. Congratulations, you now (hopefully) have a working Xorg! The next step is to install a useful window manager or desktop environment such as KDE, GNOME, or Xfce. Information on installing these desktop environments can be found here on the wiki.

Creating and editing config files
and provide quick yet complete references about the syntax used by these configuration files. Be sure to have them open on a terminal when editing Xorg configuration files!

Example configurations can be found at.

There are also many online resources on editing config files in. Only a few are listed here; use a favorite search engine to find more.

Other resources
More information about installing and configuring various graphical desktop environments and applications can be found in the section of our documentation.

When upgrading to xorg-server 1.9 or higher, be sure to read the migration guide.

X.org provides many FAQs on their website, in addition to their other documentation.