os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

- Add an article about installing and using the Compiz Fusion composite

Browse source 
window manager under FreeBSD. The article also covers the installation
  of the nVidia display drivers.

Submitted by:	Manolis Kiagias <sonicy@otenet.gr>
This commit is contained in:
Gabor Kovesdan 2008-02-12 07:25:23 +00:00
parent 284de2ea5b
commit 5c6725b69c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=31467
3 changed files with 432 additions and 0 deletions
en_US.ISO8859-1/articles
Makefile
compiz-fusion
Makefilearticle.sgml

1
en_US.ISO8859-1/articles/Makefile
View file

@ -7,6 +7,7 @@ SUBDIR+= building-products
SUBDIR+= casestudy-argentina.com
SUBDIR+= checkpoint
SUBDIR+= committers-guide
SUBDIR+= compiz-fusion
SUBDIR+= console-server
SUBDIR+= contributing
SUBDIR+= contributing-ports

18
en_US.ISO8859-1/articles/compiz-fusion/Makefile Normal file
View file

@ -0,0 +1,18 @@
#
# $FreeBSD$
#
# Article: Installing and using compiz-fusion
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

413
en_US.ISO8859-1/articles/compiz-fusion/article.sgml Normal file
View file

@ -0,0 +1,413 @@
<+
<!--
Installing and Using compiz-fusion in FreeBSD
The FreeBSD Documentation Project
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
]>
<article lang="en">
<articleinfo>
<title>Installing and using Compiz&nbsp;Fusion</title>
<author>
<firstname>Manolis</firstname>
<surname>Kiagias</surname>
<affiliation>
<address><email>sonicy@otenet.gr</email></address>
</affiliation>
</author>
<copyright>
<year>2008</year>
<holder role="mailto:sonicy@otenet.gr">Manolis Kiagias</holder>
</copyright>
<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 96X 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 71XX 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:
<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 24bits 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; nvidia-xconfig --add-argb-glx-visuals
&prompt.root; nvidia-xconfig --composite
&prompt.root; nvidia-xconfig --depth=24</screen>
<para>You may wish to run <command>nvidia-xonfig -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; cd /usr/ports/x11-wm/compiz-fusion
&prompt.root; make install clean</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>compiz --replace --sm-disable --ignore-desktop-hints ccp &
emerald --replace &</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 &
emerald --replace &</programlisting>
<para>Save this in your home directory as, for example,
<filename>start-compiz</filename> and make it executable:</para>
<screen>chmod +x ~/start-compiz</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>ccsm</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 DefaultDepth and
AddARGBGLXVisuals 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>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
fill-column: 78
indent-tabs-mode: nil
End:
-->