aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-12-01 12:58:54 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-12-01 12:58:54 +0000
commit79687bd1fa2bed8647968437578a5cfbf06d0e12 (patch)
tree2a5ec299062e20d99b36384de05dc7b9d2ffd64c
parent8846285e62e44f2c79e054a3ad3b0e62b8c0ac12 (diff)
downloadpaludis-79687bd1fa2bed8647968437578a5cfbf06d0e12.tar.gz
paludis-79687bd1fa2bed8647968437578a5cfbf06d0e12.tar.xz
Docs update for the new cache options
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/doc_bootstrap_howto.doxygen4
-rw-r--r--doc/doc_cache_files.doxygen64
-rw-r--r--doc/doc_configuration_files.doxygen4
-rw-r--r--doc/doc_migration_howto.doxygen4
-rw-r--r--doc/header.html1
6 files changed, 79 insertions, 1 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6b15465..2c13c03 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -19,7 +19,8 @@ docfiles = \
doc_configuration_files.doxygen \
doc_migration_howto.doxygen \
doc_known_issues.doxygen \
- doc_programming_with_paludis.doxygen
+ doc_programming_with_paludis.doxygen \
+ doc_cache_files.doxygen
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css $(docfiles) $(tagfiles)
CLEANFILES = *~ html/* html
diff --git a/doc/doc_bootstrap_howto.doxygen b/doc/doc_bootstrap_howto.doxygen
index 166cccf..46d7ada 100644
--- a/doc/doc_bootstrap_howto.doxygen
+++ b/doc/doc_bootstrap_howto.doxygen
@@ -206,6 +206,10 @@ which is set magically, to make the config work both in and outside of a
chroot (this is one of the reasons we have the weird-looking specpath
thing). The Paludis overlay is optional but recommended.
+You will also need to specify <code>names_cache</code> for the Portage format
+repositories and <code>provides_cache</code> for the VDB repositories.
+See \link CacheFiles \endlink .
+
\verbatim
cat <<"END" > /mychroot/etc/paludis/repositories/gentoo.conf
location = ${ROOT}/var/paludis/repositories/gentoo/
diff --git a/doc/doc_cache_files.doxygen b/doc/doc_cache_files.doxygen
new file mode 100644
index 0000000..52c34ff
--- /dev/null
+++ b/doc/doc_cache_files.doxygen
@@ -0,0 +1,64 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/**
+\page CacheFiles Cache Files
+
+\section CacheFilesOverview Overview
+
+This document explains the various cache options that are available for
+Paludis. Correct use of the cache can offer huge speed benefits; however,
+using the different cache options impose various restrictions about
+how other package managers can be used in parallel with Paludis.
+
+\section CacheFilesProvidesCache The Provides Cache
+
+Loading the VDB (information about installed packages) is rather slow on
+systems that have several hundred packages installed. The VDB format cannot
+currently be changed because lots of ebuilds rely upon it working (solutions
+involving hacking in a fake VDB with real data elsewhere are considered too
+hackish to be practical). This is a nuisance, because the VDB needs to be
+fully loaded for most tasks.
+
+Many common tasks only require a full VDB load to check for PROVIDE entries.
+If, instead of forcing a full scan to load PROVIDEs, we cache this data in
+a single file, various common tasks become an order of magnitude faster.
+Paludis supports this option via a key called <code>provides_cache</code>
+in the configuration files for <code>vdb</code> format repositories.
+
+To enable this cache, set <code>provides_cache = ${location}/.cache/provides</code> .
+To disable it, set <code>provides_cache = /var/empty</code> . By default, the
+provide cache is disabled but generates a warning message suggesting that the
+user explicitly enable or disable it.
+
+\warning If you enable the provides cache, and then go on to install or
+ uninstall packages using another package manager, you <b>must</b> run
+ <code>paludis --regenerate-installed-cache</code> before performing
+ <i>any</i> other operation. You should also run this command after turning
+ on the cache for the first time, and if Paludis is interrupted during
+ an install or uninstall.
+
+\section CacheFilesNamesCache The Names Cache
+
+Turning an unqualified package name, like <code>vim</code>, into a qualified
+name, like <code>app-editors/vim</code>, involves scanning every category
+directory. This can take several seconds on a cold filesystem cache. Paludis can
+cache unqualified to qualified name mappings for <code>portage</code> and
+<code>vdb</code> repository formats. This makes certain common tasks much faster.
+
+To enable this cache, set <code>names_cache = ${location}/.cache/names</code> .
+To disable it, set <code>names_cache = /var/empty</code> . By default, the
+names cache is disabled but generates a warning message suggesting that the
+user explicitly enable or disable it.
+
+\warning If you enable the names cache, and then go on to sync or otherwise
+ modify the repository in question manually or with another package manager,
+ you <b>must</b> run <code>paludis --regenerate-installable-cache</code>
+ (for Portage repositories) or <code>paludis
+ --regenerate-installed-cache</code> (for VDB repositories). You should
+ also run this command after turning on the cache for the first time,
+ and if Paludis is interrupted during an install, uninstall or sync.
+
+*/
+
+
+
diff --git a/doc/doc_configuration_files.doxygen b/doc/doc_configuration_files.doxygen
index b7a986e..a3069ee 100644
--- a/doc/doc_configuration_files.doxygen
+++ b/doc/doc_configuration_files.doxygen
@@ -197,6 +197,8 @@ The following keys are available for <code>format = portage</code>:
to <code>/var/empty</code> if there is no metadata cache available.
- <code>write_cache</code>, which can be set to a directory that will be used
to write generated cache files.
+- <code>names_cache</code>, which should be either <code>/var/empty</code> or
+ <code>${location}/.cache/names</code>. See \link CacheFiles \endlink
- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
controls where downloaded files are saved.
- <code>eclassdirs</code> (default: <code>${location}/eclass</code>), which
@@ -228,6 +230,8 @@ The following keys are available for <code>format = vdb</code>:
<code>${ROOT}/var/db/pkg</code>.
- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which is
used as a temporary directory when carrying out uninstall operations,
+- <code>provides_cache</code>, which should be either <code>/var/empty</code> or
+ <code>${location}/.cache/provides</code>. See \link CacheFiles \endlink
- <code>world</code> (default: <code>${location}/world</code>), which is used
for the world file.
diff --git a/doc/doc_migration_howto.doxygen b/doc/doc_migration_howto.doxygen
index c64592a..d6d104f 100644
--- a/doc/doc_migration_howto.doxygen
+++ b/doc/doc_migration_howto.doxygen
@@ -169,6 +169,10 @@ Set up your repository files. Do not tinker with the VDB location, it
<code>/usr/portage</code> for the main tree because sticking data that gets
changed on <code>/usr</code> is silly.
+You will also need to specify <code>names_cache</code> for the Portage format
+repositories and <code>provides_cache</code> for the VDB repositories.
+See \link CacheFiles \endlink .
+
\verbatim
cat <<"END" > /etc/paludis/repositories/gentoo.conf
location = /var/paludis/repositories/gentoo/
diff --git a/doc/header.html b/doc/header.html
index 8c269bd..4ffaa72 100644
--- a/doc/header.html
+++ b/doc/header.html
@@ -22,6 +22,7 @@
<a class="qindex" href="MigrationHowto.html">Migration&nbsp;Howto</a> |
<a class="qindex" href="KnownIssues.html">Known&nbsp;Issues&nbsp;and&nbsp;Non-Issues</a>&nbsp;(<strong>Important</strong>) |
<a class="qindex" href="ConfigurationFiles.html">Configuration&nbsp;Files</a> |
+ <a class="qindex" href="CacheFiles.html">Cache&nbsp;Files</a> |
<a class="qindex" href="PortageDifferences.html">Portage&nbsp;Differences</a> |
<a class="qindex" href="CodingStandards.html">Coding&nbsp;Standards</a> |
<a class="qindex" href="ProgrammingWithPaludis.html">Programming&nbsp;with&nbsp;Paludis</a> ]