Copyright © 2008 Manolis Kiagias
FreeBSD is a registered trademark of the FreeBSD Foundation.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol.
The Linux world has been overwhelmed lately by what seems to be the latest fashion: 3D Desktop effects. While their usefulness is rather heavily debated, the wow factor behind the composited desktop holds quite well. Several different programs have emerged, like Compiz, Beryl, and the latest Compiz Fusion. You do not need to miss these effects when using FreeBSD. These instructions will help you install and configure your system for the latest 3D desktop experience using Compiz Fusion and nVidia drivers (if applicable).
While installing Compiz Fusion from the Ports Collection is a rather trivial task, configuring it requires a few more steps that are not described in the port's documentation. This article will help you configure your Xorg server for composite operation, setup your nVidia card, and finally guide you to the final steps for executing the compiz program itself.
After reading this article, you will know:
How to setup the latest nVidia driver (if required) for your system.
How to setup your xorg.conf file for desktop composition.
How to install and configure Compiz Fusion using the Ports Collection.
How to troubleshoot common problems associated with desktop effects.
Desktop effects can cause quite a load on your graphics card. If you are using an nVidia-based graphics card, you will need to install and configure the proprietary FreeBSD driver that is suitable for your system. If you are using another card, that you know can handle desktop effects, you may skip this section and continue with the xorg.conf configuration.
There are various versions of the nVidia drivers in the Ports Collection. The correct one to use depends on the actual model (and age) of your graphics card:
The latest versions of nVidia cards are supported by the x11/nvidia-driver port.
nVidia cards like the GeForce 2MX/3/4 series are supported by the 96XX series of drivers, available in the x11/nvidia-driver-96xx port.
Even older cards, like GeForce and RIVA TNT are supported by the 71XX series of drivers, available in the x11/nvidia-driver-71xx port.
In fact, nVidia provides detailed information on which card is supported by which driver. This information is available directly on their web site: http://www.nvidia.com/object/IO_32667.html.
Having determined the correct driver to use for your card, installation is as simple as installing any other port.
Note: Make sure to update your ports tree using your favorite method (like csup, CVSup or portsnap) before you install any application from the ports system. Graphics drivers and the desktop effects programs are under heavy development, and are updated regularly.
For example, to install the latest driver:
# cd /usr/ports/x11/nvidia-driver # make install clean
The driver will create a kernel module, which should be loaded at system startup. You will need to add the following line to the /boot/loader.conf file:
nvidia_load="YES"
Note: You may attempt to immediately load the kernel module into the running kernel by issuing a command like kldload nvidia, however it has been noted that the latest versions of Xorg will not function properly if the driver is not loaded at boot time. After editing /boot/loader.conf, a reboot is recommended.
With the kernel module loaded, you normally only need to change a single line in your xorg.conf file to enable the proprietary driver:
Find the following line in /etc/X11/xorg.conf:
Driver "nv"
and change it to:
Driver "nvidia"
Start your GUI as usual, and you should be greeted by the nVidia splash. Everything should work as usual. Note, that at this point you have only set up Xorg to use the nVidia driver, but further configuration is needed before you can actually use 3D desktop effects. This is described in the following sections.
Note: Although not strictly necessary, you may also wish to install x11/nvidia-xconfig and x11/nvidia-settings ports. The former can assist you in writing settings to /etc/X11/xorg.conf from the command line, and the latter will allow you to modify screen settings from a GUI while running the Xorg system.
Before you install and run Compiz Fusion, you need to add a few settings to /etc/X11/xorg.conf:
Add the following section to enable composite effects:
Section "Extensions" Option "Composite" "Enable" EndSection
Locate the “Screen” section which should look similar to the one below:
Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" ...
and add the following two lines (after “Monitor” will do):
DefaultDepth 24 Option "AddARGBGLXVisuals" "True"
Locate the “Subsection” that refers to the screen resolution that you wish to use. For example, if you wish to use 1280x1024, locate the section that follows. If the desired resolution does not appear in any subsection, you may add the relevant entry by hand:
SubSection "Display" Viewport 0 0 Modes "1280x1024" EndSubSection
A color depth of 24 bits is needed for desktop composition, change the above subsection to:
SubSection "Display" Viewport 0 0 Depth 24 Modes "1280x1024" EndSubSection
Finally, confirm that the “glx” and “extmod” modules are loaded in the “Module” section:
Section "Module" Load "extmod" Load "glx" ...
Note: If you installed the x11/nvidia-xconfig port, you should be able to perform most of the above settings by entering the following commands (as root):
# nvidia-xconfig --add-argb-glx-visuals # nvidia-xconfig --composite # nvidia-xconfig --depth=24You may wish to run nvidia-xconfig -A | more to see a list of all the options offered by the above program.
Installing Compiz Fusion is as simple as any other port:
# cd /usr/ports/x11-wm/compiz-fusion # make install clean
Make sure to select the “EXTRA” plugins and the “EMERALD” window decorator from the options dialog that appears. If you are using GNOME, or already have support for gconf in your system, you may also wish to select “gconf support”. In this way, your effect settings will be integrated with the other desktop settings, and will be viewable via gconf-editor. Compiz Fusion can however save its settings to flat files, if such an integration is not wanted. In this case, a .compizconfig directory will be created inside your home directory.
When the installation is finished, start your graphic desktop and at a terminal, enter the following commands (as a normal user):
% compiz --replace --sm-disable --ignore-desktop-hints ccp & % emerald --replace &
Your screen will flicker for a few seconds, as your window manager (e.g. Metacity if you are using GNOME) is replaced by Compiz Fusion. Emerald takes care of the window decorations (i.e. close, minimize, maximize buttons, title bars and so on).
You may convert this to a trivial script and have it run at startup automatically (e.g. by adding to “Sessions” in a GNOME desktop):
#! /bin/sh compiz --replace --sm-disable --ignore-desktop-hints ccp & emerald --replace &
Save this in your home directory as, for example, start-compiz and make it executable:
% chmod +x ~/start-compiz
Then use the GUI to add it to Startup Programs (located in System, Preferences, Sessions on a GNOME desktop).
To actually select all the desired effects and their settings, execute (again as a normal user) the Compiz Config Settings Manager:
% ccsm
Note: In GNOME, this can also be found in the System, Preferences menu.
If you have selected “gconf support” during the build, you will also be able to view these settings using gconf-editor under apps/compiz.
The following section covers frequently asked questions regarding problems when running Compiz Fusion.
5.1. I have installed Compiz Fusion, and after running the commands you mention, my windows are left without title bars and buttons. What is wrong?
You are probably missing a setting in /etc/X11/xorg.conf. Review this file carefully and check especially the DefaultDepth and AddARGBGLXVisuals directives.
5.2. When I run the command to start Compiz Fusion, the X server crashes and I am back at the console. What is wrong?
If you check your /var/log/Xorg.0.log file, you will probably find error messages during the X startup. The most common would be:
(EE) NVIDIA(0): Failed to initialize the GLX module; please check in your X (EE) NVIDIA(0): log file that the GLX module has been loaded in your X (EE) NVIDIA(0): server, and that the module is the NVIDIA GLX module. If (EE) NVIDIA(0): you continue to encounter problems, Please try (EE) NVIDIA(0): reinstalling the NVIDIA driver.
This is usually the case when you upgrade Xorg. You will need to reinstall the x11/nvidia-driver port so glx is built again.