en/handbook/hb-working-features.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

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

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.15 2004/08/30 17:44:00 neysx Exp $ -->

<sections>
<section>
<title>DistCC</title>
<subsection>
<title>What is DistCC?</title>
<body>

<p>
<c>distcc</c> is a program to distribute compilations across several, not 
necessarily identical, machines on a network. The <c>distcc</c> client sends all
necessary information to the available DistCC servers (running <c>distccd</c>)
so they can compile pieces of source code for the client. The net result is a
faster compilation time.
</p>

<p>
You can find more elaborate information about <c>distcc</c> (and information on
how to have it work with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo
Distcc Documentation</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Installing DistCC</title>
<body>

<p>
Distcc ships with a graphical monitor to monitor tasks that your computer is
sending away for compilation. If you use Gnome then put 'gnome' in your
<c>USE</c> setting. However, if you don't use Gnome and would still like to have
the monitor then you should put 'gtk' in your <c>USE</c> setting.
</p>

<p>
Installing distcc is, as is with all software available through Gentoo's
Portage, extremely easy:
</p>

<note>
From now on, we will omit the --usepkg option throughout the rest of the Gentoo
Handbook, as you now know how to install binary packages when you want to.
</note>

<pre caption="Installing Distcc">
# <i>emerge distcc</i>
</pre>

</body>
</subsection>
<subsection>
<title>Activating Portage Support</title>
<body>

<p>
Well, if installation is easy, the rest should be easy too :) So let us quickly
activate the Portage support for <c>distcc</c>.
</p>

<p>
First, open <path>/etc/make.conf</path> and edit the <c>FEATURES</c> variable so
it contains the <c>distcc</c> keyword. Next, edit the <c>MAKEOPTS</c> variable
so it reads <c>-jX</c> with <c>X</c> the number of CPUs that run <c>distccd</c>
(including the current host) plus one:
</p>

<pre caption="Possible MAKEOPTS setting in /etc/make.conf">
<comment># Suppose you have 2 single-CPU distccd hosts excluding this host:</comment>
MAKEOPTS="-j4"
</pre>

<p>
Now run <c>distcc-config</c> and enter the list of available DistCC servers. For
a simple example we assume that the available DistCC servers are
<c>192.168.1.102</c> (the current host), <c>192.168.1.103</c> and 
<c>192.168.1.104</c> (two "remote" hosts):
</p>

<pre caption="Configuring distcc to use three available DistCC servers">
# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
</pre>

<p>
Of course, don't forget to run the <c>distccd</c> daemon too:
</p>

<pre caption="Starting the distcc daemon">
# <i>/etc/init.d/distccd start</i>
</pre>

<p>
Congratulations, your system will now use distributed compiling! For more
in-depth information about DistCC and Gentoo, please read our <uri
link="/doc/en/distcc.xml">Gentoo DistCC Documentation</uri>.
</p>

</body>
</subsection>
</section>
<section>
<title>ccache</title>
<subsection>
<title>What is ccache?</title>
<body>

<p>
<c>ccache</c> is a fast compiler cache. When you compile a program, it will
cache intermediate results so that, whenever you recompile the same program,
the compilation time is greatly reduced. In common compilations this can result
in 5 to 10 times faster compilation times.
</p>

<p>
If you are interested in the ins and outs of <c>ccache</c>, please visit the
<uri link="http://ccache.samba.org">ccache homepage</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Installing ccache</title>
<body>

<p>
Installing <c>ccache</c> with Gentoo is a breeze. Just emerge it and you're done
:)
</p>

<pre caption="Installing ccache">
# <i>emerge ccache</i>
</pre>

</body>
</subsection>
<subsection>
<title>Tweaking ccache</title>
<body>

<p>
Portage will automatically use ccache if it's installed. However, you can alter
the default cache size used by ccache by providing a <c>CCACHE_SIZE</c> variable
in <path>/etc/make.conf</path>:
</p>

<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
CCACHE_SIZE="2G"
</pre>

<p>
As of now, Portage will use <c>ccache</c> to speed up compilations where
possible. If you are uncertain that <c>ccache</c> works, you can run <c>ccache
-s</c> to view the <c>ccache</c> statistics:
</p>

<pre caption="Viewing ccache statistics">
# <i>ccache -s</i>
</pre>

</body>
</subsection>
<subsection>
<title>Using ccache for non-Portage C compiling</title>
<body>

<p>
If you would like to use ccache for non-Portage compilations, add
<path>/usr/lib/ccache/bin</path> to the beginning of your <c>PATH</c> variable
(before <path>/usr/bin</path>). This can be accomplished by editing
<path>/etc/env.d/00basic</path>:
</p>

<pre caption="Editing 00basic">
# <i>nano -w /etc/env.d/00basic</i>
# <i>env-update &amp;&amp; source /etc/profile</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Binary Packages</title>
<subsection>
<title>Creating binary packages</title>
<body>

<p>
We have already discussed how to work with prebuilt packages, but how do you
create your own prebuilt packages?
</p>

<p>
If the package is already installed, you can use the <c>quickpkg</c> command
which will make a tarball of the installed files. This is very useful for
backup purposes!
</p>

<pre caption="Using quickpkg">
# <i>quickpkg gnumeric</i>
</pre>

<p>
If the package isn't installed yet, you can install it using <c>emerge</c> and
ask to build a binary package too. <c>emerge</c> uses the <c>--buildpkg</c>
option (<c>-b</c> in short) for this:
</p>

<pre caption="Installing gnumeric and building binary packages too">
# <i>emerge --buildpkg gnumeric</i>
</pre>

<p>
If you want Portage to do this by default, you should set the <c>buildpkg</c>
keyword in the <c>FEATURES</c> variable declared in <path>/etc/make.conf</path>.
</p>

<pre caption="Automatically creating binary packages">
FEATURES="buildpkg"
</pre>

<p>
If you don't want to install the software, but only build the package, you can
use the <c>--buildpkgonly</c> option (<c>-B</c> in short):
</p>

<pre caption="Building a binary package for gnumeric">
# <i>emerge --buildpkgonly gnumeric</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Security Related Features</title>
<subsection>
<title>Sandbox</title>
<body>

<p>
While building and installing packages, Portage uses a <e>sandbox</e> to protect
your live system. This means that, as long as the package isn't installed on
your system, the package cannot touch any file outside the sandbox. This 
ensures that Portage knows what files are created and modified by a package.
</p>

<p>
When the package compilation is finished, Portage will "preinstall" the package
in the sandbox, registering what files are placed and where. It will then move
those files from the sandbox on your live system.
</p>

</body>
</subsection>
<subsection>
<title>User Privileges</title>
<body>

<p>
Portage also supports building packages as non-root user (more precisely, as
user "portage", group "portage"). This improves the security during the
build process. You can opt to use user privileges with or without sandboxing. Of
course, it goes without saying that user privileges and sandboxing is the most
preferred method :)
</p>

</body>
</subsection>
<subsection>
<title>Activating sandbox and/or userpriv</title>
<body>

<p>
Portage will use <c>sandbox</c> by default. If you want <c>userpriv</c>, you
should add it to the <c>FEATURES</c> variable. Note that activating
<c>userpriv</c> will drop <c>sandbox</c> support, unless you also activate
<c>usersandbox</c>:
</p>

<pre caption="Activating userpriv and usersandbox">
FEATURES="userpriv usersandbox"
</pre>

<warn>
Do <e>not</e> remove <c>sandbox</c> from the <c>FEATURES</c> variable!
</warn>

</body>
</subsection>
<subsection>
<title>Strict Checking</title>
<body>

<p>
Portage can be asked to react strongly to possibly dangerous conditions (such as
missing or incorrect Manifest files). To activate this strict checking, add the
<c>strict</c> keyword to the <c>FEATURES</c> variable:
</p>

<pre caption="Activating strict checking">
FEATURES="strict"
</pre>

</body>
</subsection>
<subsection>
<title>Smart File System Permissions</title>
<body>

<p>
Portage can be told to automatically deal with potentially dangerous file
permissions that could pose a security risk. It does this by removing the
"group" and "other" readable bits on setuid files and removing the "other"
readable bit on setgid files in the pre install phase.  To activate the
smart file permissions, add the <c>sfperms</c> keyword to the
<c>FEATURES</c> variable:
</p>

<pre caption="Activating smart file system permissions">
FEATURES="sfperms"
</pre>

</body>
</subsection>
</section>
<section>
<title>SLOT'ed Software Titles</title>
<subsection>
<title>SLOT ?</title>
<body>

<p>
Occasionally you need to have several versions of a software title installed at
the same time to satisfy your system's dependencies. Whereas most distributions
allow this by having their packages called to the version (such as 
<c>freetype</c> and <c>freetype2</c>) Portage uses the concept of <e>SLOT</e>s.
</p>

<p>
A <e>SLOT</e> is a (part of a) version number that tells Portage that all
equally named packages with a different SLOT are able to coexist on the same 
system. Portage is able to track both branches of a certain package and update
them if updates to the respective branches are available.
</p>

<p>
When you perform an update Portage will only automatically unmerge the old
instance of a package if it uses the same SLOT. This is why kernel sources are
never automatically unmerged as their SLOT is the complete version. 
</p>

</body>
</subsection>
</section>
<section>
<title>Other Features</title>
<subsection>
<title>Portage Help</title>
<body>

<p>
There are several other keywords you can place in the <c>FEATURES</c> variable.
Most of them are targeted towards developers and less interesting for the casual
user. If you are interested in learning more about these features (or Portage
generally), don't forget to read the <path>make.conf</path> manpage we provide.
</p>

<pre caption="More Portage-related information">
# <i>man make.conf</i>
</pre>

</body>
</subsection>
</section>
</sections>
1	swift	1.10	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4	swift	1.1	<!-- The content of this document is licensed under the CC-BY-SA license -->
5			<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
6
7	swift	1.16	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.15 2004/08/30 17:44:00 neysx Exp $ -->
8	swift	1.1
9			<sections>
10			<section>
11			<title>DistCC</title>
12			<subsection>
13			<title>What is DistCC?</title>
14			<body>
15
16	swift	1.2	<p>
17			<c>distcc</c> is a program to distribute compilations across several, not
18			necessarily identical, machines on a network. The <c>distcc</c> client sends all
19			necessary information to the available DistCC servers (running <c>distccd</c>)
20	swift	1.9	so they can compile pieces of source code for the client. The net result is a
21	swift	1.2	faster compilation time.
22			</p>
23
24			<p>
25			You can find more elaborate information about <c>distcc</c> (and information on
26			how to have it work with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo
27			Distcc Documentation</uri>.
28			</p>
29
30	swift	1.1	</body>
31			</subsection>
32			<subsection>
33			<title>Installing DistCC</title>
34			<body>
35
36	swift	1.2	<p>
37			Distcc ships with a graphical monitor to monitor tasks that your computer is
38			sending away for compilation. If you use Gnome then put 'gnome' in your
39			<c>USE</c> setting. However, if you don't use Gnome and would still like to have
40			the monitor then you should put 'gtk' in your <c>USE</c> setting.
41			</p>
42
43			<p>
44			Installing distcc is, as is with all software available through Gentoo's
45			Portage, extremely easy:
46			</p>
47
48			<note>
49	neysx	1.15	From now on, we will omit the --usepkg option throughout the rest of the Gentoo
50			Handbook, as you now know how to install binary packages when you want to.
51	swift	1.2	</note>
52
53			<pre caption="Installing Distcc">
54			# <i>emerge distcc</i>
55			</pre>
56
57	swift	1.1	</body>
58			</subsection>
59			<subsection>
60			<title>Activating Portage Support</title>
61			<body>
62
63	swift	1.2	<p>
64			Well, if installation is easy, the rest should be easy too :) So let us quickly
65			activate the Portage support for <c>distcc</c>.
66			</p>
67
68			<p>
69			First, open <path>/etc/make.conf</path> and edit the <c>FEATURES</c> variable so
70			it contains the <c>distcc</c> keyword. Next, edit the <c>MAKEOPTS</c> variable
71	swift	1.3	so it reads <c>-jX</c> with <c>X</c> the number of CPUs that run <c>distccd</c>
72			(including the current host) plus one:
73	swift	1.2	</p>
74
75			<pre caption="Possible MAKEOPTS setting in /etc/make.conf">
76	swift	1.3	<comment># Suppose you have 2 single-CPU distccd hosts excluding this host:</comment>
77			MAKEOPTS="-j4"
78	swift	1.2	</pre>
79
80			<p>
81	swift	1.3	Now run <c>distcc-config</c> and enter the list of available DistCC servers. For
82			a simple example we assume that the available DistCC servers are
83			<c>192.168.1.102</c> (the current host), <c>192.168.1.103</c> and
84			<c>192.168.1.104</c> (two "remote" hosts):
85			</p>
86
87			<pre caption="Configuring distcc to use three available DistCC servers">
88			# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
89			</pre>
90
91			<p>
92			Of course, don't forget to run the <c>distccd</c> daemon too:
93			</p>
94
95			<pre caption="Starting the distcc daemon">
96			# <i>/etc/init.d/distccd start</i>
97			</pre>
98
99			<p>
100			Congratulations, your system will now use distributed compiling! For more
101			in-depth information about DistCC and Gentoo, please read our <uri
102			link="/doc/en/distcc.xml">Gentoo DistCC Documentation</uri>.
103			</p>
104	swift	1.2
105	swift	1.1	</body>
106			</subsection>
107			</section>
108			<section>
109	swift	1.4	<title>ccache</title>
110	swift	1.1	<subsection>
111	swift	1.4	<title>What is ccache?</title>
112	swift	1.1	<body>
113
114	swift	1.4	<p>
115			<c>ccache</c> is a fast compiler cache. When you compile a program, it will
116	neysx	1.15	cache intermediate results so that, whenever you recompile the same program,
117	swift	1.4	the compilation time is greatly reduced. In common compilations this can result
118			in 5 to 10 times faster compilation times.
119			</p>
120
121			<p>
122			If you are interested in the ins and outs of <c>ccache</c>, please visit the
123			<uri link="http://ccache.samba.org">ccache homepage</uri>.
124			</p>
125
126	swift	1.1	</body>
127			</subsection>
128			<subsection>
129	swift	1.4	<title>Installing ccache</title>
130	swift	1.1	<body>
131
132	swift	1.4	<p>
133			Installing <c>ccache</c> with Gentoo is a breeze. Just emerge it and you're done
134			:)
135			</p>
136
137			<pre caption="Installing ccache">
138			# <i>emerge ccache</i>
139			</pre>
140
141	swift	1.1	</body>
142			</subsection>
143			<subsection>
144	swift	1.12	<title>Tweaking ccache</title>
145	swift	1.1	<body>
146	swift	1.4
147			<p>
148	swift	1.12	Portage will automatically use ccache if it's installed. However, you can alter
149			the default cache size used by ccache by providing a <c>CCACHE_SIZE</c> variable
150			in <path>/etc/make.conf</path>:
151	swift	1.4	</p>
152
153			<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
154			CCACHE_SIZE="2G"
155			</pre>
156
157			<p>
158			As of now, Portage will use <c>ccache</c> to speed up compilations where
159			possible. If you are uncertain that <c>ccache</c> works, you can run <c>ccache
160			-s</c> to view the <c>ccache</c> statistics:
161			</p>
162
163			<pre caption="Viewing ccache statistics">
164			# <i>ccache -s</i>
165			</pre>
166	swift	1.1
167			</body>
168			</subsection>
169	swift	1.12	<subsection>
170			<title>Using ccache for non-Portage C compiling</title>
171			<body>
172
173			<p>
174			If you would like to use ccache for non-Portage compilations, add
175			<path>/usr/lib/ccache/bin</path> to the beginning of your <c>PATH</c> variable
176			(before <path>/usr/bin</path>). This can be accomplished by editing
177			<path>/etc/env.d/00basic</path>:
178			</p>
179
180			<pre caption="Editing 00basic">
181			# <i>nano -w /etc/env.d/00basic</i>
182			# <i>env-update && source /etc/profile</i>
183			</pre>
184
185			</body>
186			</subsection>
187	swift	1.1	</section>
188			<section>
189			<title>Binary Packages</title>
190			<subsection>
191			<title>Creating binary packages</title>
192			<body>
193
194	swift	1.2	<p>
195	swift	1.8	We have already discussed how to work with prebuilt packages, but how do you
196			create your own prebuilt packages?
197	swift	1.2	</p>
198
199			<p>
200			If the package is already installed, you can use the <c>quickpkg</c> command
201	neysx	1.15	which will make a tarball of the installed files. This is very useful for
202	swift	1.2	backup purposes!
203			</p>
204
205			<pre caption="Using quickpkg">
206			# <i>quickpkg gnumeric</i>
207			</pre>
208
209			<p>
210			If the package isn't installed yet, you can install it using <c>emerge</c> and
211			ask to build a binary package too. <c>emerge</c> uses the <c>--buildpkg</c>
212			option (<c>-b</c> in short) for this:
213			</p>
214
215			<pre caption="Installing gnumeric and building binary packages too">
216			# <i>emerge --buildpkg gnumeric</i>
217			</pre>
218
219			<p>
220			If you want Portage to do this by default, you should set the <c>buildpkg</c>
221			keyword in the <c>FEATURES</c> variable declared in <path>/etc/make.conf</path>.
222			</p>
223	swift	1.6
224			<pre caption="Automatically creating binary packages">
225			FEATURES="buildpkg"
226			</pre>
227	swift	1.2
228			<p>
229			If you don't want to install the software, but only build the package, you can
230			use the <c>--buildpkgonly</c> option (<c>-B</c> in short):
231			</p>
232
233			<pre caption="Building a binary package for gnumeric">
234			# <i>emerge --buildpkgonly gnumeric</i>
235	swift	1.5	</pre>
236
237			</body>
238			</subsection>
239			</section>
240			<section>
241			<title>Security Related Features</title>
242			<subsection>
243			<title>Sandbox</title>
244			<body>
245
246			<p>
247			While building and installing packages, Portage uses a <e>sandbox</e> to protect
248			your live system. This means that, as long as the package isn't installed on
249			your system, the package cannot touch any file outside the sandbox. This
250			ensures that Portage knows what files are created and modified by a package.
251			</p>
252
253			<p>
254			When the package compilation is finished, Portage will "preinstall" the package
255			in the sandbox, registering what files are placed and where. It will then move
256			those files from the sandbox on your live system.
257			</p>
258
259			</body>
260			</subsection>
261			<subsection>
262			<title>User Privileges</title>
263			<body>
264
265			<p>
266			Portage also supports building packages as non-root user (more precisely, as
267			user "portage", group "portage"). This improves the security during the
268			build process. You can opt to use user privileges with or without sandboxing. Of
269			course, it goes without saying that user privileges and sandboxing is the most
270			preferred method :)
271			</p>
272
273			</body>
274			</subsection>
275			<subsection>
276			<title>Activating sandbox and/or userpriv</title>
277			<body>
278
279			<p>
280	neysx	1.15	Portage will use <c>sandbox</c> by default. If you want <c>userpriv</c>, you
281	swift	1.5	should add it to the <c>FEATURES</c> variable. Note that activating
282			<c>userpriv</c> will drop <c>sandbox</c> support, unless you also activate
283			<c>usersandbox</c>:
284			</p>
285
286			<pre caption="Activating userpriv and usersandbox">
287			FEATURES="userpriv usersandbox"
288			</pre>
289
290			<warn>
291			Do <e>not</e> remove <c>sandbox</c> from the <c>FEATURES</c> variable!
292			</warn>
293
294			</body>
295			</subsection>
296			<subsection>
297			<title>Strict Checking</title>
298			<body>
299
300			<p>
301			Portage can be asked to react strongly to possibly dangerous conditions (such as
302			missing or incorrect Manifest files). To activate this strict checking, add the
303			<c>strict</c> keyword to the <c>FEATURES</c> variable:
304			</p>
305
306			<pre caption="Activating strict checking">
307			FEATURES="strict"
308			</pre>
309
310			</body>
311			</subsection>
312	swift	1.7	<subsection>
313			<title>Smart File System Permissions</title>
314			<body>
315
316			<p>
317			Portage can be told to automatically deal with potentially dangerous file
318			permissions that could pose a security risk. It does this by removing the
319			"group" and "other" readable bits on setuid files and removing the "other"
320			readable bit on setgid files in the pre install phase. To activate the
321			smart file permissions, add the <c>sfperms</c> keyword to the
322			<c>FEATURES</c> variable:
323			</p>
324
325			<pre caption="Activating smart file system permissions">
326			FEATURES="sfperms"
327			</pre>
328
329			</body>
330			</subsection>
331	swift	1.5	</section>
332			<section>
333	swift	1.14	<title>SLOT'ed Software Titles</title>
334			<subsection>
335			<title>SLOT ?</title>
336			<body>
337
338			<p>
339			Occasionally you need to have several versions of a software title installed at
340			the same time to satisfy your system's dependencies. Whereas most distributions
341			allow this by having their packages called to the version (such as
342			<c>freetype</c> and <c>freetype2</c>) Portage uses the concept of <e>SLOT</e>s.
343			</p>
344
345			<p>
346			A <e>SLOT</e> is a (part of a) version number that tells Portage that all
347			equally named packages with a different SLOT are able to coexist on the same
348			system. Portage is able to track both branches of a certain package and update
349			them if updates to the respective branches are available.
350			</p>
351
352			<p>
353			When you perform an update Portage will only automatically unmerge the old
354			instance of a package if it uses the same SLOT. This is why kernel sources are
355			never automatically unmerged as their SLOT is the complete version.
356			</p>
357
358			</body>
359			</subsection>
360			</section>
361			<section>
362	swift	1.5	<title>Other Features</title>
363			<subsection>
364			<title>Portage Help</title>
365			<body>
366
367			<p>
368			There are several other keywords you can place in the <c>FEATURES</c> variable.
369			Most of them are targeted towards developers and less interesting for the casual
370			user. If you are interested in learning more about these features (or Portage
371			generally), don't forget to read the <path>make.conf</path> manpage we provide.
372			</p>
373
374			<pre caption="More Portage-related information">
375			# <i>man make.conf</i>
376	swift	1.2	</pre>
377	swift	1.1
378			</body>
379			</subsection>
380			</section>
381			</sections>