en/handbook/hb-portage-diverttree.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-portage-diverttree.xml,v 1.12 2006/10/28 09:17:55 neysx Exp $ -->

<sections>

<abstract>
"Diverting from the Official Tree" gives you some tips and tricks on how to use
your own Portage tree, how to synchronise only the categories you want, inject
packages and more.
</abstract>

<version>1.5</version>
<date>2006-11-01</date>

<section>
<title>Using a Portage Tree Subset</title>
<subsection>
<title>Excluding Packages/Categories</title>
<body>

<p>
You can selectively update certain categories/packages and ignore the other
categories/packages. We achieve this by having <c>rsync</c> exclude
categories/packages during the <c>emerge --sync</c> step.
</p>

<p>
You need to define the name of the file that contains the exclude patterns in
the <c>--exclude-from</c> variable in your <path>/etc/make.conf</path>.
</p>

<pre caption="Defining the exclude file in /etc/make.conf">
PORTAGE_RSYNC_EXTRA_OPTS="--exclude-from=/etc/portage/rsync_excludes"
</pre>

<pre caption="Excluding all games in /etc/portage/rsync_excludes">
games-*/*
</pre>

<p>
Note however that this may lead to dependency issues since new, allowed packages
might depend on new but excluded packages.
</p>

</body>
</subsection>
</section>
<section>
<title>Adding Unofficial Ebuilds</title>
<subsection>
<title>Defining a Portage Overlay Directory</title>
<body>

<p>
You can ask Portage to use ebuilds that are not officially available through the
Portage tree. Create a new directory (for instance
<path>/usr/local/portage</path>) in which you store the 3rd-party ebuilds. Use
the same directory structure as the official Portage tree!
</p>

<p>
Then define PORTDIR_OVERLAY in <path>/etc/make.conf</path> and have it point to
the previously defined directory. When you use Portage now, it will take those
ebuilds into account as well without removing/overwriting those ebuilds the next
time you run <c>emerge --sync</c>.
</p>

</body>
</subsection>
<subsection>
<title>Working with Several Overlays</title>
<body>

<p>
For the powerusers who develop on several overlays, test packages before they
hit the Portage tree or just want to use unofficial ebuilds from various
sources, the <c>app-portage/gentoolkit-dev</c> package brings you
<c>gensync</c>, a tool to help you keep the overlay repositories up to date.
</p>

<p>
With <c>gensync</c> you can update all the repositories at once, or select just
a few of them. Each repository should have a <path>.syncsource</path> file in
the <path>/etc/gensync/</path> configuration directory which contains the
repository location, name, ID, etc.
</p>

<p>
Suppose you have two additional repositories called <c>java</c> (for the
in-development java ebuilds) and <c>entapps</c> (for the applications developed
in-house for your enterprise). You can update those repositories with the
following command:
</p>

<pre caption="Using gensync to update a few repositories">
# <i>gensync java entapps</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Non-Portage Maintained Software</title>
<subsection>
<title>Using Portage with Self-Maintained Software</title>
<body>

<p>
In some cases you want to configure, install and maintain software yourself
without having Portage automate the process for you, even though Portage
can provide the software titles. Known cases are kernel sources and nvidia 
drivers. You can configure Portage so it knows that a certain package is 
manually installed on your system. This process is called <e>injecting</e> and 
supported by Portage through the 
<path>/etc/portage/profile/package.provided</path> file.
</p>

<p>
For instance, if you want to inform Portage about 
<c>vanilla-sources-2.6.11.6</c> which you've installed manually, add the 
following line to <path>/etc/portage/profile/package.provided</path>:
</p>

<pre caption="Example line for package.provided">
sys-kernel/vanilla-sources-2.6.11.6
</pre>

</body>
</subsection>
</section>
</sections>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4			<!-- The content of this document is licensed under the CC-BY-SA license -->
5	neysx	1.11	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6	swift	1.1
7	nightmorph	1.13	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-diverttree.xml,v 1.12 2006/10/28 09:17:55 neysx Exp $ -->
8	swift	1.1
9			<sections>
10	swift	1.2
11	neysx	1.12	<abstract>
12			"Diverting from the Official Tree" gives you some tips and tricks on how to use
13			your own Portage tree, how to synchronise only the categories you want, inject
14			packages and more.
15			</abstract>
16
17	nightmorph	1.13	<version>1.5</version>
18			<date>2006-11-01</date>
19	swift	1.2
20	swift	1.1	<section>
21			<title>Using a Portage Tree Subset</title>
22			<subsection>
23			<title>Excluding Packages/Categories</title>
24			<body>
25
26			<p>
27			You can selectively update certain categories/packages and ignore the other
28			categories/packages. We achieve this by having <c>rsync</c> exclude
29			categories/packages during the <c>emerge --sync</c> step.
30			</p>
31
32			<p>
33	neysx	1.8	You need to define the name of the file that contains the exclude patterns in
34	nightmorph	1.13	the <c>--exclude-from</c> variable in your <path>/etc/make.conf</path>.
35	swift	1.1	</p>
36
37	neysx	1.9	<pre caption="Defining the exclude file in /etc/make.conf">
38	nightmorph	1.13	PORTAGE_RSYNC_EXTRA_OPTS="--exclude-from=/etc/portage/rsync_excludes"
39	neysx	1.8	</pre>
40
41			<pre caption="Excluding all games in /etc/portage/rsync_excludes">
42			games-/
43			</pre>
44
45	swift	1.1	<p>
46			Note however that this may lead to dependency issues since new, allowed packages
47			might depend on new but excluded packages.
48			</p>
49
50			</body>
51			</subsection>
52			</section>
53			<section>
54			<title>Adding Unofficial Ebuilds</title>
55			<subsection>
56			<title>Defining a Portage Overlay Directory</title>
57			<body>
58
59			<p>
60			You can ask Portage to use ebuilds that are not officially available through the
61			Portage tree. Create a new directory (for instance
62			<path>/usr/local/portage</path>) in which you store the 3rd-party ebuilds. Use
63			the same directory structure as the official Portage tree!
64			</p>
65
66			<p>
67			Then define PORTDIR_OVERLAY in <path>/etc/make.conf</path> and have it point to
68			the previously defined directory. When you use Portage now, it will take those
69			ebuilds into account as well without removing/overwriting those ebuilds the next
70			time you run <c>emerge --sync</c>.
71			</p>
72
73			</body>
74			</subsection>
75	swift	1.7	<subsection>
76			<title>Working with Several Overlays</title>
77			<body>
78
79			<p>
80			For the powerusers who develop on several overlays, test packages before they
81			hit the Portage tree or just want to use unofficial ebuilds from various
82			sources, the <c>app-portage/gentoolkit-dev</c> package brings you
83			<c>gensync</c>, a tool to help you keep the overlay repositories up to date.
84			</p>
85
86			<p>
87			With <c>gensync</c> you can update all the repositories at once, or select just
88			a few of them. Each repository should have a <path>.syncsource</path> file in
89			the <path>/etc/gensync/</path> configuration directory which contains the
90			repository location, name, ID, etc.
91			</p>
92
93			<p>
94			Suppose you have two additional repositories called <c>java</c> (for the
95			in-development java ebuilds) and <c>entapps</c> (for the applications developed
96	neysx	1.10	in-house for your enterprise). You can update those repositories with the
97			following command:
98	swift	1.7	</p>
99
100			<pre caption="Using gensync to update a few repositories">
101			# <i>gensync java entapps</i>
102			</pre>
103
104			</body>
105			</subsection>
106	swift	1.1	</section>
107			<section>
108			<title>Non-Portage Maintained Software</title>
109			<subsection>
110			<title>Using Portage with Self-Maintained Software</title>
111			<body>
112
113			<p>
114			In some cases you want to configure, install and maintain software yourself
115			without having Portage automate the process for you, even though Portage
116			can provide the software titles. Known cases are kernel sources and nvidia
117			drivers. You can configure Portage so it knows that a certain package is
118			manually installed on your system. This process is called <e>injecting</e> and
119			supported by Portage through the
120			<path>/etc/portage/profile/package.provided</path> file.
121			</p>
122
123			<p>
124			For instance, if you want to inform Portage about
125	so	1.6	<c>vanilla-sources-2.6.11.6</c> which you've installed manually, add the
126	swift	1.1	following line to <path>/etc/portage/profile/package.provided</path>:
127			</p>
128
129			<pre caption="Example line for package.provided">
130	so	1.5	sys-kernel/vanilla-sources-2.6.11.6
131	swift	1.1	</pre>
132
133			</body>
134			</subsection>
135			</section>
136			</sections>