aboutsummaryrefslogtreecommitdiff
path: root/doc/faq/howdoi.html.part
blob: 9323424aafd62a750f7a4805d1d2b4cf3a53dd01 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->

<h1>FAQ: How do I ...?</h1>

<ul>
    <li><a href="howdoi.html#ccache">Use <code>ccache</code></a></li>
    <li><a href="howdoi.html#distcc">Use <code>distcc</code></a></li>
    <li><a href="howdoi.html#defaultoptions">Specify default options</a></li>
    <li><a href="howdoi.html#removeunneeded">Remove unneeded packages</a></li>
    <li><a href="howdoi.html#unmask">Unmask a Package</a></li>
    <li><a href="howdoi.html#syncfromcvs">Sync from CVS</a></li>
    <li><a href="howdoi.html#syncfromsnapshot">Sync from a Gentoo tree snapshot</a></li>
    <li><a href="howdoi.html#deletedvdb">Recover VDB</a></li>
    <li><a href="howdoi.html#removeportage">Remove Portage from my Gentoo installation</a></li>
    <li><a href="howdoi.html#etcupdate">Update Configuration Files (<code>etc-update</code>)</a></li>
</ul>

<h2 id="ccache">Use <code>ccache</code></h2>

<p>To enable <code>ccache</code>, simply set the relevant variables in your
configuration <code>bashrc</code>:</p>

<pre>
PATH="/usr/lib/ccache/bin/:${PATH}"
CCACHE_DIR="/var/tmp/ccache"
SANDBOX_WRITE="${SANDBOX_WRITE}:${CCACHE_DIR}"
</pre>

<p>You'll need to make sure that your ccache directory has appropriate permissions. Paludis
will sometimes use the <code>paludisbuild</code> user when compiling.
You can set the maxium size of the cache by running (for example)
<code>CCACHE_DIR="/var/tmp/ccache" ccache -M 2G</code> once as root.</p>

<h2 id="distcc">Use <code>distcc</code></h2>

<p>To enable <code>distcc</code>, simply set the relevant variables in your
configuration <code>bashrc</code>:</p>

<pre>
DISTCC_DIR="/var/tmp/paludis/.distcc"
DISTCC_HOSTS="localhost another_host"
PATH="/usr/lib/distcc/bin:${PATH}"
SANDBOX_WRITE="${SANDBOX_WRITE}:${DISTCC_DIR}"
</pre>

<h2 id="defaultoptions">Specify default options</h2>

<p>Often users want to specify certain options by default. Common choices include:</p>

<ul>
    <li><code>--log-level warning</code> (you should <strong>not</strong> use
    <code>silent</code> in this way -- warnings are warnings because you need
    to read them)</li>

    <li><code>--show-reasons summary</code></li>

    <li><code>--resume-command-template $HOME/.paludis-resume-XXXXXX</code></li>

    <li><code>--dl-reinstall-scm weekly</code></li>
</ul>

<p>You can either use a shell alias, or <code>export
    PALUDIS_OPTIONS="--options"</code> (in your environment, not in the
configuration <code>bashrc</code>).</p>

<h2 id="removeunneeded">Remove unneeded packages</h2>

<p>Paludis has three ways of removing unused packages. You should <strong>always</strong>
use <code>--pretend</code> and check the output before proceeding:</p>

<dl>
    <dt><code>--uninstall-unused</code></dt>
    <dd>
    <p>For the purposes of <code>--uninstall-unused</code>, an installed package
    is <em>used</em> if any of these conditions are true:</p>

    <ul>
        <li>It is matched by any dependency specification in any repository's <code>system</code> or
        <code>world</code> set.</li>
        <li>It is depended upon by another used package.</li>
    </ul>

    <p>This action will therefore flag any packages that are no longer in use,
    for example because they were only pulled in by a package that is no longer
    installed, or because they were required by an old version of a package but
    no longer are.</p>
    </dd>

    <dt><code>--uninstall --with-unused-dependencies</code></dt>
    <dd>
    <p>This action will uninstall a package, along with any of its dependencies
    that will no longer be used once the target package is removed.</p>

    <p>This action is recursive, so if <code>foo</code> depends upon <code>bar</code>
    and <code>bar</code> depends upon <code>baz</code>, and if neither <code>bar</code>
    nor <code>baz</code> are otherwise required, uninstalling <code>foo</code> will
    also uninstall <code>bar</code> then <code>baz</code>.</p>
    </dd>

    <dt><code>--uninstall --with-dependencies</code></dt>
    <dd>
    <p>This action will uninstall a package, along with any other package that
    requires this package as a dependency. Again, this action is recursive.</p>
    </dd>
</dl>

<p>Some important notes:</p>

<ul>
    <li>These actions rely upon a package's dependencies being correctly specified.
    They do not attempt to figure out whether a package has unlisted dependencies
    using devious trickery.</li>

    <li>These actions rely upon a package correctly using <code>USE</code> flags. If
    a package was built with, say, <code>-foo</code> whilst <code>libfoo</code> was
    installed, Paludis will not consider the package to require <code>libfoo</code>.
    Unfortunately, some people don't know how to use <code>autoconf</code> correctly,
    so this assumption is currently not entirely safe in all cases.</li>

    <li>Currently a package's build dependencies, as well as its runtime and post
    dependencies, are used when determining needed packages. Experimentation has
    shown that doing otherwise will lead to an awful lot of breakage -- in the future,
    if ebuild authors start being more careful, this behaviour may become
    controllable.</li>

    <li>For the case of any-of (<code>|| ( foo bar )</code>) dependencies, Paludis
    currently does the safe thing and assumes that all available options, if
    installed, are needed. This cannot be changed safely until ebuild authors stop
    abusing <code>|| ( )</code> -- this construct <em>should</em> only be used
    where the dependency can be switched at runtime, but unfortunately it is
    often used to mean "compile against one of these".</li>
</ul>

<h2 id="unmask">Unmask a Package</h2>

<p>First, you need to determine how a package is masked. The easiest way to do
this is to use <code>paludis --query</code>. Then, if you're sure you really
want to unmask a package, and bearing in mind that doing so might break your
system, you need to override the mask. How to do this depends upon the mask
reasons:</p>

<dl>
    <dt>keyword</dt>

    <dd>You need to add an entry to your <code>keywords.conf</code> accepting
    one of the ebuild's keywords. The special <code>-*</code> keyword cannot be
    accepted this way; if an ebuild only has this in its keywords, report it
    to <a href="https://bugs.gentoo.org/show_bug.cgi?id=160519">Gentoo bug
        160519</a> and work around it by using <code>*</code>. An asterisk will
    also accept an ebuild with empty keywords.</dd>

    <dt>user mask</dt>

    <dd>Either remove your <code>package_mask.conf</code> entry or override it
    with <code>package_unmask.conf</code>.</dd>

    <dt>profile mask</dt>

    <dd>Override with <code>package_unmask.conf</code>.</dd>

    <dt>repository mask</dt>

    <dd>Override with <code>package_unmask.conf</code>.</dd>

    <dt>eapi</dt>

    <dd>You cannot override this mask. It indicates either a broken ebuild (if
    <code>EAPI=unknown</code>) or an ebuild not supported by your current version
    of Paludis.</dd>

    <dt>license</dt>

    <dd>Accept the appropriate licences in <code>licenses.conf</code>.</dd>

    <dt>by association</dt>

    <dd>Unmask the associated package. This mask reason is currently only used
    for old style virtuals.</dd>
</dl>

<h2 id="syncfromcvs">Sync from CVS</h2>

<p>Syncing from CVS requires use of either the <code>cvs+pserver</code> or the <code>cvs+ssh</code> protocol.
The syntax for the configuration file line is
<code>sync = cvs+ssh://username@host:/path/to/cvsroot:modulename</code>. As an example,
for syncing with the <code>gentoo</code> repository via CVS, you would use
<code>sync = cvs+ssh://username@cvs.gentoo.org:/var/cvsroot:gentoo-x86</code>.</p>

<h2 id="syncfromsnapshot">Sync from a Gentoo tree snapshot</h2>

<p>Syncing from a tarball requires the <code>tar+http</code>
or <code>tar+ftp</code> protocol.  You must also
specify <code>sync_options = --strip-components=1</code>, as the
Gentoo snapshots place everything under a subdirectory
named <code>portage</code>.  For example:</p>
<pre>
# Replace this with your favourite Gentoo mirror
sync = tar+ftp://my.favourite.mirror/gentoo/snapshots/portage-latest.tar.bz2
sync_options = --strip-components=1
</pre>

<h2 id="deletedvdb">Recover VDB</h2>

<p>If you deleted <code>/var/db/pkg</code> by accident, you're pretty much screwed. So don't do that, and be more
careful next time.</p>

<p>If you deleted <code>/var/db/pkg</code> on purpose, please install OS X and stop pestering us.</p>

<h2 id="removeportage">Remove Portage from my Gentoo installation</h2>

<p>The short answer is that you can't.</p>

<p>Several Gentoo packages wrongly depend on Portage, several depend on Portage because they use it
and there really is no reason to try. Just leave Portage installed.</p>

<h2 id="etcupdate">Update Configuration Files (<code>etc-update</code>)</h2>

<p>Paludis doesn't provide its own version of <code>etc-update</code>. You can just keep using <code>etc-update</code>
or <code>dispatch-conf</code>, since you <a href="howdoi.html#removeportage">can't remove Portage</a>. Or, you can use
one of the workalikes that are available in the tree, such as <code>app-portage/conf-update</code>, or
<code>app-portage/cfg-update</code>.</p>