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/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.30 2005/10/09 15:55:34 swift Exp $ -->

<sections>

<version>1.28</version>
<date>2005-12-01</date>

<section>
<title>Portage Features</title>
<body>

<p>
Portage has several additional features that makes your Gentoo experience even
better. Many of these features rely on certain software tools that improve
performance, reliability, security, ...
</p>

<p>
To enable or disable certain Portage features you need to edit
<path>/etc/make.conf</path>'s <c>FEATURES</c> variable which contains the
various feature keywords, separated by white space. In several cases you
will also need to install the additional tool on which the feature relies.
</p>

<p>
Not all features that Portage supports are listed here. For a full overview,
please consult the <path>make.conf</path> man page:
</p>

<pre caption="Consulting the make.conf man page">
$ <i>man make.conf</i>
</pre>

<p>
To find out what FEATURES are default set, run <c>emerge --info</c> and search
for the FEATURES variable or grep it out:
</p>

<pre caption="Finding out the FEATURES that are already set">
$ <i>emerge --info | grep FEATURES</i>
</pre>

</body>
</section>
<section>
<title>Distributed Compiling</title>
<subsection>
<title>Using 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 information about <c>distcc</c> (and 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 USE
variable. However, if you don't use Gnome and would still like to have the
monitor then you should put 'gtk' in your USE variable.
</p>

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

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

<p>
Add <c>distcc</c> to the FEATURES variable inside <path>/etc/make.conf</path>.
Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in
"-jX" with X the number of CPUs that run <c>distccd</c> (including the current
host) plus one, but you might have better results with other numbers.
</p>

<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 192.168.1.102
(the current host), 192.168.1.103 and 192.168.1.104 (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>
Don't forget to run the <c>distccd</c> daemon as well:
</p>

<pre caption="Starting the distccd daemons">
# <i>rc-update add distccd default</i>
# <i>/etc/init.d/distccd start</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Caching Compilation</title>
<subsection>
<title>About 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 ccache, please visit the 
<uri link="http://ccache.samba.org">ccache homepage</uri>.
</p>

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

<p>
To install <c>ccache</c>, run <c>emerge ccache</c>:
</p>

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

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

<p>
Open <path>/etc/make.conf</path> and add <c>ccache</c> to the FEATURES variable.
Next, add a new variable called CCACHE_SIZE and set it to "2G":
</p>

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

<p>
To check if ccache functions, ask ccache to provide you with its statistics.
Because Portage uses a different ccache home directory, you need to set the
<c>CCACHE_DIR</c> variable as well:
</p>

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

<p>
The <path>/var/tmp/ccache</path> location is Portage' default ccache home
directory; if you want to alter this setting you can set the <c>CCACHE_DIR</c>
variable in <path>/etc/make.conf</path>.
</p>

<p>
However, if you would run <c>ccache</c>, it would use the default location of
<path>${HOME}/.ccache</path>, which is why you needed to set the
<c>CCACHE_DIR</c> variable when asking for the (Portage) ccache statistics.
</p>

</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 PATH variable 
(before <path>/usr/bin</path>). This can be accomplished by editing
<path>/etc/env.d/00basic</path>, which is the first environment file that
defines the <c>PATH</c> variable:
</p>

<pre caption="Editing /etc/env.d/00basic">
PATH="<i>/usr/lib/ccache/bin</i>:/opt/bin"
</pre>

</body>
</subsection>
</section>
<section>
<title>Binary Package Support</title>
<subsection>
<title>Creating Prebuilt Packages</title>
<body>

<p>
Portage supports the installation of prebuilt packages. Even though Gentoo does
not provide prebuilt packages by itself (except for the GRP snapshots) Portage
can be made fully aware of prebuilt packages.
</p>

<p>
To create a prebuilt package you can use <c>quickpkg</c> if the package is
already installed on your system, or <c>emerge</c> with the <c>--buildpkg</c> or
<c>--buildpkgonly</c> options.
</p>

<p>
If you want Portage to create prebuilt packages of every single package you
install, add <c>buildpkg</c> to the FEATURES variable.
</p>

<p>
More extended support for creating prebuilt package sets can be obtained with
<c>catalyst</c>. For more information on catalyst please read the <uri
link="/proj/en/releng/catalyst/2.x/reference.xml">Catalyst Reference 
Manual</uri> and <uri link="/proj/en/releng/catalyst/faq.xml">Catalyst 
Frequently Asked Questions</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Installing Prebuilt Packages</title>
<body>

<p>
Although Gentoo doesn't provide one, you can create a central repository where 
you store prebuilt packages. If you want to use this repository, you need to 
make Portage aware of it by having the PORTAGE_BINHOST variable point to
it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:
</p>

<pre caption="Setting PORTAGE_BINHOST in /etc/make.conf">
PORTAGE_BINHOST="ftp://buildhost/gentoo"
</pre>

<p>
When you want to install a prebuilt package, add the <c>--getbinpkg</c> option
to the emerge command alongside of the <c>--usepkg</c> option. The former tells
emerge to download the prebuilt package from the previously defined server
while the latter asks emerge to try to install the prebuilt package first before
fetching the sources and compiling it.
</p>

<p>
For instance, to install <c>gnumeric</c> with prebuilt packages:
</p>

<pre caption="Installing the gnumeric prebuilt package">
# <i>emerge --usepkg --getbinpkg gnumeric</i>
</pre>

<p>
More information about emerge's prebuilt package options can be found in the
emerge man page:
</p>

<pre caption="Reading the emerge man page">
$ <i>man emerge</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	swift	1.29	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6	swift	1.1
7	swift	1.31	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.30 2005/10/09 15:55:34 swift Exp $ -->
8	swift	1.1
9			<sections>
10	swift	1.23
11	swift	1.31	<version>1.28</version>
12			<date>2005-12-01</date>
13	swift	1.23
14	swift	1.1	<section>
15	swift	1.19	<title>Portage Features</title>
16			<body>
17
18			<p>
19			Portage has several additional features that makes your Gentoo experience even
20			better. Many of these features rely on certain software tools that improve
21			performance, reliability, security, ...
22			</p>
23
24			<p>
25			To enable or disable certain Portage features you need to edit
26	swift	1.28	<path>/etc/make.conf</path>'s <c>FEATURES</c> variable which contains the
27			various feature keywords, separated by white space. In several cases you
28	swift	1.19	will also need to install the additional tool on which the feature relies.
29			</p>
30
31			<p>
32			Not all features that Portage supports are listed here. For a full overview,
33	swift	1.21	please consult the <path>make.conf</path> man page:
34	swift	1.19	</p>
35
36	swift	1.21	<pre caption="Consulting the make.conf man page">
37	swift	1.19	$ <i>man make.conf</i>
38			</pre>
39
40			<p>
41	cam	1.27	To find out what FEATURES are default set, run <c>emerge --info</c> and search
42			for the FEATURES variable or grep it out:
43	swift	1.19	</p>
44
45			<pre caption="Finding out the FEATURES that are already set">
46	cam	1.27	$ <i>emerge --info \| grep FEATURES</i>
47	swift	1.19	</pre>
48
49			</body>
50			</section>
51			<section>
52			<title>Distributed Compiling</title>
53	swift	1.1	<subsection>
54	swift	1.19	<title>Using distcc</title>
55	swift	1.1	<body>
56
57	swift	1.2	<p>
58	swift	1.19	<c>distcc</c> is a program to distribute compilations across several, not
59	swift	1.2	necessarily identical, machines on a network. The <c>distcc</c> client sends all
60	swift	1.19	necessary information to the available distcc servers (running <c>distccd</c>)
61			so they can compile pieces of source code for the client. The net result is a
62	swift	1.2	faster compilation time.
63			</p>
64
65			<p>
66	swift	1.19	You can find more information about <c>distcc</c> (and how to have it work
67			with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo Distcc
68			Documentation</uri>.
69	swift	1.2	</p>
70
71	swift	1.1	</body>
72			</subsection>
73			<subsection>
74	swift	1.19	<title>Installing distcc</title>
75	swift	1.1	<body>
76
77	swift	1.2	<p>
78			Distcc ships with a graphical monitor to monitor tasks that your computer is
79	swift	1.19	sending away for compilation. If you use Gnome then put 'gnome' in your USE
80			variable. However, if you don't use Gnome and would still like to have the
81			monitor then you should put 'gtk' in your USE variable.
82	swift	1.2	</p>
83
84	swift	1.19	<pre caption="Installing distcc">
85	swift	1.2	# <i>emerge distcc</i>
86			</pre>
87
88	swift	1.1	</body>
89			</subsection>
90			<subsection>
91			<title>Activating Portage Support</title>
92			<body>
93
94	swift	1.2	<p>
95	swift	1.19	Add <c>distcc</c> to the FEATURES variable inside <path>/etc/make.conf</path>.
96			Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in
97			"-jX" with X the number of CPUs that run <c>distccd</c> (including the current
98			host) plus one, but you might have better results with other numbers.
99	swift	1.2	</p>
100
101			<p>
102	swift	1.19	Now run <c>distcc-config</c> and enter the list of available distcc servers. For
103			a simple example we assume that the available DistCC servers are 192.168.1.102
104			(the current host), 192.168.1.103 and 192.168.1.104 (two "remote" hosts):
105	swift	1.2	</p>
106
107	swift	1.19	<pre caption="Configuring distcc to use three available distcc servers">
108	swift	1.3	# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
109			</pre>
110
111			<p>
112	swift	1.19	Don't forget to run the <c>distccd</c> daemon as well:
113	swift	1.3	</p>
114
115	swift	1.19	<pre caption="Starting the distccd daemons">
116			# <i>rc-update add distccd default</i>
117	swift	1.3	# <i>/etc/init.d/distccd start</i>
118			</pre>
119
120	swift	1.1	</body>
121			</subsection>
122			</section>
123			<section>
124	swift	1.19	<title>Caching Compilation</title>
125	swift	1.1	<subsection>
126	swift	1.19	<title>About ccache</title>
127	swift	1.1	<body>
128
129	swift	1.4	<p>
130	swift	1.19	<c>ccache</c> is a fast compiler cache. When you compile a program, it will
131			cache intermediate results so that, whenever you recompile the same program, the
132			compilation time is greatly reduced. In common compilations this can result in 5
133			to 10 times faster compilation times.
134	swift	1.4	</p>
135
136			<p>
137	swift	1.19	If you are interested in the ins and outs of ccache, please visit the
138	swift	1.4	<uri link="http://ccache.samba.org">ccache homepage</uri>.
139			</p>
140
141	swift	1.1	</body>
142			</subsection>
143			<subsection>
144	swift	1.4	<title>Installing ccache</title>
145	swift	1.1	<body>
146
147	swift	1.4	<p>
148	swift	1.19	To install <c>ccache</c>, run <c>emerge ccache</c>:
149	swift	1.4	</p>
150
151			<pre caption="Installing ccache">
152			# <i>emerge ccache</i>
153			</pre>
154
155	swift	1.1	</body>
156			</subsection>
157			<subsection>
158	swift	1.19	<title>Activating Portage Support</title>
159	swift	1.1	<body>
160	swift	1.4
161			<p>
162	swift	1.19	Open <path>/etc/make.conf</path> and add <c>ccache</c> to the FEATURES variable.
163			Next, add a new variable called CCACHE_SIZE and set it to "2G":
164	swift	1.4	</p>
165
166			<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
167			CCACHE_SIZE="2G"
168			</pre>
169
170			<p>
171	swift	1.30	To check if ccache functions, ask ccache to provide you with its statistics.
172			Because Portage uses a different ccache home directory, you need to set the
173			<c>CCACHE_DIR</c> variable as well:
174	swift	1.4	</p>
175
176			<pre caption="Viewing ccache statistics">
177	swift	1.30	# <i>CCACHE_DIR="/var/tmp/ccache" ccache -s</i>
178	swift	1.4	</pre>
179	swift	1.1
180	swift	1.30	<p>
181			The <path>/var/tmp/ccache</path> location is Portage' default ccache home
182			directory; if you want to alter this setting you can set the <c>CCACHE_DIR</c>
183			variable in <path>/etc/make.conf</path>.
184			</p>
185
186			<p>
187			However, if you would run <c>ccache</c>, it would use the default location of
188			<path>${HOME}/.ccache</path>, which is why you needed to set the
189			<c>CCACHE_DIR</c> variable when asking for the (Portage) ccache statistics.
190			</p>
191
192	swift	1.1	</body>
193			</subsection>
194	swift	1.12	<subsection>
195	swift	1.19	<title>Using ccache for non-Portage C Compiling</title>
196	swift	1.12	<body>
197
198			<p>
199			If you would like to use ccache for non-Portage compilations, add
200	swift	1.19	<path>/usr/lib/ccache/bin</path> to the beginning of your PATH variable
201	swift	1.29	(before <path>/usr/bin</path>). This can be accomplished by editing
202			<path>/etc/env.d/00basic</path>, which is the first environment file that
203			defines the <c>PATH</c> variable:
204	swift	1.12	</p>
205
206	swift	1.29	<pre caption="Editing /etc/env.d/00basic">
207			PATH="<i>/usr/lib/ccache/bin</i>:/opt/bin"
208	swift	1.12	</pre>
209
210			</body>
211			</subsection>
212	swift	1.1	</section>
213			<section>
214	swift	1.19	<title>Binary Package Support</title>
215	swift	1.1	<subsection>
216	swift	1.19	<title>Creating Prebuilt Packages</title>
217	swift	1.1	<body>
218
219	swift	1.2	<p>
220	swift	1.19	Portage supports the installation of prebuilt packages. Even though Gentoo does
221			not provide prebuilt packages by itself (except for the GRP snapshots) Portage
222			can be made fully aware of prebuilt packages.
223	swift	1.2	</p>
224
225			<p>
226	swift	1.19	To create a prebuilt package you can use <c>quickpkg</c> if the package is
227			already installed on your system, or <c>emerge</c> with the <c>--buildpkg</c> or
228			<c>--buildpkgonly</c> options.
229	swift	1.2	</p>
230
231			<p>
232	swift	1.19	If you want Portage to create prebuilt packages of every single package you
233			install, add <c>buildpkg</c> to the FEATURES variable.
234	swift	1.2	</p>
235
236			<p>
237	swift	1.19	More extended support for creating prebuilt package sets can be obtained with
238			<c>catalyst</c>. For more information on catalyst please read the <uri
239	swift	1.31	link="/proj/en/releng/catalyst/2.x/reference.xml">Catalyst Reference
240			Manual</uri> and <uri link="/proj/en/releng/catalyst/faq.xml">Catalyst
241			Frequently Asked Questions</uri>.
242	swift	1.2	</p>
243	swift	1.6
244	swift	1.5	</body>
245			</subsection>
246			<subsection>
247	swift	1.19	<title>Installing Prebuilt Packages</title>
248	swift	1.5	<body>
249
250			<p>
251	swift	1.19	Although Gentoo doesn't provide one, you can create a central repository where
252			you store prebuilt packages. If you want to use this repository, you need to
253			make Portage aware of it by having the PORTAGE_BINHOST variable point to
254			it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:
255	swift	1.5	</p>
256
257	swift	1.19	<pre caption="Setting PORTAGE_BINHOST in /etc/make.conf">
258			PORTAGE_BINHOST="ftp://buildhost/gentoo"
259	swift	1.5	</pre>
260
261			<p>
262	swift	1.19	When you want to install a prebuilt package, add the <c>--getbinpkg</c> option
263			to the emerge command alongside of the <c>--usepkg</c> option. The former tells
264			emerge to download the prebuilt package from the previously defined server
265			while the latter asks emerge to try to install the prebuilt package first before
266			fetching the sources and compiling it.
267	swift	1.5	</p>
268
269	swift	1.7	<p>
270	swift	1.19	For instance, to install <c>gnumeric</c> with prebuilt packages:
271	swift	1.7	</p>
272
273	swift	1.19	<pre caption="Installing the gnumeric prebuilt package">
274			# <i>emerge --usepkg --getbinpkg gnumeric</i>
275	swift	1.7	</pre>
276
277	swift	1.5	<p>
278	swift	1.19	More information about emerge's prebuilt package options can be found in the
279	swift	1.21	emerge man page:
280	swift	1.5	</p>
281
282	swift	1.21	<pre caption="Reading the emerge man page">
283	swift	1.19	$ <i>man emerge</i>
284	swift	1.2	</pre>
285	swift	1.1
286			</body>
287			</subsection>
288			</section>
289			</sections>