aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-08-31 20:50:31 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-08-31 20:50:31 +0000
commit1410987478dc28fa60228c0e76587944152a7614 (patch)
treec27c60de186a0f8045aeae7234f6c28383cc6b04
parent6ceadd7cf399a63fdb9597abe8f8c2fb03ef1588 (diff)
downloadpaludis-1410987478dc28fa60228c0e76587944152a7614.tar.gz
paludis-1410987478dc28fa60228c0e76587944152a7614.tar.xz
Extend the user documentation (forward port from 0.6 branch)
-rw-r--r--doc/Makefile.am4
-rw-r--r--doc/doc_bootstrap_howto.doxygen50
-rw-r--r--doc/doc_known_issues.doxygen60
-rw-r--r--doc/doc_mainpage.doxygen15
-rw-r--r--doc/doc_migration_howto.doxygen150
-rw-r--r--doc/header.html2
6 files changed, 248 insertions, 33 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 40cca23..591cc4e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -14,7 +14,9 @@ docfiles = \
doc_portage_differences.doxygen \
doc_news.doxygen \
doc_security_advisories.doxygen \
- doc_configuration_files.doxygen
+ doc_configuration_files.doxygen \
+ doc_migration_howto.doxygen \
+ doc_known_issues.doxygen
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css $(docfiles)
diff --git a/doc/doc_bootstrap_howto.doxygen b/doc/doc_bootstrap_howto.doxygen
index 111cc22..d3c8cdb 100644
--- a/doc/doc_bootstrap_howto.doxygen
+++ b/doc/doc_bootstrap_howto.doxygen
@@ -5,39 +5,39 @@
\section BootstrapHowtoMain How to make a Paludis chroot
-<b>THIS WILL PROBABLY NOT ACTUALLY WORK!</b> Paludis is at the very
-early alpha stage. It can sometimes install things, if you're very lucky, and
-if you're really lucky it might let you upgrade or uninstall them too. There are
-zillions of things that are not implemented. There are zillions of things that
-Paludis does differently from Portage -- some of these are intentional, some are
-not.
-
<b>You may encounter problems!</b> Paludis is still undergoing heavy development,
and although it's getting to be fairly reliable, there are still issues. Most
-ebuild authors don't test their code with both package managers.
+ebuild authors don't test their code with both package managers. You will also
+find that some packages are very picky about honouring <code>ROOT</code>. At the
+very least, you will encounter issues if you are trying to build a stable stage
+from an unstable system.
You should join the <code>\#paludis</code> channel on Freenode. If you're doing
anything development-related, you should probably also ask to be allowed to
subscribe to the <code>paludis-sekrit</code> mailing list.
-\warning Do not try to use Paludis and Portage to install things inside the same
- root. The config and vdb formats are not compatible!
+\warning Using Portage and Paludis on the same root isn't a very good idea. There
+ are differences in configuration and VDB formats.
\warning Do not file bugs related to Paludis on Gentoo Bugzilla. Do not discuss
Paludis on Gentoo mailing lists or forums. Do not pester Gentoo developers
- about Paludis.
+ about Paludis. Read the \link KnownIssues known issues \endlink list.
\section BootstrapHowtoRequirements Requirements
Install Paludis locally, being sure to configure <code>sysconfdir</code> as
-<code>/etc</code> to avoid confusion later on. There're ebuilds in the tree, or in
-<a href="http://svn.pioto.org/viewvc/paludis/overlay/">
-the Paludis overlay</a> if you need SVN ebuilds.
-
-You'll need libebt, eselect and Subversion. You'll also need either g++-3.4,
-g++-4.1 or some other reasonably standard C++ compiler along with a complete
-standard library implementation (so no uClibc++). If you're trying to run on
-non-Linux, you'll also need to fix a few includes and submit a patch.
+<code>/etc</code>, <code>localstatedir</code> as <code>/var/lib</code> and
+<code>datadir</code> as <code>/usr/share</code> to avoid confusion later on.
+There're ebuilds in the tree, or in <a
+href="http://svn.pioto.org/viewvc/paludis/overlay/"> the Paludis overlay</a> if
+you need SVN ebuilds.
+
+You'll need libebt, libwrapiter, eselect and Subversion. If you're using the QA
+tools (<code>--enable-qa</code>) you will also need pcre++ (and pcre, by
+extension) and libxml2. You'll also need either g++-3.4, g++-4.1 or some other
+reasonably standard C++ compiler along with a complete standard library
+implementation (so no uClibc++). If you're trying to run on non-Linux, you'll
+also need to fix a few includes and submit a patch.
Make sure the test suite passes (either <code>FEATURES="test"</code> for
Portage, or <code>make check</code>). If it fails, don't continue until you
@@ -75,12 +75,12 @@ should use <code>* arch ~arch</code>.
\verbatim
cat <<"END" > /mychroot/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
-app-editors/vim x86 ~x86
+* x86
+dev-cpp/libebt x86 ~x86
+sys-apps/paludis x86 ~x86
+dev-util/subversion x86 ~x86
+app-admin/eselect x86 ~x86
+app-editors/vim x86 ~x86
app-editors/vim-core x86 ~x86
END
\endverbatim
diff --git a/doc/doc_known_issues.doxygen b/doc/doc_known_issues.doxygen
new file mode 100644
index 0000000..c313ec2
--- /dev/null
+++ b/doc/doc_known_issues.doxygen
@@ -0,0 +1,60 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/**
+\page KnownIssues Known Issues
+
+\section KnownIssuesMain About these 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 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.
+
+\subsection KnownIssuesKDE Some KDE libraries are broken on some amd64 profiles
+
+Problem: Various KDE applications install libraries into the wrong libdir.
+
+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.
+
+\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>.
+
+*/
+
+
diff --git a/doc/doc_mainpage.doxygen b/doc/doc_mainpage.doxygen
index 3e68c12..2990dff 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/doc_mainpage.doxygen
@@ -6,6 +6,10 @@
This is the documentation for Paludis, the other package manager. It is available as part of Paludis via <code>make doxygen</code>, or on the web at <a href="http://paludis.berlios.de/">the Paludis project page</a>.
+\warning Do not file bugs related to Paludis on Gentoo Bugzilla. Do not discuss
+ Paludis on Gentoo mailing lists or forums. Do not pester Gentoo developers
+ about Paludis. Read the \link KnownIssues known issues \endlink list.
+
\section userdocs For End Users
Paludis is still undergoing heavy development. It is not a mature solution, and
@@ -14,9 +18,10 @@ Paludis (some of which may leave your system unusable). Most ebuild authors do
not test their code with both package managers.
If you find this acceptable, read \link BootstrapHowto the Bootstrap HOWTO
-\endlink for how to set up a chroot or make a stage. You may also like to read
-about \link PortageDifferences some of the differences between Paludis and
-Portage\endlink.
+\endlink for how to set up a chroot or make a stage, or \link MigrationHowto the
+Migration HOWTO \endlink for how to migrate an existing install (this is less
+reliable). You may also like to read about \link PortageDifferences some of the
+differences between Paludis and Portage \endlink.
We have a <a href="https://developer.berlios.de/bugs/?group_id=6360">bug
tracker</a> and some
@@ -24,10 +29,6 @@ tracker</a> and some
you shouldn't try to use these until after you've discussed your problem in our
IRC channel. Read the howto for more details.
-\warning Do not file bugs related to Paludis on Gentoo Bugzilla. Do not discuss
- Paludis on Gentoo mailing lists or forums. Do not pester Gentoo developers
- about Paludis.
-
\section developerdocs For Developers
Start by getting a
diff --git a/doc/doc_migration_howto.doxygen b/doc/doc_migration_howto.doxygen
new file mode 100644
index 0000000..7929898
--- /dev/null
+++ b/doc/doc_migration_howto.doxygen
@@ -0,0 +1,150 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/**
+\page MigrationHowto Migration Howto
+
+\warning Do not file bugs related to Paludis on Gentoo Bugzilla. Do not discuss
+ Paludis on Gentoo mailing lists or forums. Do not pester Gentoo developers
+ about Paludis. Read the \link KnownIssues known issues \endlink list.
+
+\section MigrationHowtoPortageToPaludis How to Migrate from Portage to Paludis
+
+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.
+
+\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/header.html b/doc/header.html
index 033721d..06f4c57 100644
--- a/doc/header.html
+++ b/doc/header.html
@@ -19,6 +19,8 @@
<div class="qindex">User Documentation: [
<a class="qindex" href="BootstrapHowto.html">Bootstrap&nbsp;Howto</a> |
+ <a class="qindex" href="MigrationHowto.html">Migration&nbsp;Howto</a> |
+ <a class="qindex" href="KnownIssues">Known&nbsp;Issues</a>&nbsp;(<strong>Important</strong>) |
<a class="qindex" href="ConfigurationFiles.html">Configuration&nbsp;Files</a> |
<a class="qindex" href="PortageDifferences.html">Portage&nbsp;Differences</a> ]
</div>