1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
|
<?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 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 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 Fusion</application> 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
<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 Fusion</application> using the
Ports 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 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 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 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 Fusion</title>
<para>Installing <application>Compiz 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 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 &</userinput>
&prompt.user; <userinput>emerald --replace &</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 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>&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 Config Settings 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 Fusion</title>
<para>The following section covers frequently asked questions regarding
problems when running
<application>Compiz Fusion</application>.</para>
<qandaset>
<qandaentry>
<question id="no-decorations">
<para>I have installed
<application>Compiz 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 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>
|