doc/en/gnome-config.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gnome-config.xml,v 1.29 2010/01/04 00:24:16 nightmorph Exp $ -->

<guide>
<title>The GNOME Configuration HOWTO</title>

<author title="Author">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
  <mail link="lars@strojny.net">Lars Strojny</mail>
</author>
<author title="Editor">
  <mail link="nightmorph"/>
</author>

<abstract>
A frequently used environment is GNOME. This HOWTO tries to describe
all aspects of GNOME, including installation, configuration, usage, ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.23</version>
<date>2010-02-11</date>

<chapter>
<title>What is GNOME?</title>
<section>
<title>The Project</title>
<body>

<p>
The <uri link="http://www.gnome.org">GNOME</uri> project is a free software
project dedicated to the development of GNOME, a Unix/Linux desktop suite and
development platform. The <uri link="http://foundation.gnome.org">GNOME
Foundation</uri> coordinates the development and other aspects of the GNOME
Project.
</p>

</body>
</section>
<section>
<title>The Software</title>
<body>

<p>
GNOME is a desktop environment and a development platform. This piece of free
software is the desktop of choice for several industry leaders. It is
interesting both for business users, home users as well as developers.
</p>

</body>
</section>
<section>
<title>The Community</title>
<body>

<p>
Like with any big free software project, GNOME has an extensive user- and
development base. <uri link="http://www.gnomedesktop.org">Footnotes</uri>
contains GNOME Desktop news for users; <uri
link="http://planet.gnome.org">GnomePlanet</uri> is for hackers/contributors and
<uri link="http://developer.gnome.org">Developer.Gnome.Org</uri> is for the
GNOME developers.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Installing GNOME</title>
<section>
<title>What do you need?</title>
<body>

<impo>
First read and follow the instructions in the <uri
link="/doc/en/xorg-confix.xml">X Server Configuration Howto</uri> to setup your
X environment.
</impo>

<p>
Before you start installing GNOME, you might want to edit your USE variables.
Make sure that <c>X</c>, <c>gtk</c>, and <c>gnome</c> are in your USE variable
listed in <path>/etc/make.conf</path>. If you want support for <c>hald</c>, the
hardware abstraction layer daemon add <c>hal</c> to your USE flags. The same
goes for <c>dbus</c>, a system message bus Gnome uses extensively. If you don't
want KDE support (the other big desktop environment), remove <c>qt3</c>,
<c>qt4</c>, <c>arts</c>, and <c>kde</c>.
</p>

<pre caption="Example USE in /etc/make.conf">
USE="-qt3 -qt4 -arts -kde X dbus gtk gnome hal"
</pre>

<p>
You can add the <c>branding</c> USE flag to get a lovely Gentoo-branded
splashscreen instead of the default Gnome splashscreen:
</p>

<pre caption="Enabling Gentoo branding">
# <i>echo "gnome-base/gnome-session branding" &gt;&gt; /etc/portage/package.use</i>
</pre>

<p>
Once done, start installing GNOME by emerging <c>gnome</c>:
</p>

<pre caption="Installing GNOME">
# <i>emerge gnome</i>
</pre>

<p>
You can also opt for a minimal Gnome installation using <c>gnome-light</c>:
</p>

<pre caption="Installing a minimal GNOME environment">
# <i>emerge gnome-light</i>
</pre>

<p>
This will take a while, so you might want to start reading all those books your
mother bought you but you never opened. Done? Great, now update your
environment variables:
</p>

<pre caption="Updating environment variables">
# <i>env-update &amp;&amp; source /etc/profile</i>
</pre>

<p>
Next we'll clean up the remaining services.
</p>

<pre caption="Adding hald and dbus to the default runlevel">
# <i>/etc/init.d/hald start</i>
# <i>rc-update add hald default</i>

# <i>/etc/init.d/dbus start</i>
# <i>rc-update add dbus default</i>
</pre>

</body>
</section>
<section>
<title>First Impressions</title>
<body>

<p>
Let us first take a look at what we just built. Exit your root shell and log on
as a regular user. We will configure our session to run GNOME when we issue the
<c>startx</c> command (see also
<uri link="/doc/en/xorg-config.xml#using_startx">Using startx</uri> in the
<uri link="/doc/en/xorg-config.xml">X Server Configuration Howto</uri>):
</p>

<pre caption="Having GNOME as default desktop environment">
$ <i>echo "exec gnome-session" &gt; ~/.xinitrc</i>
</pre>

<p>
Starting with <c>gnome-base/gnome-session-2.26.2</c>, you will need to prepend
the XDG_MENU_PREFIX variable to get the Gnome menus if you're using the
<path>~/.xinitrc</path> method to start your desktop. (If you're not using
<path>~/.xinitrc</path>, it will be handled automatically for you; no additional
configuration is needed.)
</p>

<pre caption="Prepending XDG_MENU_PREFIX to ~/.xinitrc">
$ <i>sed -i '1i\export XDG_MENU_PREFIX=gnome-' ~/.xinitrc</i>
</pre>

<p>
Now start your graphical environment by running <c>startx</c>:
</p>

<pre caption="Starting GNOME">
$ <i>startx</i>
</pre>

<p>
If all goes well, you should be greeted by GNOME. Congratulations. Now let us
take a look at how you can configure GNOME to suit your needs.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Configuring GNOME</title>
<section>
<title>GNOME's Graphical Login Manager</title>
<body>

<p>
If you want the GNOME Display Manager (GDM) to run automatically when you boot
(so you can log on graphically), you must add the <c>xdm</c> init script to the
default runlevel:
</p>

<pre caption="Adding xdm to the default runlevel">
# <i>rc-update add xdm default</i>
</pre>

<p>
Now edit <path>/etc/conf.d/xdm</path> and alter the DISPLAYMANAGER variable.
</p>

<pre caption="Editing /etc/conf.d/xdm">
DISPLAYMANAGER="gdm"
</pre>

<p>
If you reboot now, the GNOME Display Manager will prompt you for your username
and password and will default to using GNOME as Desktop Environment (even though
you will have the option of selecting a different one of course, choosing from
those available in <path>/usr/share/xsessions/</path>). Thus, if you use GDM,
you don't need to edit <path>~/.xinitrc</path>.
</p>

<p>
To use the functionality of <c>hald</c> you need to add your user to the
<c>plugdev</c> group. If you want support for devices not handled by the
<c>nautilus</c> file manager, or if you're not using <c>nautilus</c> at all, you
might want to make sure that <c>gnome-volume-manager</c> is built with the
<c>automount</c> USE flag, and that it's started every time you login.
</p>

</body>
</section>
</chapter>
</guide>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	nightmorph	1.30	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gnome-config.xml,v 1.29 2010/01/04 00:24:16 nightmorph Exp $ -->
4	swift	1.1
5	nightmorph	1.28	<guide>
6	swift	1.1	<title>The GNOME Configuration HOWTO</title>
7
8			<author title="Author">
9	nightmorph	1.14	<mail link="swift@gentoo.org">Sven Vermeulen</mail>
10	swift	1.1	</author>
11	dertobi123	1.3	<author title="Editor">
12			<mail link="lars@strojny.net">Lars Strojny</mail>
13			</author>
14	nightmorph	1.21	<author title="Editor">
15			<mail link="nightmorph"/>
16			</author>
17	swift	1.1
18			<abstract>
19	swift	1.26	A frequently used environment is GNOME. This HOWTO tries to describe
20	swift	1.1	all aspects of GNOME, including installation, configuration, usage, ...
21			</abstract>
22
23			<!-- The content of this document is licensed under the CC-BY-SA license -->
24	neysx	1.7	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
25	swift	1.1	<license/>
26
27	nightmorph	1.30	<version>1.23</version>
28			<date>2010-02-11</date>
29	swift	1.1
30			<chapter>
31			<title>What is GNOME?</title>
32			<section>
33			<title>The Project</title>
34			<body>
35
36			<p>
37			The <uri link="http://www.gnome.org">GNOME</uri> project is a free software
38			project dedicated to the development of GNOME, a Unix/Linux desktop suite and
39	swift	1.26	development platform. The <uri link="http://foundation.gnome.org">GNOME
40			Foundation</uri> coordinates the development and other aspects of the GNOME
41	swift	1.1	Project.
42			</p>
43
44			</body>
45			</section>
46			<section>
47			<title>The Software</title>
48			<body>
49
50			<p>
51			GNOME is a desktop environment and a development platform. This piece of free
52			software is the desktop of choice for several industry leaders. It is
53			interesting both for business users, home users as well as developers.
54			</p>
55
56			</body>
57			</section>
58			<section>
59			<title>The Community</title>
60			<body>
61
62			<p>
63			Like with any big free software project, GNOME has an extensive user- and
64			development base. <uri link="http://www.gnomedesktop.org">Footnotes</uri>
65			contains GNOME Desktop news for users; <uri
66			link="http://planet.gnome.org">GnomePlanet</uri> is for hackers/contributors and
67			<uri link="http://developer.gnome.org">Developer.Gnome.Org</uri> is for the
68			GNOME developers.
69			</p>
70
71			</body>
72			</section>
73			</chapter>
74			<chapter>
75			<title>Installing GNOME</title>
76			<section>
77			<title>What do you need?</title>
78			<body>
79
80	nightmorph	1.30	<impo>
81			First read and follow the instructions in the <uri
82			link="/doc/en/xorg-confix.xml">X Server Configuration Howto</uri> to setup your
83			X environment.
84			</impo>
85
86	swift	1.1	<p>
87			Before you start installing GNOME, you might want to edit your USE variables.
88	nightmorph	1.21	Make sure that <c>X</c>, <c>gtk</c>, and <c>gnome</c> are in your USE variable
89			listed in <path>/etc/make.conf</path>. If you want support for <c>hald</c>, the
90			hardware abstraction layer daemon add <c>hal</c> to your USE flags. The same
91	nightmorph	1.28	goes for <c>dbus</c>, a system message bus Gnome uses extensively. If you don't
92			want KDE support (the other big desktop environment), remove <c>qt3</c>,
93			<c>qt4</c>, <c>arts</c>, and <c>kde</c>.
94	swift	1.1	</p>
95
96			<pre caption="Example USE in /etc/make.conf">
97	nightmorph	1.28	USE="-qt3 -qt4 -arts -kde X dbus gtk gnome hal"
98	swift	1.1	</pre>
99
100			<p>
101	nightmorph	1.17	You can add the <c>branding</c> USE flag to get a lovely Gentoo-branded
102			splashscreen instead of the default Gnome splashscreen:
103			</p>
104
105			<pre caption="Enabling Gentoo branding">
106			# <i>echo "gnome-base/gnome-session branding" >> /etc/portage/package.use</i>
107			</pre>
108
109			<p>
110	nightmorph	1.18	Once done, start installing GNOME by emerging <c>gnome</c>:
111	swift	1.1	</p>
112
113			<pre caption="Installing GNOME">
114	nightmorph	1.18	# <i>emerge gnome</i>
115	swift	1.1	</pre>
116
117			<p>
118	swift	1.4	You can also opt for a minimal Gnome installation using <c>gnome-light</c>:
119			</p>
120
121			<pre caption="Installing a minimal GNOME environment">
122			# <i>emerge gnome-light</i>
123			</pre>
124
125			<p>
126	swift	1.1	This will take a while, so you might want to start reading all those books your
127	swift	1.26	mother bought you but you never opened. Done? Great, now update your
128	swift	1.1	environment variables:
129			</p>
130
131			<pre caption="Updating environment variables">
132			# <i>env-update && source /etc/profile</i>
133			</pre>
134
135			<p>
136	jkt	1.19	Next we'll clean up the remaining services.
137	nightmorph	1.6	</p>
138	dertobi123	1.3
139	nightmorph	1.28	<pre caption="Adding hald and dbus to the default runlevel">
140	dertobi123	1.3	# <i>/etc/init.d/hald start</i>
141			# <i>rc-update add hald default</i>
142
143	nightmorph	1.23	# <i>/etc/init.d/dbus start</i>
144	nightmorph	1.22	# <i>rc-update add dbus default</i>
145	swift	1.1	</pre>
146
147			</body>
148			</section>
149			<section>
150			<title>First Impressions</title>
151			<body>
152
153			<p>
154			Let us first take a look at what we just built. Exit your root shell and log on
155			as a regular user. We will configure our session to run GNOME when we issue the
156	swift	1.5	<c>startx</c> command (see also
157			<uri link="/doc/en/xorg-config.xml#using_startx">Using startx</uri> in the
158			<uri link="/doc/en/xorg-config.xml">X Server Configuration Howto</uri>):
159	swift	1.1	</p>
160
161			<pre caption="Having GNOME as default desktop environment">
162			$ <i>echo "exec gnome-session" > ~/.xinitrc</i>
163			</pre>
164
165			<p>
166	nightmorph	1.27	Starting with <c>gnome-base/gnome-session-2.26.2</c>, you will need to prepend
167			the XDG_MENU_PREFIX variable to get the Gnome menus if you're using the
168			<path>~/.xinitrc</path> method to start your desktop. (If you're not using
169			<path>~/.xinitrc</path>, it will be handled automatically for you; no additional
170			configuration is needed.)
171			</p>
172
173			<pre caption="Prepending XDG_MENU_PREFIX to ~/.xinitrc">
174	nightmorph	1.29	$ <i>sed -i '1i\export XDG_MENU_PREFIX=gnome-' ~/.xinitrc</i>
175	nightmorph	1.27	</pre>
176
177			<p>
178	swift	1.1	Now start your graphical environment by running <c>startx</c>:
179			</p>
180
181			<pre caption="Starting GNOME">
182			$ <i>startx</i>
183			</pre>
184
185			<p>
186			If all goes well, you should be greeted by GNOME. Congratulations. Now let us
187			take a look at how you can configure GNOME to suit your needs.
188			</p>
189
190			</body>
191			</section>
192			</chapter>
193			<chapter>
194			<title>Configuring GNOME</title>
195			<section>
196			<title>GNOME's Graphical Login Manager</title>
197			<body>
198
199			<p>
200			If you want the GNOME Display Manager (GDM) to run automatically when you boot
201			(so you can log on graphically), you must add the <c>xdm</c> init script to the
202			default runlevel:
203			</p>
204
205			<pre caption="Adding xdm to the default runlevel">
206			# <i>rc-update add xdm default</i>
207			</pre>
208
209			<p>
210	nightmorph	1.16	Now edit <path>/etc/conf.d/xdm</path> and alter the DISPLAYMANAGER variable.
211	swift	1.1	</p>
212
213	nightmorph	1.16	<pre caption="Editing /etc/conf.d/xdm">
214	swift	1.1	DISPLAYMANAGER="gdm"
215			</pre>
216
217			<p>
218			If you reboot now, the GNOME Display Manager will prompt you for your username
219			and password and will default to using GNOME as Desktop Environment (even though
220	swift	1.5	you will have the option of selecting a different one of course, choosing from
221			those available in <path>/usr/share/xsessions/</path>). Thus, if you use GDM,
222			you don't need to edit <path>~/.xinitrc</path>.
223	swift	1.1	</p>
224
225	dertobi123	1.3	<p>
226	nightmorph	1.27	To use the functionality of <c>hald</c> you need to add your user to the
227			<c>plugdev</c> group. If you want support for devices not handled by the
228			<c>nautilus</c> file manager, or if you're not using <c>nautilus</c> at all, you
229			might want to make sure that <c>gnome-volume-manager</c> is built with the
230			<c>automount</c> USE flag, and that it's started every time you login.
231	dertobi123	1.3	</p>
232
233	swift	1.1	</body>
234			</section>
235			</chapter>
236			</guide>