aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-01 19:45:19 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-01 19:45:19 +0000
commitec7a26fd248b15d0014e5687f0355da7fc042df6 (patch)
tree6b00843924def483452d4c7d226a26cf2e1bb175
parente3098b9e7c78568e603429476ae0445185e7c1b3 (diff)
downloadpaludis-ec7a26fd248b15d0014e5687f0355da7fc042df6.tar.gz
paludis-ec7a26fd248b15d0014e5687f0355da7fc042df6.tar.xz
More docs work
-rw-r--r--doc/Makefile.am20
-rw-r--r--doc/doc_authors.doxygen9
-rw-r--r--doc/doc_changelog.doxygen10
-rw-r--r--doc/doc_known_issues.doxygen93
-rw-r--r--doc/doc_licence.doxygen12
-rw-r--r--doc/doc_migration_howto.doxygen247
-rw-r--r--doc/doc_news.doxygen11
-rw-r--r--doc/footer.html2
-rw-r--r--doc/htmlfooter.html2
-rw-r--r--doc/migration.html.skel208
10 files changed, 221 insertions, 393 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ad0bd0f..b906079 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -10,15 +10,9 @@ docfiles = \
doc_coding_standards.doxygen \
doc_namespaces.doxygen \
doc_references.doxygen \
- doc_licence.doxygen \
- doc_authors.doxygen \
doc_bootstrap_howto.doxygen \
- doc_changelog.doxygen \
doc_portage_differences.doxygen \
- doc_news.doxygen \
doc_configuration_files.doxygen \
- doc_migration_howto.doxygen \
- doc_known_issues.doxygen \
doc_programming_with_paludis.doxygen \
doc_cache_files.doxygen
@@ -28,15 +22,16 @@ htmlfiles = \
changelog.html \
licence.html \
authors.html \
- faq.html
+ faq.html \
+ migration.html
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css \
$(docfiles) $(tagfiles) $(htmlfiles) htaccess \
news.html.skel index.html.skel changelog.html.skel licence.html.skel authors.html.skel \
- faq.html.skel htmlheader.html htmlfooter.html
+ faq.html.skel htmlheader.html htmlfooter.html migration.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
- cleannews cleanchangelog cleanauthors cleanfaqtoc
+ migration.html cleannews cleanchangelog cleanauthors cleanfaqtoc
MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
@@ -138,6 +133,13 @@ index.html : index.html.skel htmlheader.html htmlfooter.html
-e '/@FOOTER@/d' \
< index.html.skel > index.html
+migration.html : migration.html.skel htmlheader.html htmlfooter.html
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ < migration.html.skel > migration.html
+
faq.html : faq.html.skel htmlheader.html htmlfooter.html cleanfaqtoc
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
diff --git a/doc/doc_authors.doxygen b/doc/doc_authors.doxygen
deleted file mode 100644
index 54066fc..0000000
--- a/doc/doc_authors.doxygen
+++ /dev/null
@@ -1,9 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page PaludisAuthors Paludis Authors
-
-\verbinclude AUTHORS
-
-*/
-
diff --git a/doc/doc_changelog.doxygen b/doc/doc_changelog.doxygen
deleted file mode 100644
index 5bb1c0b..0000000
--- a/doc/doc_changelog.doxygen
+++ /dev/null
@@ -1,10 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page PaludisChangeLog Paludis ChangeLog
-
-\verbinclude ChangeLog
-
-*/
-
-
diff --git a/doc/doc_known_issues.doxygen b/doc/doc_known_issues.doxygen
deleted file mode 100644
index c62c2a5..0000000
--- a/doc/doc_known_issues.doxygen
+++ /dev/null
@@ -1,93 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page KnownIssues Known Issues and Non-Issues
-
-\section KnownIssuesMain About the issues
-
-This document describes some of the more commonly encountered problems, issues
-and things that aren't bugs but might look like they are. Pestering anyone about
-these is liable to get you hurt.
-
-\section KnownIssuesNonIssuesMain About the non-issues
-
-This document also describes some things that are not bugs or missing functionality. Pestering anyone about these is liable to get you hurt a lot.
-
-\section KnownIssuesPackages Packages
-
-\subsection KnownIssuesUdev sys-fs/udev
-
-Problem: <code>sys-fs/udev</code> will fail at the merge stage.
-
-Workaround: Use <code>~arch</code> for this package. We don't support merging
-fancy things like device files. Neither does Portage, but Portage isn't well
-behaved enough to error out on it either -- it just does something silly.
-
-\subsection KnownIssuesKDE Some KDE libraries are broken on some amd64 profiles
-
-Problem: Various KDE applications install libraries into the wrong libdir.
-
-Workaround: Make sure you're running 0.6.1 or later.
-
-Workaround: Check your profile. You can't use <code>default-linux/amd64/</code>
-directly -- you have to use one of the release subdirectories. If this still
-fails, someone who knows what they're doing needs to sit down and figure out
-exactly what's going on for the profile in question.
-
-\subsection KnownIssuesCheck Various packages fail src_test
-
-Problem: Various packages fail <code>src_test</code>
-
-Workaround: You can <code>export SKIP_FUNCTIONS="test"</code> to skip tests. This
-is best done on a per-package basis via <code>bashrc</code>:
-
-\verbatim
-case "${PN}" in
-
- automake|glibc|e2fsprogs|neon|gettext|tar)
- export SKIP_FUNCTIONS=test
- ;;
-
-esac
-\endverbatim
-
-Unfortunately not all package maintainers care about making their package's test
-suite work. This is a nuisance, a) because it makes things much harder for arch
-teams and b) because it makes it harder for users to catch bugs.
-
-At this stage, you should not consider filing a bug about packages whose test
-phases fail. This is something that is being handled by the Gentoo QA team and
-various arch teams.
-
-\subsection KnownIssuesRootSandbox Sandbox violations when ROOT!=/
-
-Problem: Sandbox violations when ROOT!=/
-
-Workaround: Paludis enforces ROOT. However, some packages don't honour ROOT. To
-temporarily disable sandbox for these packages, <code>export SANDBOX_PREDICT=/</code>
-or <code>export SANDBOX_WRITE=/</code> .
-
-\section KnownNonIssuesPortageThings Things Portage Does
-
-\subsection KnownNonIssuesWget wget Resume Support
-
-Non-Problem: With Portage, <code>wget -c</code> is used to attempt to resume downloads of partial files. With Paludis, resumes are not allowed.
-
-Rationale: This leads to corruption and wasted bandwidth far too frequently. In particular, if an error page that isn't recognised as a 404 is fetched from one server (this is common for <code>mirror://sourceforge/</code>), resume support means <code>wget</code> would then download all but the first few hundred bytes of the file from somewhere else, leading to a corrupt distfile notice only after lots of bandwidth has been wasted.
-
-\subsection KnownNonIssesResume Resume / Skip First Support
-
-Non-Problem: Paludis doesn't have an equivalent to --resume --skipfirst in Portage.
-
-Rationale: Too unreliable, too flaky and far too widely abused; however, if an ebuild exits with an error, Paludis will echo a resume command (<code>paludis -i10 =sys-apps/foo-1.23-r1 =app-misc/fnord-2 ...</code>) that can be used to resume the build.
-
-\subsection KnownNonIssuesNice Automatic Niceness Support
-
-Non-Problem: There's no <code>PORTAGE_NICENESS</code> equivalent.
-
-Rationale: Learn how to use <code>nice</code>. There's no <code>GCC_NICENESS</code> or <code>VIM_NICENESS</code>
-either.
-
-*/
-
-
diff --git a/doc/doc_licence.doxygen b/doc/doc_licence.doxygen
deleted file mode 100644
index 85f85bb..0000000
--- a/doc/doc_licence.doxygen
+++ /dev/null
@@ -1,12 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page PaludisLicence Paludis Licence
-
-Paludis is distributed under the terms of the GNU General Public Licence,
-version 2.
-
-\verbinclude COPYING
-
-*/
-
diff --git a/doc/doc_migration_howto.doxygen b/doc/doc_migration_howto.doxygen
deleted file mode 100644
index d6d104f..0000000
--- a/doc/doc_migration_howto.doxygen
+++ /dev/null
@@ -1,247 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page MigrationHowto Migration Howto
-
-\warning Read the \link KnownIssues known issues \endlink list.
-
-There are two methods you can follow to migrate from Portage to Paludis, the
-\ref MigrationHowtoPortageToPaludisManual "Manual Method", and the \ref
-MigrationHowtoPortageToPaludisAutomated "Automated Method". Also, it is now
-usually possible to migrate \ref MigrationHowtoPaludisToPortage "from Paludis back to Portage".
-
-\section MigrationHowtoPortageToPaludisAutomated How to Migrate from Portage to Paludis (the automated method)
-
-Ideally, you'd install Paludis from scratch. However, it's usually possible to
-migrate from Portage to Paludis without too many issues.
-
-\warning Migration is not entirely reliable.
-
-Start by installing Paludis. There are ebuilds in the tree, or you can get SVN
-ebuilds (which Portage can't use) from
-<a href="http://svn.pioto.org/viewvc/paludis/overlay/"> the Paludis overlay</a>.
-If you don't like the <code>libxml2</code> and <code>pcre++</code> dependencies,
-turn off the <code>qa</code> USE flag. <b>Make sure you are using at least
-version 0.6</b> when following this guide.
-
-The easiest way to migrate your configuration from Portage to Paludis is by
-using the <a href="http://svn.pioto.org/viewvc/paludis/scratch/scripts/portage2paludis.bash">portage2paludis.bash</a> script, available via subversion. It is invoked as follows:
-
-\verbatim
-$ sudo ./portage2paludis.bash
-Portage2Paludis:
-
-This script will attempt to convert an existing portage configuration to
-a paludis configuration. It assumes that the portage configuration can
-be found via /etc/make.conf, /etc/make.profile, and /etc/portage/*
-
-Please enter where you would like your new paludis configuration to be
-created, or press enter to use the default.
-
-Paludis Config Directory [/etc/paludis]:
-
-* Configuration Files:
-Generating use.conf (Pass 1 of 3)... done.
-Generating use.conf (Pass 2 of 3)... done.
-Generating use.conf (Pass 3 of 3)... done.
-Generating bashrc (Pass 1 of 1)... done.
-Generating keywords.conf (Pass 1 of 2)... done.
-Generating keywords.conf (Pass 2 of 2)... done.
-Generating mirrors.conf (Pass 1 of 1)... done.
-Generating package_mask.conf (Pass 1 of 1)... done.
-Generating package_unmask.conf (Pass 1 of 1)... done.
-Generating licenses.conf stub (Pass 1 of 1)... done.
-
-* Standard Repositories:
-Generating gentoo.conf (/usr/portage) (Pass 1 of 1)... done.
-Generating installed.conf (/var/db/pkg) (Pass 1 of 1)... done.
-Creating /var/db/pkg/world -> /var/lib/portage/world symlink... done.
-
-* Overlays:
-Generating portage.conf (/usr/local/portage) (Pass 1 of 1)... done.
-Generating vmware.conf (/usr/portage/local/layman/vmware) (Pass 1 of 1)... done.
-
-Complete!
-You now have a new paludis config in: /etc/paludis
-\endverbatim
-
-A few notes on the migration script. The target directory <b>must not exist</b>,
-or the script will bail out. This is to prevent it from clobbering an existing
-paludis config. Also, the script will not migrate your customized portage
-bashrc, that is something you will have to do on your own.
-
-The script will migrate your <code>PORTDIR_OVERLAYS</code> to Paludis as best as
-possible, but, currently, Paludis doesn't support all the sync methods that
-<i>layman</i> does, so you will still probably want to run <code>layman
--S</code> to update any layman repositories you have now. Finally, the script
-will first try to name your repositories what their profiles/repo_name file
-says they should be called and, if that fails, they will be called what their
-top level directory is called (so, /usr/local/portage is called "portage"). If
-any name collisions occur, the script will terminate, and you will have to
-finish configuring your overlays on your own.
-
-Now, try:
-
-\verbatim
-sudo paludis --sync
-paludis -pi world
-\endverbatim
-
-You will likely find that it picks up a few packages that Portage wouldn't. This
-is to be expected -- the Paludis dependency resolver is considerably more complete
-than the Portage one, and it will try to enforce runtime dependencies of already
-installed packages. In particular, this means that if you have any packages
-installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
-be pulled in.
-
-You may encounter some nasty error messages, especially if you're running an old
-install and have some packages that were installed a very long time ago with a
-broken Portage release. In most cases, removing the VDB entry by hand and then
-immediately reinstalling the same version of the package using Paludis (or even
-a recent Portage) will suffice.
-
-\section MigrationHowtoPortageToPaludisManual How to Migrate from Portage to Paludis (the manual method)
-
-Ideally, you'd install Paludis from scratch. However, it's usually possible to
-migrate from Portage to Paludis without too many issues.
-
-\warning Migration is not entirely reliable.
-
-Start by installing Paludis. There are ebuilds in the tree, or you can get SVN
-ebuilds (which Portage can't use) from
-<a href="http://svn.pioto.org/viewvc/paludis/overlay/"> the Paludis overlay</a>.
-If you don't like the <code>libxml2</code> and <code>pcre++</code> dependencies,
-turn off the <code>qa</code> USE flag. <b>Make sure you are using at least
-version 0.6</b> when following this guide.
-
-Next, make some configuration files. For full details, see \link ConfigurationFiles
-the configuration files documentation \endlink . For a quick template:
-
-\verbatim
-mkdir -p /etc/paludis/repositories
-
-cat <<"END" > /etc/paludis/keywords.conf
-* x86
-dev-cpp/libebt x86 ~x86
-sys-apps/paludis x86 ~x86
-dev-util/subversion x86 ~x86
-app-admin/eselect x86 ~x86
-sys-fs/udev x86 ~x86
-END
-
-cat <<"END" > /etc/paludis/use.conf
-* -doc nls -apache2
-* LINGUAS: en
-* INPUT_DEVICES: keyboard mouse
-* VIDEO_CARDS: -* ati
-app-editors/vim -nls
-END
-
-cat <<"END" > /etc/paludis/licenses.conf
-* *
-END
-
-cat <<"END" > /etc/paludis/mirrors.conf
-gentoo http://gentoo.blueyonder.co.uk/distfiles/
-gnu http://gnu.blueyonder.co.uk/
-debian http://debian.blueyonder.co.uk/
-END
-\endverbatim
-
-Set up your <code>bashrc</code>. This must <b>NOT</b> be used to change any
-values that affect dependency resolution (e.g. <code>USE</code>,
-<code>LINGUAS</code>). It can be used to set <code>CFLAGS</code>,
-<code>CHOST</code> and the like (on some archs you'll have to do this to
-avoid getting junk from your profile). Remember to <code>export</code> your
-variables.
-
-\verbatim
-cat <<"END" > /etc/paludis/bashrc
-export CFLAGS="-O2 -march=pentium4 -fomit-frame-pointer"
-export CXXFLAGS="${CFLAGS}"
-export CHOST="i686-pc-linux-gnu"
-export MAKEOPTS="-j2"
-END
-\endverbatim
-
-Set up your repository files. Do not tinker with the VDB location, it
-<b>must</b> go in <code>${ROOT}/var/db/pkg</code>. Here we'll avoid using
-<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/
-sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
-profiles = /var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
-format = portage
-END
-
-cat <<"END" > /etc/paludis/repositories/installed.conf
-location = /var/db/pkg/
-format = vdb
-END
-
-cat <<"END" > /etc/paludis/repositories/paludis-overlay.conf
-location = /var/paludis/repositories/paludis-overlay/
-sync = svn://svn.pioto.org/paludis/overlay
-profiles = /var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
-eclassdirs = /var/paludis/repositories/gentoo/eclass
-distdir = /var/paludis/repositories/gentoo/distfiles
-cache = /var/empty
-format = portage
-importance = 10
-END
-\endverbatim
-
-The world file for Paludis lives in the VDB directory. For Portage compatibility,
-a symlink can be used (but be careful when uninstalling Portage if you use this
-route).
-
-\verbatim
-sudo ln -s /var/lib/portage/world /var/db/pkg/world
-\endverbatim
-
-Now, try:
-
-\verbatim
-sudo paludis --sync
-paludis -pi world
-\endverbatim
-
-You will likely find that it picks up a few packages that Portage wouldn't. This
-is to be expected -- the Paludis dependency resolver is considerably more complete
-than the Portage one, and it will try to enforce runtime dependencies of already
-installed packages. In particular, this means that if you have any packages
-installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
-be pulled in.
-
-You may encounter some nasty error messages, especially if you're running an old
-install and have some packages that were installed a very long time ago with a
-broken Portage release. In most cases, removing the VDB entry by hand and then
-immediately reinstalling the same version of the package using Paludis (or even
-a recent Portage) will suffice.
-
-\section MigrationHowtoPaludisToPortage How to Migrate from Paludis to Portage
-
-\warning Migration is not entirely reliable.
-
-If, and only if, you have at any point used a Paludis version below 0.6, start
-with:
-
-\verbatim
-# For people who used Paludis before 0.6 only!
-rm -fr /var/db/pkg/virtual
-\endverbatim
-
-Then <code>emerge --sync</code> (this is important) and you might be back to normal.
-If you encounter weird failures when upgrading or uninstalling packages that were
-installed by Paludis, removing the VDB entry by hand and then immediately
-reinstalling the same version of the package using Portage will usually fix things.
-
-*/
-
diff --git a/doc/doc_news.doxygen b/doc/doc_news.doxygen
deleted file mode 100644
index 990eae5..0000000
--- a/doc/doc_news.doxygen
+++ /dev/null
@@ -1,11 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page PaludisNews Paludis News
-
-\verbinclude NEWS
-
-*/
-
-
-
diff --git a/doc/footer.html b/doc/footer.html
index 0483246..32832e3 100644
--- a/doc/footer.html
+++ b/doc/footer.html
@@ -1,5 +1,5 @@
<div class="qindex" style="text-align: center; margin-top: 1em;">
- <p>Copyright &copy; 2005, 2006 <a href="http://ciaranm.org/">Ciaran
+ <p>Copyright &copy; 2005, 2006, 2007 <a href="http://ciaranm.org/">Ciaran
McCreesh</a> and various others. See the <a href="../../authors.html">Authors
list</a> and <a href="../../licence.html">Licence</a> for details and redistribution conditions.</p>
</div>
diff --git a/doc/htmlfooter.html b/doc/htmlfooter.html
index 383c100..bc79603 100644
--- a/doc/htmlfooter.html
+++ b/doc/htmlfooter.html
@@ -1,5 +1,5 @@
<div class="qindex" style="text-align: center; margin-top: 1em;">
- <p>Copyright &copy; 2005, 2006 <a href="http://ciaranm.org/">Ciaran
+ <p>Copyright &copy; 2005, 2006, 2007 <a href="http://ciaranm.org/">Ciaran
McCreesh</a> and various others. See the <a href="authors.html">Authors
list</a> and <a href="licence.html">Licence</a> for details and redistribution conditions.</p>
</div>
diff --git a/doc/migration.html.skel b/doc/migration.html.skel
new file mode 100644
index 0000000..9aa84b2
--- /dev/null
+++ b/doc/migration.html.skel
@@ -0,0 +1,208 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en">
+<head>
+<title>Paludis, the Other Package Mangler</title>
+<link rel="stylesheet" href="paludis.css" type="text/css" />
+</head>
+<body>
+@HEADER@
+
+<h1>Paludis, the Other Package Mangler</h1>
+
+<h2>Migrating to Paludis</h2>
+
+<p>There are two methods you can follow to migrate from Portage to Paludis: the
+<a href="#manual">manual method</a> or the <a href="#automated">automated
+ method</a>. Also, it is now usually possible to migrate <a
+ href="#coward">from Paludis back to Portage</a>.</p>
+
+<p><strong>Warning:</strong> Migration is not always entirely reliable. If
+you've had an install for a long time, chances are your system contains a fair
+amount of cruft generated by buggy Portage versions. You may need to fix this
+manually.</p>
+
+<p>No matter which method you plan to use, start by installing Paludis. There
+are ebuilds in the tree, or you can get SVN ebuilds (which Portage can't use)
+from <a href="http://svn.pioto.org/viewvc/paludis/overlay/">the Paludis
+ overlay</a>. If you don't like the <code>libxml2</code> and
+<code>pcre++</code> dependencies, turn off the <code>qa</code> USE flag.
+<strong>Make sure you are using at least version 0.14</strong> when following
+this guide.</p>
+
+<h3 id="automated">How to Migrate from Portage to Paludis (the automated
+ method)</h3>
+
+The easiest way to migrate your configuration from Portage to Paludis is by
+using the <a href="http://svn.pioto.org/viewvc/paludis/scratch/scripts/portage2paludis.bash">portage2paludis.bash</a> script, available via subversion. It is invoked as follows:
+
+<pre>
+$ sudo ./portage2paludis.bash
+</pre>
+
+<p>A few notes on the migration script. The target configuration directory <b>must not exist</b>,
+or the script will bail out. This is to prevent it from clobbering an existing
+paludis config. Also, the script will not migrate your customized portage
+bashrc -- this is something you will have to do on your own.</p>
+
+<p>The script will migrate your <code>PORTDIR_OVERLAYS</code> to Paludis as best as
+possible. Finally, the script
+will first try to name your repositories what their profiles/repo_name file
+says they should be called and, if that fails, they will be called what their
+top level directory is called (so, /usr/local/portage is called "portage"). If
+any name collisions occur, the script will terminate, and you will have to
+finish configuring your overlays on your own.</p>
+
+<p>Now, try:</p>
+
+<pre>
+sudo paludis --sync
+paludis -pi world
+</pre>
+
+<p>You will likely find that it picks up a few packages that Portage wouldn't. This
+is to be expected -- the Paludis dependency resolver is considerably more complete
+than the Portage one, and it will try to enforce runtime dependencies of already
+installed packages. In particular, this means that if you have any packages
+installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
+be pulled in.</p>
+
+<p>You may encounter some nasty error messages, especially if you're running an old
+install and have some packages that were installed a very long time ago with a
+broken Portage release. In most cases, removing the VDB entry by hand and then
+immediately reinstalling the same version of the package using Paludis (or even
+a recent Portage) will suffice.</p>
+
+<h3 id="#manual">How to Migrate from Portage to Paludis (the manual method)</h3>
+
+<p>First, make some configuration files. For full details, see <a
+ href="configuration.html">the configuration files documentation</a>.
+For a quick template:</p>
+
+<pre>
+mkdir -p /etc/paludis/repositories
+
+cat &lt;&lt;"END" &gt; /etc/paludis/keywords.conf
+* x86
+dev-cpp/libebt x86 ~x86
+sys-apps/paludis x86 ~x86
+dev-util/subversion x86 ~x86
+app-admin/eselect x86 ~x86
+sys-fs/udev x86 ~x86
+END
+
+cat &lt;&lt;"END" &gt; /etc/paludis/use.conf
+* -doc nls -apache2
+* LINGUAS: en
+* INPUT_DEVICES: keyboard mouse
+* VIDEO_CARDS: -* ati
+app-editors/vim -nls
+END
+
+cat &lt;&lt;"END" &gt; /etc/paludis/licenses.conf
+* *
+END
+
+cat &lt;&lt;"END" &gt; /etc/paludis/mirrors.conf
+gentoo http://gentoo.blueyonder.co.uk/distfiles/
+gnu http://gnu.blueyonder.co.uk/
+debian http://debian.blueyonder.co.uk/
+END
+</pre>
+
+<p>Set up your <code>bashrc</code>. This must <b>NOT</b> be used to change any
+values that affect dependency resolution (e.g. <code>USE</code>,
+<code>LINGUAS</code>). It can be used to set <code>CFLAGS</code>,
+<code>CHOST</code> and the like (on some archs you'll have to do this to
+avoid getting junk from your profile). Remember to <code>export</code> your
+variables.</p>
+
+<pre>
+cat &lt;&lt;"END" &gt; /etc/paludis/bashrc
+export CFLAGS="-O2 -march=pentium4 -fomit-frame-pointer"
+export CXXFLAGS="${CFLAGS}"
+export CHOST="i686-pc-linux-gnu"
+export MAKEOPTS="-j2"
+END
+</pre>
+
+<p>Set up your repository files. Do not tinker with the VDB location, it
+<b>must</b> go in <code>${ROOT}/var/db/pkg</code>. Here we'll avoid using
+<code>/usr/portage</code> for the main tree because sticking data that gets
+changed on <code>/usr</code> is silly.</p>
+
+<p>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 <a href="cachefiles.html">the cache documentation</a>.</p>
+
+<pre>
+cat &lt;&lt;"END" &gt; /etc/paludis/repositories/gentoo.conf
+location = /var/paludis/repositories/gentoo/
+sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
+profiles = /var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
+format = portage
+END
+
+cat &lt;&lt;"END" &gt; /etc/paludis/repositories/installed.conf
+location = /var/db/pkg/
+format = vdb
+END
+
+cat &lt;&lt;"END" &gt; /etc/paludis/repositories/paludis-overlay.conf
+location = /var/paludis/repositories/paludis-overlay/
+sync = svn://svn.pioto.org/paludis/overlay
+profiles = /var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
+eclassdirs = /var/paludis/repositories/gentoo/eclass
+distdir = /var/paludis/repositories/gentoo/distfiles
+cache = /var/empty
+format = portage
+importance = 10
+END
+</pre>
+
+<p>The world file for Paludis lives in the VDB directory. For Portage compatibility,
+a symlink can be used (but be careful when uninstalling Portage if you use this
+route).</p>
+
+<pre>
+sudo ln -s /var/lib/portage/world /var/db/pkg/world
+</pre>
+
+<p>Now, try:</p>
+
+<pre>
+sudo paludis --sync
+paludis -pi world
+</pre>
+
+<p>You will likely find that it picks up a few packages that Portage wouldn't. This
+is to be expected -- the Paludis dependency resolver is considerably more complete
+than the Portage one, and it will try to enforce runtime dependencies of already
+installed packages. In particular, this means that if you have any packages
+installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
+be pulled in.</p>
+
+<p>You may encounter some nasty error messages, especially if you're running an old
+install and have some packages that were installed a very long time ago with a
+broken Portage release. In most cases, removing the VDB entry by hand and then
+immediately reinstalling the same version of the package using Paludis (or even
+a recent Portage) will suffice.</p>
+
+<h3 id="#coward">How to Migrate from Paludis to Portage</h3>
+
+<p>Start by uninstalling any packages that use <code>-scm</code> or
+<code>-try</code>. Also <code>rm -fr</code> any <code>.cache</code> directories
+created inside repository directories.</p>
+
+<p>Finally <code>emerge --sync</code> (this is important) and you might be back to normal.
+If you encounter weird failures when upgrading or uninstalling packages that were
+installed by Paludis, removing the VDB entry by hand and then immediately
+reinstalling the same version of the package using Portage will usually fix
+things.</p>
+
+@FOOTER@
+</body>
+</html>
+
+
+