path: root/en_US.ISO8859-1/articles/compiz-fusion/article.sgml

<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/sgml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/sgml/entities.ent">
%entities;
]>

<article lang="en">
  <articleinfo>
    <title>Installing and using Compiz&nbsp;Fusion</title>

    <author>
      <firstname>Manolis</firstname>
      <surname>Kiagias</surname>
      <affiliation>
	<address><email>manolis@FreeBSD.org</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>2008</year>
      <holder role="mailto:manolis@FreeBSD.org">Manolis Kiagias</holder>
    </copyright>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>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
	<ulink url="http://compiz.org/"><application>Compiz</application></ulink>,
	<ulink url="http://www.beryl-project.org/"><application>Beryl</application></ulink>,
	and the latest <ulink
	  url="http://www.compiz-fusion.org/"><application>Compiz&nbsp;Fusion</application></ulink>.
	You do not need to miss these effects when using &os;.  These
	instructions will help you install and configure your system for the
	latest 3D desktop experience using
	<application>Compiz Fusion</application> and nVidia drivers
	(if applicable).</para>
    </abstract>
  </articleinfo>

  <sect1 id="introduction">
    <title>Introduction</title>

    <para>While installing <application>Compiz&nbsp;Fusion</application> from
      the Ports&nbsp;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
      <application>&xorg;</application> server for composite operation,
      setup your nVidia card, and finally guide you to the final steps for
      executing the <command>compiz</command> program itself.</para>

    <para>After reading this article, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to setup the latest nVidia driver (if required) for your
	  system.</para>
      </listitem>

      <listitem>
	<para>How to setup your <filename>xorg.conf</filename> file for
	  desktop composition.</para>
      </listitem>

      <listitem>
	<para>How to install and configure
	  <application>Compiz&nbsp;Fusion</application> using the
	  Ports&nbsp;Collection.</para>
      </listitem>

      <listitem>
	<para>How to troubleshoot common problems associated with
	  desktop effects.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="nvidia-setup">
    <title>Setting up the &os; nVidia driver</title>

    <para>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 &os; 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
      <filename>xorg.conf</filename> configuration.</para>

    <sect2 id="determine-driver">
      <title>Determining the correct driver to use</title>

      <para>There are various versions of the nVidia drivers in the
	Ports&nbsp;Collection.  The correct one to use depends on the actual
	model (and age) of your graphics card:</para>

      <itemizedlist>
	<listitem>
	  <para>The latest versions of nVidia cards are supported by the
	    <filename role="package">x11/nvidia-driver</filename> port.</para>
	</listitem>

	<listitem>
	  <para>nVidia cards like the GeForce 2MX/3/4 series are supported by
	    the 96<replaceable>XX</replaceable> series of drivers, available
	    in the <filename role="package">x11/nvidia-driver-96xx</filename>
	    port.</para>
	</listitem>

	<listitem>
	  <para>Even older cards, like GeForce and RIVA TNT are supported
	    by the 71<replaceable>XX</replaceable> series of drivers,
	    available in the
	    <filename role="package">x11/nvidia-driver-71xx</filename>
	    port.</para>
	</listitem>
      </itemizedlist>

      <para>In fact, nVidia provides detailed information on which card is
	supported by which driver.  This information is available directly
	on their web site: <ulink
	  url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para>
    </sect2>

    <sect2 id="install-driver">
      <title>Installing the nVidia driver</title>

      <para>Having determined the correct driver to use for your card,
	installation is as simple as installing any other port.</para>

      <note>
	<para>Make sure to update your ports tree using your favorite method
	  (like <application>csup</application>,
	  <application>CVSup</application> or
	  <application>portsnap</application>) before you install any
	  application from the ports system.  Graphics drivers and the
	  desktop effects programs are under heavy development, and are
	  updated regularly.</para>
      </note>

      <para>For example, to install the latest driver:</para>

      <screen>&prompt.root; <userinput>cd /usr/ports/x11/nvidia-driver</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

      <para>The driver will create a kernel module, which should be loaded
	at system startup.  You will need to add the following line to the
	<filename>/boot/loader.conf</filename> file:</para>

      <programlisting>nvidia_load="YES"</programlisting>

      <note>
	<para>You may attempt to immediately load the kernel module into the
	  running kernel by issuing a command like
	  <command>kldload nvidia</command>, however it has been noted that
	  the latest versions of <application>&xorg;</application> will not
	  function properly if the driver is not loaded at boot time.  After
	  editing <filename>/boot/loader.conf</filename>, a reboot is
	  recommended.</para>
      </note>

      <para>With the kernel module loaded, you normally only need to change
	a single line in your <filename>xorg.conf</filename> file to enable
	the proprietary driver:</para>

      <para>Find the following line in
	<filename>/etc/X11/xorg.conf</filename>:</para>

      <programlisting>Driver      "nv"</programlisting>

      <para>and change it to:</para>

      <programlisting>Driver      "nvidia"</programlisting>

      <para>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 <application>&xorg;</application> 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.</para>

      <note>
	<para>Although not strictly necessary, you may also wish to install
	  <filename role="package">x11/nvidia-xconfig</filename> and
	  <filename role="package">x11/nvidia-settings</filename> ports.  The
	  former can assist you in writing settings to
	  <filename>/etc/X11/xorg.conf</filename> from the command line, and
	  the latter will allow you to modify screen settings from a GUI while
	  running the <application>&xorg;</application> system.</para>
      </note>
    </sect2>
  </sect1>

  <sect1 id="xorg-configuration">
    <title>Configuring xorg.conf for desktop effects</title>

    <para>Before you install and run
      <application>Compiz&nbsp;Fusion</application>, you need to add a few
      settings to <filename>/etc/X11/xorg.conf</filename>:</para>

    <para>Add the following section to enable composite effects:</para>

    <programlisting>Section "Extensions"
Option         "Composite" "Enable"
EndSection</programlisting>

    <para>Locate the <quote>Screen</quote> section which should look similar
      to the one below:</para>

    <programlisting>Section "Screen"
Identifier     "Screen0"
Device         "Card0"
Monitor        "Monitor0"
...</programlisting>

    <para>and add the following two lines (after <quote>Monitor</quote> will
      do):</para>

    <programlisting>DefaultDepth    24
Option         "AddARGBGLXVisuals" "True"</programlisting>

    <para>Locate the <quote>Subsection</quote> 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:</para>

    <programlisting>SubSection     "Display"
Viewport    0 0
Modes      "1280x1024"
EndSubSection</programlisting>

    <para>A color depth of 24&nbsp;bits is needed for desktop composition,
      change the above subsection to:</para>

    <programlisting>SubSection     "Display"
Viewport    0 0
Depth       24
Modes      "1280x1024"
EndSubSection</programlisting>

    <para>Finally, confirm that the <quote>glx</quote> and
      <quote>extmod</quote> modules are loaded in the <quote>Module</quote>
      section:</para>

    <programlisting>Section "Module"
Load           "extmod"
Load           "glx"
...</programlisting>

    <note>
      <para>If you installed the
	<filename role="package">x11/nvidia-xconfig</filename> port,
	you should be able to perform most of the above settings by
	entering the following commands (as root):</para>

      <screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
&prompt.root; <userinput>nvidia-xconfig --composite</userinput>
&prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>

      <para>You may wish to run <command>nvidia-xconfig -A | more</command>
	to see a list of all the options offered by the above program.</para>
    </note>
  </sect1>

  <sect1 id="compiz-fusion">
    <title>Installing and configuring Compiz&nbsp;Fusion</title>

    <para>Installing <application>Compiz&nbsp;Fusion</application>
      is as simple as any other port:</para>

    <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/compiz-fusion</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>

    <para>Make sure to select the <quote>EXTRA</quote> plugins and the
      <quote>EMERALD</quote> window decorator from the options dialog that
      appears.  If you are using <application>GNOME</application>, or
      already have support for <command>gconf</command> in your system, you
      may also wish to select <quote>gconf support</quote>.  In this way,
      your effect settings will be integrated with the other desktop settings,
      and will be viewable via <command>gconf-editor</command>.
      <application>Compiz&nbsp;Fusion</application>
      <emphasis>can</emphasis> however save its settings to flat files, if
      such an integration is not wanted.  In this case, a
      <filename>.compizconfig</filename> directory will be created inside
      your home directory.</para>

    <para>When the installation is finished, start your graphic desktop and
      at a terminal, enter the following commands (as a normal user):</para>

    <screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;</userinput>
&prompt.user; <userinput>emerald --replace &amp;</userinput></screen>

    <para>Your screen will flicker for a few seconds, as your window manager
      (e.g. <application>Metacity</application> if you are using
      <application>GNOME</application>) is replaced by
      <application>Compiz&nbsp;Fusion</application>.
      <application>Emerald</application> takes care of the window
      decorations (i.e. close, minimize, maximize buttons, title bars
      and so on).</para>

    <para>You may convert this to a trivial script and have it run at
      startup automatically (e.g. by adding to <quote>Sessions</quote> in
      a <application>GNOME</application> desktop):</para>

    <programlisting>#! /bin/sh
compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;
emerald --replace &amp;</programlisting>

    <para>Save this in your home directory as, for example,
      <filename>start-compiz</filename> and make it executable:</para>

    <screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>

    <para>Then use the GUI to add it to
      <guimenuitem>Startup Programs</guimenuitem>
      (located in <guimenuitem>System</guimenuitem>,
      <guimenuitem>Preferences</guimenuitem>,
      <guimenuitem>Sessions</guimenuitem> on a
      <application>GNOME</application> desktop).</para>

    <para>To actually select all the desired effects and their settings,
      execute (again as a normal user) the
      <application>Compiz&nbsp;Config&nbsp;Settings&nbsp;Manager</application>:</para>

    <screen>&prompt.user; <userinput>ccsm</userinput></screen>

    <note>
      <para>In <application>GNOME</application>, this can also be found in
	the <guimenuitem>System</guimenuitem>,
	<guimenuitem>Preferences</guimenuitem> menu.</para>
    </note>

    <para>If you have selected <quote>gconf support</quote> during the build,
      you will also be able to view these settings using
      <command>gconf-editor</command> under <literal>apps/compiz</literal>.
    </para>
  </sect1>

  <sect1 id="compiz-troubleshooting">
    <title>Troubleshooting Compiz&nbsp;Fusion</title>

    <para>The following section covers frequently asked questions regarding
      problems when running
      <application>Compiz&nbsp;Fusion</application>.</para>

    <qandaset>
      <qandaentry>
	<question id="no-decorations">
	  <para>I have installed
	    <application>Compiz&nbsp;Fusion</application>,
	    and after running the commands you mention, my windows are left
	    without title bars and buttons.  What is wrong?</para>
	</question>

	<answer>
	  <para>You are probably missing a setting in
	    <filename>/etc/X11/xorg.conf</filename>.  Review this file
	    carefully and check especially the <literal>DefaultDepth</literal>
	    and <literal>AddARGBGLXVisuals</literal> directives.</para>
	</answer>
      </qandaentry>

      <qandaentry>
	<question id="xorg-crash">
	  <para>When I run the command to start
	    <application>Compiz&nbsp;Fusion</application>, the X server
	    crashes and I am back at the console.  What is wrong?</para>
	</question>

	<answer>
	  <para>If you check your <filename>/var/log/Xorg.0.log</filename>
	    file, you will probably find error messages during the X
	    startup.  The most common would be:</para>

	  <screen>(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.</screen>

	  <para>This is usually the case when you upgrade
	    <application>&xorg;</application>.  You will need to reinstall the
	    <filename role="package">x11/nvidia-driver</filename> port so
	    glx is built again.</para>
	</answer>
      </qandaentry>
    </qandaset>
  </sect1>
</article>