aboutsummaryrefslogtreecommitdiff
path: root/0.8.0/doc/doc_bootstrap_howto.doxygen
diff options
context:
space:
mode:
Diffstat (limited to '0.8.0/doc/doc_bootstrap_howto.doxygen')
-rw-r--r--0.8.0/doc/doc_bootstrap_howto.doxygen318
1 files changed, 318 insertions, 0 deletions
diff --git a/0.8.0/doc/doc_bootstrap_howto.doxygen b/0.8.0/doc/doc_bootstrap_howto.doxygen
new file mode 100644
index 0000000..eba5821
--- /dev/null
+++ b/0.8.0/doc/doc_bootstrap_howto.doxygen
@@ -0,0 +1,318 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/**
+\page BootstrapHowto Bootstrap Howto
+
+\section BootstrapHowtoMain How to make a Paludis chroot
+
+<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. 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 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. 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>, <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
+figure out why.
+
+\section BootstrapConfiguration Configuration
+
+Set up a local bootstrap config directory. We're assuming in this document that
+you're using <code>/mychroot</code> as the root path, but anywhere not on a
+noexec / nodev filesystem should work. The reason for doing things this way will
+become apparent later on.
+
+\verbatim
+mkdir ~/.paludis-bootstrap
+cat <<"END" > ~/.paludis-bootstrap/specpath
+root = /mychroot
+config-suffix =
+END
+\endverbatim
+
+Make some skeleton directories and files:
+
+\verbatim
+mkdir -p /mychroot/etc/{env.d,paludis/repositories}
+mkdir -p /mychroot/var/{db/pkg,paludis/repositories/gentoo/distfiles}
+mkdir -p /mychroot/tmp/
+touch /mychroot/etc/ld.so.conf
+\endverbatim
+
+Set up your <code>keywords.conf</code>. At the very least, you'll need a <code>*
+keywords</code> line. Further lines can be added in the form "atom keywords".
+Like with Portage, accepting <code>~keyword</code> does <b>not</b> accept
+<code>keyword</code>, so if you want a fully <code>~arch</code> system you
+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
+app-editors/vim-core x86 ~x86
+END
+\endverbatim
+
+Set up your <code>use.conf</code>. At the very least, you'll need a <code>*
+flags</code> line. Again, additional per-atom lines can be specified. The
+<code>-apache2</code> is important, if you value your sanity, since you'll be
+installing subversion. We're experimenting with a slightly different way of
+handling <code>USE_EXPAND</code> variables that allows different settings for
+different packages. This may change, but for now it looks like this (note the
+<code>-*</code> to avoid inherinting profile values:
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/use.conf
+* -doc nls -apache2 LINGUAS: en INPUT_DEVICES: keyboard mouse VIDEO_CARDS: -* ati
+app-editors/vim -nls
+END
+\endverbatim
+
+Set up your <code>licenses.conf</code>. If you don't care about licences, which
+is probably wise until we get licence grouping, it should look like this:
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/licenses.conf
+* *
+END
+\endverbatim
+
+If you want some more fun, the following list might be enough to install a
+base system if you don't turn on too many extra USE flags:
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/licenses.conf
+# These are the basic system requirements. It's possible to knock off
+# a few of these by turning off some default USE flags.
+* LGPL-2.1 LGPL-2 GPL-2 BSD MIT BZIP2 Artistic DB PSF-2.1.1 PSF-2.2
+* as-is tcp_wrappers_license freedist ZLIB openssl CRACKLIB PAM FLEX
+
+# These are needed to get Subversion.
+* Apache-1.1 Apache-2.0
+
+# These are needed to get an editor that doesn't suck.
+* vim
+
+# These are needed if you want modular X. This is utterly ridiculous,
+# and the people responsible for using different licence IDs for
+# identical licences should be shot.
+* xorg-server libXfont xtrans util-macros libfontenc xproto fontsproto
+* FTL fontcacheproto libXau libXext libX11 libXdmcp kbproto inputproto
+* xf86bigfontproto bigreqsproto xextproto xcmiscproto libxkbfile libXmu
+* libXt libSM libICE libXrender renderproto libXi libXxf86vm
+* xf86vidmodeproto libdrm MOTIF libXaw libXpm libXp printproto xbitmaps
+* makedepend xf86driproto glproto font-adobe-75dpi bdftopcf font-util
+* encodings mkfontscale mkfontdir font-misc-misc font-cursor-misc
+* xkbcomp iceauth rgb xauth xinit twm xclock libXft fontconfig xrdb X11
+* libXxf86misc xf86miscproto libdmx dmxproto libXtst recordproto libXres
+* resourceproto libxkbui liblbxutil randrproto fixesproto damageproto
+* xf86dgaproto xf86rushproto compositeproto videoproto scrnsaverproto
+* evieext trapproto xineramaproto glut setxkbmap xhost xmodmap xrandr
+* libXrandr libXcomposite libXfixes libXcursor libXdamage libXv
+* libXxf86dga libXinerama libXScrnSaver BitstreamVera font-bh-type1
+* font-adobe-utopia-type1 font-adobe-100dpi xorg-docs
+* xf86-input-keyboard xf86-input-mouse xf86-video-ati font-alias
+END
+\endverbatim
+
+Set up your <code>package_unmask.conf</code> and <code>package_mask.conf</code>,
+if necessary:
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/package_unmask.conf
+app-editors/vim
+app-editors/vim-core
+END
+\endverbatim
+
+Set up your <code>mirrors.conf</code>, if you feel like it (note that 0.2.5 or
+later is required, or this file is ignored). It uses the same format as
+<code>thirdpartymirrors</code>. Remember to include the <code>/distfiles</code>
+for Gentoo mirrors.
+
+\verbatim
+cat <<"END" > /mychroot/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.
+
+Unfortunately, some packages in system have broken test suites, and some
+packages abuse non-${ROOT} locations in pkg_postinst. Thus, you will also
+need to add a bit of magic to work around these packages.
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/bashrc
+export CFLAGS="-O2 -march=pentium4 -fomit-frame-pointer"
+export CXXFLAGS="${CFLAGS}"
+export CHOST="i686-pc-linux-gnu"
+export MAKEOPTS="-j2"
+export EBEEP_IGNORE="yes"
+export EPAUSE_IGNORE="yes"
+
+case "${PN}" in
+
+ python|portage)
+ export SKIP_FUNCTIONS=test
+ export SANDBOX_PREDICT=/
+ ;;
+
+ automake|glibc|e2fsprogs|neon|gettext|tar)
+ export SKIP_FUNCTIONS=test
+ ;;
+
+esac
+
+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. We use the <code>${ROOT}</code> variable,
+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.
+
+\verbatim
+cat <<"END" > /mychroot/etc/paludis/repositories/gentoo.conf
+location = ${ROOT}/var/paludis/repositories/gentoo/
+sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
+profiles = ${ROOT}/var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
+format = portage
+END
+
+cat <<"END" > /mychroot/etc/paludis/repositories/installed.conf
+location = ${ROOT}/var/db/pkg/
+format = vdb
+END
+
+cat <<"END" > /mychroot/etc/paludis/repositories/paludis-overlay.conf
+location = ${ROOT}/var/paludis/repositories/paludis-overlay/
+sync = svn://svn.pioto.org/paludis/overlay
+profiles = ${ROOT}/var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
+eclassdirs = ${ROOT}/var/paludis/repositories/gentoo/eclass
+distdir = ${ROOT}/var/paludis/repositories/gentoo/distfiles
+cache = /var/empty
+format = portage
+importance = 10
+END
+\endverbatim
+
+\section BootstrapHowtoSync Initial Sync
+
+Now check that the config looks ok, and sync:
+
+\verbatim
+paludis --config-suffix bootstrap --list-repositories
+sudo paludis --config-suffix bootstrap --sync
+\endverbatim
+
+If you have problems, try adding <code>--log-level debug</code>. This may or may
+not give helpful information... This applies at all stages.
+
+The initial sync will be slow. You can cheat and copy an existing Portage tree
+checkout into <code>/mychroot/var/paludis/repositories/gentoo/</code>, but
+remember to preserve mtimes and permissions if you do. Note that there's no
+hideously painful 'Updating the Portage cache...' to go through. Paludis will
+use the metadata cache, if available, but does not use the dep cache.
+
+\section BootstrapInstalling Installing Things
+
+Now install baselayout and then system. We install baselayout manually first
+because it's easier than creating a bunch of directories by hand.
+
+Note that there're a whole load of circular dependencies in system
+(ncurses <-> gpm, patch <-> patch, gcc <-> glibc for example), so you'll
+almost certainly need --dl-drop-circular at this stage.
+
+\verbatim
+paludis --config-suffix bootstrap --install --pretend --dl-drop-all sys-apps/baselayout
+sudo paludis --config-suffix bootstrap --install --dl-drop-all sys-apps/baselayout
+
+paludis --config-suffix bootstrap --install --pretend --dl-drop-circular system
+sudo paludis --config-suffix bootstrap --install --dl-drop-circular system
+\endverbatim
+
+Note that system will pull in Portage. That's a profiles thing that's
+unavoidable for now. It won't pull in Paludis, so we do that manually.
+
+\note It seems apr and apr-util are rather picky about compiling into ROOT
+unless an identical version is installed onto / .
+
+\verbatim
+paludis --config-suffix bootstrap --install --pretend sys-apps/paludis
+sudo paludis --config-suffix bootstrap --install sys-apps/paludis
+\endverbatim
+
+\section BootstrapHowtoChroot Chrooting
+
+And that should (but probably won't) give you a usable chroot:
+
+\verbatim
+sudo cp /etc/resolv.conf /mychroot/etc/
+sudo chroot /mychroot
+reset
+export HOME=/root
+cd
+cp /etc/skel/.bashrc .
+. .bashrc
+ln -sf /usr/share/zoneinfo/Europe/London /etc/localtime
+mount -tproc none /proc
+mount -tsysfs none /sys
+udevstart
+mount -tdevpts none /dev/pts
+eselect env update
+source /etc/profile
+( . /etc/paludis/bashrc ; export REAL_CHOST=$CHOST ; gcc-config 1 )
+eselect env update
+source /etc/profile
+paludis --uninstall sys-apps/portage
+paludis --install app-editors/vim
+paludis --uninstall app-editors/nano
+\endverbatim
+
+You can also tar up the system and use it as a stage3 or NFS root image.
+
+*/
+