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.26 2004/11/26 22:06:43 swift Exp $ -->

<sections>

<version>1.24</version>
<date>2005-01-22</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. 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:
</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 PATH variable 
(before <path>/usr/bin</path>). This can be accomplished by editing 
<path>/etc/profile</path>:
</p>

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