aboutsummaryrefslogtreecommitdiff
path: root/doc/faq/howdoi.html.part
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-15 11:10:38 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-15 11:10:38 +0000
commit503481c165de28bc0a5db25b7848708df7cb2668 (patch)
tree41eac48b7d7915ca0e7e88bb5dc9ea65225d3b99 /doc/faq/howdoi.html.part
parent8f51d97de6b38b8bc8a9b129baecf4bebd183c7b (diff)
downloadpaludis-503481c165de28bc0a5db25b7848708df7cb2668.tar.gz
paludis-503481c165de28bc0a5db25b7848708df7cb2668.tar.xz
Start reworking docs
Diffstat (limited to 'doc/faq/howdoi.html.part')
-rw-r--r--doc/faq/howdoi.html.part199
1 files changed, 199 insertions, 0 deletions
diff --git a/doc/faq/howdoi.html.part b/doc/faq/howdoi.html.part
new file mode 100644
index 000000000..d9d69a994
--- /dev/null
+++ b/doc/faq/howdoi.html.part
@@ -0,0 +1,199 @@
+<!-- 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>
+</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.</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>--debug-build split</code>, to make debugging easier (at the cost of disk
+ space)</li>
+
+ <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>
+