handbook: migrate compiz fusion article

The compiz fusion article previously duplicated portions of the handbook
	in an effort to be complete.  In addition, there was no reference from
	the handbook so it was often forgotten.

	By moving the article into the handbook, the article can be simplified,
	text removed, and cross references can be added.

	In addition, adding nice effects is a common enough task and isn't too
	technical that it could be combined with the handbook.

	As a part of the migration, reduce the focus on requiring an nVidia
	driver.
This commit is contained in:
Eitan Adler 2015-04-04 21:28:28 +00:00
parent 8bf23bc848
commit 0bd4a7e64a
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=46462

View file

@ -1239,6 +1239,198 @@ DisplayManager.requestPort: 0</screen>
</sect2>
</sect1>
<sect1 xml:id="x-compiz-fusion">
<title>Installing Compiz Fusion</title>
<para>One way to increase the pleasantness of using a desktop
computer is by having nice 3D effects.</para>
<para>Installing the <application>Compiz&nbsp;Fusion</application>
package is easy, but configuring it requires a few steps that
are not described in the port's documentation.</para>
<sect2 xml:id="x-compiz-video-card">
<title>Setting up the &os; nVidia driver</title>
<para>Desktop effects can cause quite a load on the graphics card.
For an an nVidia-based graphics card, the proprietary driver
is required for good performance. Users of other graphics
cards can skip this section and continue with the
<filename>xorg.conf</filename> configuration.</para>
<para>
To determine which nVidia driveris needed see the <link xlink:href="&url.books.faq;/x.html#idp59950544">FAQ question
on the subject</link>.
</para>
<para>Having determined the correct driver to use for your card,
installation is as simple as installing any other package.</para>
<para>For example, to install the latest driver:</para>
<screen>&prompt.root; <userinput>pkg install x11/nvidia-driver</userinput></screen>
<para>The driver will create a kernel module, which needs to be loaded
at system startup. Add the following line to
<filename>/boot/loader.conf</filename>:</para>
<programlisting>nvidia_load="YES"</programlisting>
<note>
<para>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 some 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 the GUI as usual, and you should be greeted by the
nVidia splash. Everything should work as usual.</para>
</sect2>
<sect2 xml:id="xorg-configuration">
<title>Configuring xorg.conf for desktop effects</title>
<para>To enable <application>Compiz&nbsp;Fusion</application>,
<filename>/etc/X11/xorg.conf</filename> needs to be
modified:</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>
<para>The preceding can be done automatically with
<package>x11/nvidia-xconfig</package> by running (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>
</sect2>
<sect2 xml:id="compiz-fusion">
<title>Installing and configuring Compiz&nbsp;Fusion</title>
<para>Installing <application>Compiz&nbsp;Fusion</application>
is as simple as any other package:</para>
<screen>&prompt.root; <userinput>pkg install x11-wm/compiz-fusion</userinput></screen>
<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>
</sect2>
</sect1>
<sect1 xml:id="x11-understanding">
<title>Troubleshooting</title>
@ -1520,5 +1712,52 @@ EndSection</programlisting>
<para>Now having completed these simple editing steps, X
should start on your new widescreen monitor.</para>
</sect2>
</sect1>
</chapter>
<sect2 xml:id="compiz-troubleshooting">
<title>Troubleshooting Compiz&nbsp;Fusion</title>
<qandaset>
<qandaentry>
<question xml: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 xml: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
<package>x11/nvidia-driver</package> package so
glx is built again.</para>
</answer>
</qandaentry>
</qandaset>
</sect2>
</sect1>
</chapter>