en/handbook/hb-working-features.xml

<!-- 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/hb-working-features.xml,v 1.4 2003/11/28 16:15:53 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 sourcecode 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 prebuild packages, but how do you
create your own prebuild 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>

<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>
</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	<!-- The content of this document is licensed under the CC-BY-SA license -->
2	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3
4	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.4 2003/11/28 16:15:53 swift Exp $ -->
5
6	<sections>
7	<section>
8	<title>DistCC</title>
9	<subsection>
10	<title>What is DistCC?</title>
11	<body>
12
13	<p>
14	<c>distcc</c> is a program to distribute compilations across several, not
15	necessarily identical, machines on a network. The <c>distcc</c> client sends all
16	necessary information to the available DistCC servers (running <c>distccd</c>)
17	so they can compile pieces of sourcecode for the client. The net result is a
18	faster compilation time.
19	</p>
20
21	<p>
22	You can find more elaborate information about <c>distcc</c> (and information on
23	how to have it work with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo
24	Distcc Documentation</uri>.
25	</p>
26
27	</body>
28	</subsection>
29	<subsection>
30	<title>Installing DistCC</title>
31	<body>
32
33	<p>
34	Distcc ships with a graphical monitor to monitor tasks that your computer is
35	sending away for compilation. If you use Gnome then put 'gnome' in your
36	<c>USE</c> setting. However, if you don't use Gnome and would still like to have
37	the monitor then you should put 'gtk' in your <c>USE</c> setting.
38	</p>
39
40	<p>
41	Installing distcc is, as is with all software available through Gentoo's
42	Portage, extremely easy:
43	</p>
44
45	<note>
46	From now on, as you now know how to install binary packages if you want, we will
47	omit the <c>--usepkg</c> option throughout the rest of the Gentoo Handbook.
48	</note>
49
50	<pre caption="Installing Distcc">
51	# <i>emerge distcc</i>
52	</pre>
53
54	</body>
55	</subsection>
56	<subsection>
57	<title>Activating Portage Support</title>
58	<body>
59
60	<p>
61	Well, if installation is easy, the rest should be easy too :) So let us quickly
62	activate the Portage support for <c>distcc</c>.
63	</p>
64
65	<p>
66	First, open <path>/etc/make.conf</path> and edit the <c>FEATURES</c> variable so
67	it contains the <c>distcc</c> keyword. Next, edit the <c>MAKEOPTS</c> variable
68	so it reads <c>-jX</c> with <c>X</c> the number of CPUs that run <c>distccd</c>
69	(including the current host) plus one:
70	</p>
71
72	<pre caption="Possible MAKEOPTS setting in /etc/make.conf">
73	<comment># Suppose you have 2 single-CPU distccd hosts excluding this host:</comment>
74	MAKEOPTS="-j4"
75	</pre>
76
77	<p>
78	Now, still inside <path>/etc/make.conf</path>, uncomment the
79	<c>PORTAGE_TMPDIR</c> line and add the following line at the end
80	of the file:
81	</p>
82
83	<pre caption="Add an extra, distcc-specific variable to /etc/make.conf">
84	<comment># Don't forget to uncomment the PORTAGE_TMPDIR variable</comment>
85	DISTCC_DIR=${PORTAGE_TMPDIR}/portage/.distcc
86	</pre>
87
88	<p>
89	Now run <c>distcc-config</c> and enter the list of available DistCC servers. For
90	a simple example we assume that the available DistCC servers are
91	<c>192.168.1.102</c> (the current host), <c>192.168.1.103</c> and
92	<c>192.168.1.104</c> (two "remote" hosts):
93	</p>
94
95	<pre caption="Configuring distcc to use three available DistCC servers">
96	# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
97	</pre>
98
99	<p>
100	Of course, don't forget to run the <c>distccd</c> daemon too:
101	</p>
102
103	<pre caption="Starting the distcc daemon">
104	# <i>/etc/init.d/distccd start</i>
105	</pre>
106
107	<p>
108	Congratulations, your system will now use distributed compiling! For more
109	in-depth information about DistCC and Gentoo, please read our <uri
110	link="/doc/en/distcc.xml">Gentoo DistCC Documentation</uri>.
111	</p>
112
113	</body>
114	</subsection>
115	</section>
116	<section>
117	<title>ccache</title>
118	<subsection>
119	<title>What is ccache?</title>
120	<body>
121
122	<p>
123	<c>ccache</c> is a fast compiler cache. When you compile a program, it will
124	cache intermediate results so that, when you ever recompile the same program,
125	the compilation time is greatly reduced. In common compilations this can result
126	in 5 to 10 times faster compilation times.
127	</p>
128
129	<p>
130	If you are interested in the ins and outs of <c>ccache</c>, please visit the
131	<uri link="http://ccache.samba.org">ccache homepage</uri>.
132	</p>
133
134	</body>
135	</subsection>
136	<subsection>
137	<title>Installing ccache</title>
138	<body>
139
140	<p>
141	Installing <c>ccache</c> with Gentoo is a breeze. Just emerge it and you're done
142	:)
143	</p>
144
145	<pre caption="Installing ccache">
146	# <i>emerge ccache</i>
147	</pre>
148
149	</body>
150	</subsection>
151	<subsection>
152	<title>Activating Portage Support</title>
153	<body>
154
155	<p>
156	First, edit <path>/etc/make.conf</path> and alter the <c>FEATURES</c> variable
157	so that it contains the <c>ccache</c> keyword:
158	</p>
159
160	<pre caption="Editing FEATURES in /etc/make.conf">
161	FEATURES="ccache"
162	</pre>
163
164	<p>
165	Next, edit (or create) the <c>CCACHE_SIZE</c> variable (also in
166	<path>/etc/make.conf</path>) so it contains the amount of diskspace you want to
167	sacrifice for <c>ccache</c>:
168	</p>
169
170	<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
171	CCACHE_SIZE="2G"
172	</pre>
173
174	<p>
175	As of now, Portage will use <c>ccache</c> to speed up compilations where
176	possible. If you are uncertain that <c>ccache</c> works, you can run <c>ccache
177	-s</c> to view the <c>ccache</c> statistics:
178	</p>
179
180	<pre caption="Viewing ccache statistics">
181	# <i>ccache -s</i>
182	</pre>
183
184	</body>
185	</subsection>
186	</section>
187	<section>
188	<title>Binary Packages</title>
189	<subsection>
190	<title>Creating binary packages</title>
191	<body>
192
193	<p>
194	We have already discussed how to work with prebuild packages, but how do you
195	create your own prebuild packages?
196	</p>
197
198	<p>
199	If the package is already installed, you can use the <c>quickpkg</c> command
200	which will make a tarball of the installed files. This is very interesting for
201	backup purposes!
202	</p>
203
204	<pre caption="Using quickpkg">
205	# <i>quickpkg gnumeric</i>
206	</pre>
207
208	<p>
209	If the package isn't installed yet, you can install it using <c>emerge</c> and
210	ask to build a binary package too. <c>emerge</c> uses the <c>--buildpkg</c>
211	option (<c>-b</c> in short) for this:
212	</p>
213
214	<pre caption="Installing gnumeric and building binary packages too">
215	# <i>emerge --buildpkg gnumeric</i>
216	</pre>
217
218	<p>
219	If you want Portage to do this by default, you should set the <c>buildpkg</c>
220	keyword in the <c>FEATURES</c> variable declared in <path>/etc/make.conf</path>.
221	</p>
222
223	<p>
224	If you don't want to install the software, but only build the package, you can
225	use the <c>--buildpkgonly</c> option (<c>-B</c> in short):
226	</p>
227
228	<pre caption="Building a binary package for gnumeric">
229	# <i>emerge --buildpkgonly gnumeric</i>
230	</pre>
231
232	</body>
233	</subsection>
234	</section>
235	<section>
236	<title>Security Related Features</title>
237	<subsection>
238	<title>Sandbox</title>
239	<body>
240
241	<p>
242	While building and installing packages, Portage uses a <e>sandbox</e> to protect
243	your live system. This means that, as long as the package isn't installed on
244	your system, the package cannot touch any file outside the sandbox. This
245	ensures that Portage knows what files are created and modified by a package.
246	</p>
247
248	<p>
249	When the package compilation is finished, Portage will "preinstall" the package
250	in the sandbox, registering what files are placed and where. It will then move
251	those files from the sandbox on your live system.
252	</p>
253
254	</body>
255	</subsection>
256	<subsection>
257	<title>User Privileges</title>
258	<body>
259
260	<p>
261	Portage also supports building packages as non-root user (more precisely, as
262	user "portage", group "portage"). This improves the security during the
263	build process. You can opt to use user privileges with or without sandboxing. Of
264	course, it goes without saying that user privileges and sandboxing is the most
265	preferred method :)
266	</p>
267
268	</body>
269	</subsection>
270	<subsection>
271	<title>Activating sandbox and/or userpriv</title>
272	<body>
273
274	<p>
275	Portage will use <c>sandbox</c> per default. If you want <c>userpriv</c>, you
276	should add it to the <c>FEATURES</c> variable. Note that activating
277	<c>userpriv</c> will drop <c>sandbox</c> support, unless you also activate
278	<c>usersandbox</c>:
279	</p>
280
281	<pre caption="Activating userpriv and usersandbox">
282	FEATURES="userpriv usersandbox"
283	</pre>
284
285	<warn>
286	Do <e>not</e> remove <c>sandbox</c> from the <c>FEATURES</c> variable!
287	</warn>
288
289	</body>
290	</subsection>
291	<subsection>
292	<title>Strict Checking</title>
293	<body>
294
295	<p>
296	Portage can be asked to react strongly to possibly dangerous conditions (such as
297	missing or incorrect Manifest files). To activate this strict checking, add the
298	<c>strict</c> keyword to the <c>FEATURES</c> variable:
299	</p>
300
301	<pre caption="Activating strict checking">
302	FEATURES="strict"
303	</pre>
304
305	</body>
306	</subsection>
307	</section>
308	<section>
309	<title>Other Features</title>
310	<subsection>
311	<title>Portage Help</title>
312	<body>
313
314	<p>
315	There are several other keywords you can place in the <c>FEATURES</c> variable.
316	Most of them are targeted towards developers and less interesting for the casual
317	user. If you are interested in learning more about these features (or Portage
318	generally), don't forget to read the <path>make.conf</path> manpage we provide.
319	</p>
320
321	<pre caption="More Portage-related information">
322	# <i>man make.conf</i>
323	</pre>
324
325	</body>
326	</subsection>
327	</section>
328	</sections>