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: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/hb-working-features.xml,v 1.1 2004/02/16 05:41:21 swift 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, as you now know how to install binary packages if you want, we will
omit the <c>--usepkg</c> option throughout the rest of the Gentoo Handbook.
</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, still inside <path>/etc/make.conf</path>, uncomment the
<c>PORTAGE_TMPDIR</c> line and add the following line at the end
of the file:
</p>

<pre caption="Add an extra, distcc-specific variable to /etc/make.conf">
<comment># Don't forget to uncomment the PORTAGE_TMPDIR variable</comment>
DISTCC_DIR=${PORTAGE_TMPDIR}/portage/.distcc
</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, when you ever 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>Activating Portage Support</title>
<body>

<p>
First, edit <path>/etc/make.conf</path> and alter the <c>FEATURES</c> variable
so that it contains the <c>ccache</c> keyword:
</p>

<pre caption="Editing FEATURES in /etc/make.conf">
FEATURES="ccache"
</pre>

<p>
Next, edit (or create) the <c>CCACHE_SIZE</c> variable (also in
<path>/etc/make.conf</path>) so it contains the amount of diskspace you want to
sacrifice for <c>ccache</c>:
</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>
</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 interesting 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> per 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>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.11	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/hb-working-features.xml,v 1.1 2004/02/16 05:41:21 swift 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			From now on, as you now know how to install binary packages if you want, we will
50			omit the <c>--usepkg</c> option throughout the rest of the Gentoo Handbook.
51			</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			Now, still inside <path>/etc/make.conf</path>, uncomment the
82			<c>PORTAGE_TMPDIR</c> line and add the following line at the end
83			of the file:
84			</p>
85
86			<pre caption="Add an extra, distcc-specific variable to /etc/make.conf">
87			<comment># Don't forget to uncomment the PORTAGE_TMPDIR variable</comment>
88			DISTCC_DIR=${PORTAGE_TMPDIR}/portage/.distcc
89			</pre>
90	swift	1.3
91			<p>
92			Now run <c>distcc-config</c> and enter the list of available DistCC servers. For
93			a simple example we assume that the available DistCC servers are
94			<c>192.168.1.102</c> (the current host), <c>192.168.1.103</c> and
95			<c>192.168.1.104</c> (two "remote" hosts):
96			</p>
97
98			<pre caption="Configuring distcc to use three available DistCC servers">
99			# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
100			</pre>
101
102			<p>
103			Of course, don't forget to run the <c>distccd</c> daemon too:
104			</p>
105
106			<pre caption="Starting the distcc daemon">
107			# <i>/etc/init.d/distccd start</i>
108			</pre>
109
110			<p>
111			Congratulations, your system will now use distributed compiling! For more
112			in-depth information about DistCC and Gentoo, please read our <uri
113			link="/doc/en/distcc.xml">Gentoo DistCC Documentation</uri>.
114			</p>
115	swift	1.2
116	swift	1.1	</body>
117			</subsection>
118			</section>
119			<section>
120	swift	1.4	<title>ccache</title>
121	swift	1.1	<subsection>
122	swift	1.4	<title>What is ccache?</title>
123	swift	1.1	<body>
124
125	swift	1.4	<p>
126			<c>ccache</c> is a fast compiler cache. When you compile a program, it will
127			cache intermediate results so that, when you ever recompile the same program,
128			the compilation time is greatly reduced. In common compilations this can result
129			in 5 to 10 times faster compilation times.
130			</p>
131
132			<p>
133			If you are interested in the ins and outs of <c>ccache</c>, please visit the
134			<uri link="http://ccache.samba.org">ccache homepage</uri>.
135			</p>
136
137	swift	1.1	</body>
138			</subsection>
139			<subsection>
140	swift	1.4	<title>Installing ccache</title>
141	swift	1.1	<body>
142
143	swift	1.4	<p>
144			Installing <c>ccache</c> with Gentoo is a breeze. Just emerge it and you're done
145			:)
146			</p>
147
148			<pre caption="Installing ccache">
149			# <i>emerge ccache</i>
150			</pre>
151
152	swift	1.1	</body>
153			</subsection>
154			<subsection>
155			<title>Activating Portage Support</title>
156			<body>
157	swift	1.4
158			<p>
159			First, edit <path>/etc/make.conf</path> and alter the <c>FEATURES</c> variable
160			so that it contains the <c>ccache</c> keyword:
161			</p>
162
163			<pre caption="Editing FEATURES in /etc/make.conf">
164			FEATURES="ccache"
165			</pre>
166
167			<p>
168			Next, edit (or create) the <c>CCACHE_SIZE</c> variable (also in
169			<path>/etc/make.conf</path>) so it contains the amount of diskspace you want to
170			sacrifice for <c>ccache</c>:
171			</p>
172
173			<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
174			CCACHE_SIZE="2G"
175			</pre>
176
177			<p>
178			As of now, Portage will use <c>ccache</c> to speed up compilations where
179			possible. If you are uncertain that <c>ccache</c> works, you can run <c>ccache
180			-s</c> to view the <c>ccache</c> statistics:
181			</p>
182
183			<pre caption="Viewing ccache statistics">
184			# <i>ccache -s</i>
185			</pre>
186	swift	1.1
187			</body>
188			</subsection>
189			</section>
190			<section>
191			<title>Binary Packages</title>
192			<subsection>
193			<title>Creating binary packages</title>
194			<body>
195
196	swift	1.2	<p>
197	swift	1.8	We have already discussed how to work with prebuilt packages, but how do you
198			create your own prebuilt packages?
199	swift	1.2	</p>
200
201			<p>
202			If the package is already installed, you can use the <c>quickpkg</c> command
203			which will make a tarball of the installed files. This is very interesting for
204			backup purposes!
205			</p>
206
207			<pre caption="Using quickpkg">
208			# <i>quickpkg gnumeric</i>
209			</pre>
210
211			<p>
212			If the package isn't installed yet, you can install it using <c>emerge</c> and
213			ask to build a binary package too. <c>emerge</c> uses the <c>--buildpkg</c>
214			option (<c>-b</c> in short) for this:
215			</p>
216
217			<pre caption="Installing gnumeric and building binary packages too">
218			# <i>emerge --buildpkg gnumeric</i>
219			</pre>
220
221			<p>
222			If you want Portage to do this by default, you should set the <c>buildpkg</c>
223			keyword in the <c>FEATURES</c> variable declared in <path>/etc/make.conf</path>.
224			</p>
225	swift	1.6
226			<pre caption="Automatically creating binary packages">
227			FEATURES="buildpkg"
228			</pre>
229	swift	1.2
230			<p>
231			If you don't want to install the software, but only build the package, you can
232			use the <c>--buildpkgonly</c> option (<c>-B</c> in short):
233			</p>
234
235			<pre caption="Building a binary package for gnumeric">
236			# <i>emerge --buildpkgonly gnumeric</i>
237	swift	1.5	</pre>
238
239			</body>
240			</subsection>
241			</section>
242			<section>
243			<title>Security Related Features</title>
244			<subsection>
245			<title>Sandbox</title>
246			<body>
247
248			<p>
249			While building and installing packages, Portage uses a <e>sandbox</e> to protect
250			your live system. This means that, as long as the package isn't installed on
251			your system, the package cannot touch any file outside the sandbox. This
252			ensures that Portage knows what files are created and modified by a package.
253			</p>
254
255			<p>
256			When the package compilation is finished, Portage will "preinstall" the package
257			in the sandbox, registering what files are placed and where. It will then move
258			those files from the sandbox on your live system.
259			</p>
260
261			</body>
262			</subsection>
263			<subsection>
264			<title>User Privileges</title>
265			<body>
266
267			<p>
268			Portage also supports building packages as non-root user (more precisely, as
269			user "portage", group "portage"). This improves the security during the
270			build process. You can opt to use user privileges with or without sandboxing. Of
271			course, it goes without saying that user privileges and sandboxing is the most
272			preferred method :)
273			</p>
274
275			</body>
276			</subsection>
277			<subsection>
278			<title>Activating sandbox and/or userpriv</title>
279			<body>
280
281			<p>
282			Portage will use <c>sandbox</c> per default. If you want <c>userpriv</c>, you
283			should add it to the <c>FEATURES</c> variable. Note that activating
284			<c>userpriv</c> will drop <c>sandbox</c> support, unless you also activate
285			<c>usersandbox</c>:
286			</p>
287
288			<pre caption="Activating userpriv and usersandbox">
289			FEATURES="userpriv usersandbox"
290			</pre>
291
292			<warn>
293			Do <e>not</e> remove <c>sandbox</c> from the <c>FEATURES</c> variable!
294			</warn>
295
296			</body>
297			</subsection>
298			<subsection>
299			<title>Strict Checking</title>
300			<body>
301
302			<p>
303			Portage can be asked to react strongly to possibly dangerous conditions (such as
304			missing or incorrect Manifest files). To activate this strict checking, add the
305			<c>strict</c> keyword to the <c>FEATURES</c> variable:
306			</p>
307
308			<pre caption="Activating strict checking">
309			FEATURES="strict"
310			</pre>
311
312			</body>
313			</subsection>
314	swift	1.7	<subsection>
315			<title>Smart File System Permissions</title>
316			<body>
317
318			<p>
319			Portage can be told to automatically deal with potentially dangerous file
320			permissions that could pose a security risk. It does this by removing the
321			"group" and "other" readable bits on setuid files and removing the "other"
322			readable bit on setgid files in the pre install phase. To activate the
323			smart file permissions, add the <c>sfperms</c> keyword to the
324			<c>FEATURES</c> variable:
325			</p>
326
327			<pre caption="Activating smart file system permissions">
328			FEATURES="sfperms"
329			</pre>
330
331			</body>
332			</subsection>
333	swift	1.5	</section>
334			<section>
335			<title>Other Features</title>
336			<subsection>
337			<title>Portage Help</title>
338			<body>
339
340			<p>
341			There are several other keywords you can place in the <c>FEATURES</c> variable.
342			Most of them are targeted towards developers and less interesting for the casual
343			user. If you are interested in learning more about these features (or Portage
344			generally), don't forget to read the <path>make.conf</path> manpage we provide.
345			</p>
346
347			<pre caption="More Portage-related information">
348			# <i>man make.conf</i>
349	swift	1.2	</pre>
350	swift	1.1
351			</body>
352			</subsection>
353			</section>
354			</sections>