diff options
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-07-07 21:24:22 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-07-07 21:24:22 +0000
commit15222203327c732feddfded01ac3de9e6b64c3f0 (patch)
parentfdb93e813e4dbade9c47205bd7339778bb998cc1 (diff)
Doxygen updates in preparation for 0.4
4 files changed, 107 insertions, 21 deletions
diff --git a/doc/doc_bootstrap_howto.doxygen b/doc/doc_bootstrap_howto.doxygen
index b96c75f..bb386ca 100644
--- a/doc/doc_bootstrap_howto.doxygen
+++ b/doc/doc_bootstrap_howto.doxygen
@@ -5,8 +5,6 @@
\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
@@ -14,6 +12,10 @@ 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
+<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 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.
@@ -215,7 +217,7 @@ thing). The Paludis overlay is optional but recommended.
cat <<"END" > /mychroot/etc/paludis/repositories/gentoo.conf
location = ${ROOT}/var/paludis/repositories/gentoo/
sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
-profile = ${ROOT}/var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
+profiles = ${ROOT}/var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
format = portage
@@ -227,8 +229,8 @@ END
cat <<"END" > /mychroot/etc/paludis/repositories/paludis-overlay.conf
location = ${ROOT}/var/paludis/repositories/paludis-overlay/
sync = svn://svn.berlios.de/paludis/overlay
-profile = ${ROOT}/var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
-eclassdir = ${ROOT}/var/paludis/repositories/gentoo/eclass
+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
@@ -309,9 +311,7 @@ paludis --install app-editors/vim
paludis --uninstall app-editors/nano
-If you're especially crazy you can tar up your chroot and use it like a stage 3
-when installing a system. This has worked at least once for one person, but
-note that there was a full moon at the time.
+You can also tar up the system and use it as a stage3 or NFS root image.
diff --git a/doc/doc_configuration_files.doxygen b/doc/doc_configuration_files.doxygen
index 7dbc812..7031d44 100644
--- a/doc/doc_configuration_files.doxygen
+++ b/doc/doc_configuration_files.doxygen
@@ -120,6 +120,95 @@ For filtering, the format is similar to the keywords and use files:
app-editors/vim-core vim
+\section ConfigurationFilesMirrorsConf The mirrors.conf File
+Mirrors and downloading can be controlled via <code>mirrors.conf</code>. Each
+line takes the form <code>mirrorname http://mirror/blah/ http://another.mirror/</code>.
+A special mirror named <code>*</code>, if present, will be consulted <em>before</em>
+any other location for all files. For example:
+* file:///mnt/nfs/distfiles
+gentoo http://gentoo.blueyonder.co.uk/distfiles
+\section ConfigurationFilesBashrc The bashrc File
+Paludis will source <code>bashrc</code> when doing ebuild work. This file
+can be used to set environment variables (<code>CHOST</code>, <code>CFLAGS</code>
+and so on), but <em>cannot</em> be used to change metadata-affecting variables
+such as <code>USE</code> or <code>LINGUAS</code>.
+\section ConfigurationFilesRepositories The repositories/ Files
+Each file named <code>*.conf</code> in the <code>repositories/</code> subdirectory
+creates a repository for Paludis. This is a key = value format file, and the special
+variable <code>${ROOT}</code> is defined based upon <code>specpath</code>. All
+files must define a <code>format =</code> key; depending upon the value used, other
+optional and mandatory keys are available.
+\subsection ConfigurationFilesRepositoriesPortage portage Format Repositories
+\note The name <code>portage</code> is used here to refer to repositories in the
+format used by the <code>gentoo-portage</code> (or <code>gentoo-x86</code>) tree.
+The name is far from ideal...
+The following keys are available for <code>format = portage</code>:
+- <code>location</code> (mandatory), which points to the location of the
+ tree.
+- <code>profiles</code> (mandatory), which should be a space separated list of
+ directories used for profile data. Later directories have priority.
+- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
+ the temporary directory used by Paludis for compiling software.
+- <code>cache</code> (default: <code>${location}/metadata/cache</code>), which
+ controls the location of the metadata cache for a repository. It should be set
+ to <code>/var/empty</code> if there is no metadata cache available.
+- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
+ controls where downloaded files are saved.
+- <code>eclassdirs</code> (default: <code>${location}/eclass</code>), which
+ is a space separated list of locations of eclasses. The value of ECLASSDIR
+ is taken from the <em>first</em> entry, but eclasses from later entries are
+ favoured.
+- <code>newsdir</code> (default: <code>${location}/metadata/news</code>), which
+ controls where GLEP 42 news items are located.
+- <code>securitydir</code> (default: <code>${location}/metadata/security</code>),
+ which controls where security advisories are located.
+- <code>setsdir</code> (default: <code>${location}/sets</code>), which controls
+ where package set files are located.
+- <code>sync</code> (default: empty), which controls how the repository is
+ synced. Typically values are in the form <code>rsync://rsync.europe.gentoo.org/gentoo-portage</code>
+ or <code>svn://svn.berlios.de/paludis/overlay</code>. Use
+ <code>paludis --list-sync-protocols</code> to see supported protocols.
+- <code>sync_exclude</code> (default: empty), which can point to a file that
+ contains a list of directories to exclude when syncing via
+ <code>rsync://</code>.
+\subsection ConfigurationFilesRepositoriesVDB vdb Format Repositories
+You should have exactly one VDB format repository. It holds packages that have
+been installed from a <code>portage</code> format repository.
+The following keys are available for <code>format = vdb</code>:
+- <code>location</code> (mandatory), which <strong>must</strong> be set to
+ <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>world</code> (default: <code>${location}/world</code>), which is used
+ for the world file.
+\subsection ConfigurationFilesRepositoriesNothing nothing Format Repositories
+Usually you won't have any <code>nothing</code> repositories. They are used as
+a convenience when certain locations have to be synced at <code>--sync</code>
+time; they do not contain any packages.
+The following keys are available for <code>format = vdb</code>:
+- <code>location</code> (mandatory).
+- <code>sync</code> (default: empty), as per <code>format = portage</code>.
+- <code>sync_exclude</code> (default: empty), idem.
diff --git a/doc/doc_mainpage.doxygen b/doc/doc_mainpage.doxygen
index 9347d59..8d4d432 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/doc_mainpage.doxygen
@@ -8,11 +8,13 @@ This is the documentation for Paludis, the other package manager. It is availabl
\section userdocs For End Users
-You shouldn't be touching Paludis at the moment. Paludis will delete all your
-files, then delete everyone else's files, then rape your dog. Go away.
+Paludis is still undergoing heavy development. It is not a mature solution, and
+still has quite a few missing features. You <b>will</b> run into bugs if you use
+Paludis (some of which may leave your system unusable). Most ebuild authors do
+not test their code with both package managers.
-If you're still here, read \link BootstrapHowto the Bootstrap HOWTO \endlink for
-how to break your system or possibly set up a chroot. You may also like to read
+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
@@ -34,15 +36,10 @@ checkout</a>, and reading the \link PortageDifferences Paludis and Portage
differences \endlink document.
It's best to start by skimming over the main program to get a feel for how
-everything fits together. Useful files:
+everything fits together. The interface code is kept in the src/ directory,
+and library code is in paludis/ .
-- src/paludis.cc The main program.
-- src/query.cc The --query action handler.
-- src/install.cc The --install action handler.
-- src/applets.cc Various small action handlers.
-- src/list.cc The --list action handlers
-After that, the following classes are good places to begin:
+The following classes are good places to begin:
- paludis::DefaultEnvironment provides a representation of the default
operating environment.
diff --git a/doc/doxygen.conf.in b/doc/doxygen.conf.in
index 81d94fb..7357786 100644
--- a/doc/doxygen.conf.in
+++ b/doc/doxygen.conf.in
@@ -452,7 +452,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = ../paludis ../paludis/args ../paludis/util ../test ../doc ../src
+INPUT = ../paludis ../paludis/args ../paludis/util ../paludis/digests ../paludis/selinux ../test ../doc ../src
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp