aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-09-26 22:17:46 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-09-26 22:17:46 +0000
commit1b07de4ddd7d54b1aff56d9c48fc43596554d482 (patch)
tree427d8c062e27b5989789d5222f015d761e9de64a
parentb2c5636d0262ac180ce5319f464de5bb5ee3f420 (diff)
downloadpaludis-1b07de4ddd7d54b1aff56d9c48fc43596554d482.tar.gz
paludis-1b07de4ddd7d54b1aff56d9c48fc43596554d482.tar.xz
Start reworking docs, examples
-rw-r--r--doc/Makefile.am25
-rw-r--r--doc/doc_main.doxygen492
-rw-r--r--doc/doc_mainpage.doxygen7
-rw-r--r--doc/doxygen.conf.in4
-rw-r--r--doc/examples/Makefile.am22
-rw-r--r--doc/examples/example_about.cc34
-rw-r--r--doc/examples/example_action.cc107
-rw-r--r--doc/examples/example_dep_label.cc186
-rw-r--r--doc/examples/pwp_basic_cplusplus_app.cc39
-rw-r--r--doc/examples/pwp_basic_ruby_app.rb14
-rw-r--r--doc/header.html1
-rw-r--r--doc/index.html.skel4
-rw-r--r--doc/programmingwithpaludis.html.skel278
-rw-r--r--paludis/about.hh.in32
-rw-r--r--paludis/action-fwd.hh6
-rw-r--r--paludis/action.hh252
-rw-r--r--paludis/action.se18
-rw-r--r--paludis/action.sr10
-rw-r--r--paludis/contents-fwd.hh14
-rw-r--r--paludis/contents.hh23
20 files changed, 667 insertions, 901 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f0cf546..44e9587 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -26,7 +26,6 @@ htmlfiles = \
cachefiles.html \
configuration.html \
portagedifferences.html \
- programmingwithpaludis.html \
sets.html \
hooks.html \
man-paludis.html \
@@ -41,11 +40,11 @@ EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css epydoc.css \
$(docfiles) $(tagfiles) $(images) htaccess \
news.html.skel index.html.skel changelog.html.skel licence.html.skel authors.html.skel \
faq.html.skel htmlheader.html htmlfooter.html migration.html.skel cachefiles.html.skel \
- configuration.html.skel portagedifferences.html.skel programmingwithpaludis.html.skel \
+ configuration.html.skel portagedifferences.html.skel \
sets.html.skel hooks.html.skel man.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
- migration.html cachefiles.html configuration.html portagedifferences.html programmingwithpaludis.html \
+ migration.html cachefiles.html configuration.html portagedifferences.html \
sets.html hooks.html man-paludis.html man-qualudis.html man-contrarius.html man-adjutrix.html man-inquisitio.html \
man-accerso.html man-instruo.html \
cleannews cleanrecentnews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
@@ -209,26 +208,6 @@ portagedifferences.html : portagedifferences.html.skel htmlheader.html htmlfoote
-e '/@FOOTER@/d' \
< $(srcdir)/portagedifferences.html.skel > portagedifferences.html
-cleanbasiccppapp : $(srcdir)/examples/pwp_basic_cplusplus_app.cc
- sed -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' \
- < $(srcdir)/examples/pwp_basic_cplusplus_app.cc > cleanbasiccppapp
-
-cleanbasicrubyapp : $(srcdir)/examples/pwp_basic_ruby_app.rb
- sed -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' \
- < $(srcdir)/examples/pwp_basic_ruby_app.rb > cleanbasicrubyapp
-
-programmingwithpaludis.html : programmingwithpaludis.html.skel htmlheader.html htmlfooter.html \
- cleanbasiccppapp cleanbasicrubyapp
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@BASIC_CPP_APP@/r cleanbasiccppapp' \
- -e '/@BASIC_CPP_APP@/d' \
- -e '/@BASIC_RUBY_APP@/r cleanbasicrubyapp' \
- -e '/@BASIC_RUBY_APP@/d' \
- < $(srcdir)/programmingwithpaludis.html.skel > programmingwithpaludis.html
-
cachefiles.html : cachefiles.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
diff --git a/doc/doc_main.doxygen b/doc/doc_main.doxygen
index 2f4161f..679ebee 100644
--- a/doc/doc_main.doxygen
+++ b/doc/doc_main.doxygen
@@ -1,495 +1,49 @@
/* vim: set ft=cpp tw=80 sw=4 et : */
-// ----- Top Level Groups -----
-
-/** \defgroup grplibpaludis Main Paludis library
- */
-
-/** \defgroup grplibpaludisutil Paludis utilities library
- */
-
-/** \defgroup grplibpaludistasks Paludis tasks library
- */
-
-/** \defgroup grplibpaludisxml Paludis XML wrapper library
- */
-
-/** \defgroup grplibpaludisqa Paludis QA library
- */
-
-/** \defgroup grplibpaludisargs Paludis args library
- */
-
-/** \defgroup grplibpaludisdigests Paludis digests library
- */
-
-/** \defgroup grplibpaludisselinux Paludis SELinux library
- */
-
-/** \defgroup grptestcases Test cases
- */
-
-/** \defgroup grpexceptions Exceptions
- */
-
-// ----- grplibpaludistasks Subgroups -----
-
-/** \defgroup grptasks Tasks
- *
- * \ingroup grplibpaludistasks
- */
-
-// ----- grplibpaludisxml Subgroups -----
-
-/** \defgroup grpxml XML Wrappers
- *
- * \ingroup grplibpaludisxml
- */
-
-// ----- grplibpaludis Subgroups -----
-
-/** \defgroup grpdependencies Dependencies
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpabout About Paludis
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpconfigfile Configuration files
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpdistributions Distributions
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpeapi EAPIs
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpenvironment Environment
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grphashedcontainers Hashed containers
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grphooker Hooker
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpmerger Merger
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpunmerger Unmerger
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpnames Names
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grphosttuplename Host tuple names
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpversions Versions
- *
- * \ingroup grplibpaludis
- */
-
-/** \defgroup grpcontents Contents
- *
- * \ingroup grplibpaludis
- */
-
-// ----- grpconfigfile Subgroups -----
-
-/** \defgroup grpkvconfigfile Key/Value configuration file
- *
- * \ingroup grpconfigfile
- */
-
-/** \defgroup grplineconfigfile Line configuration file
- *
- * \ingroup grpconfigfile
- */
-
-/** \defgroup grpadvisoryconfigfile Security advisory file
- *
- * \ingroup grpconfigfile
- */
-
-/** \defgroup grpnewsconfigfile News file
- *
- * \ingroup grpconfigfile
- */
-
-/** \defgroup grpsetfile Set files
- *
- * \ingroup grpconfigfile
- */
-
-// ----- grpenvironment Subgroups -----
-
-/** \defgroup grpadaptedenvironment Adapted environment
- *
- * \ingroup grpenvironment
- */
-
-/** \defgroup grppaludisenvironment Paludis environment
- *
- * \ingroup grpenvironment
- */
-
-/** \defgroup grpportageenvironment Portage environment
- *
- * \ingroup grpenvironment
- */
-
-/** \defgroup grptestenvironment Test environment
- *
- * \ingroup grpenvironment
- */
-
-/** \defgroup grpnoconfigenvironment No config environment
- *
- * \ingroup grpenvironment
- */
-
-/** \defgroup grppackagedatabase Package database
+/** \defgroup g_paludis Paludis
*
- * \ingroup grpenvironment
+ * Paludis public API.
*/
-/** \defgroup grpmaskreasons Mask reasons
+/** \defgroup g_about About
*
- * \ingroup grpenvironment
- */
-
-// ----- grppaludisenvironment Subgroups -----
-
-/** \defgroup grppaludisconfig Paludis environment configuration
+ * \ingroup g_paludis
*
- * \ingroup grppaludisenvironment
- */
-
-// --- grppackagedatabase Subgroups -----
-
-/** \defgroup grprepository Repositories
+ * Information about Paludis (version, build options etc).
*
- * \ingroup grppackagedatabase
- */
-
-/** \defgroup grpquery Queries
- *
- * \ingroup grppackagedatabase
- */
-
-// --- grprepository Subgroups -----
-
-/** \defgroup grpfakerepository Fake repository
- *
- * \ingroup grprepository
- */
-
-/** \defgroup grpgemsrepository Gems repository
+ * \section Examples
*
- * \ingroup grprepository
+ * - \ref example_about.cc "example_about.cc"
*/
-/** \defgroup grperepository Portage repository
+/** \defgroup g_actions Actions
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpnothingrepository Nothing repository
+ * \ingroup g_paludis
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpvdbrepository VDB repository
+ * Action-related classes are used to provide the information needed by a
+ * PackageID to perform operations such as installing, uninstalling and fetching.
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpcranrepository CRAN repository
+ * \section Examples
*
- * \ingroup grprepository
+ * - \ref example_action.cc "example_action.cc"
*/
-/** \defgroup grpcraninstrepository CRAN installed repository
+/** \defgroup g_dep_spec Dependency specifications
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpvirtualsrepository Virtuals repository
+ * \ingroup g_paludis
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpcrandesc CRAN descriptions
+ * Dependency specification classes provide an abstraction representing
+ * dependency and dependency-like (for example, SRC_URI, RESTRICT)
+ * heirarchies.
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpebuildinterface Ebuild interface
+ * \section Examples
*
- * \ingroup grprepository
+ * - \ref example_dep_label.cc "example_dep_label.cc"
*/
-/** \defgroup grpebininterface Ebin interface
+/** \defgroup g_exceptions Exceptions
*
- * \ingroup grprepository
- */
-
-/** \defgroup grpsyncer Sync protocol handler classes
+ * Exceptions and related utility classes.
*
- * \ingroup grprepository
+ * \ingroup g_paludis
*/
-
-// ----- grpdepspecs Subgroups -----
-
-/** \defgroup grpdepspecdumper Dep spec dumper
- *
- * \ingroup grpdepspecs
- */
-
-/** \defgroup grpdepspecflattener Dep spec flattener
- *
- * \ingroup grpdepspecs
- */
-
-/** \defgroup grpdepspecprettyprinter Dep spec pretty printer
- *
- * \ingroup grpdepspecs
- */
-
-/** \defgroup grpdeptag Dependency tags
- *
- * \ingroup grpdepspecs
- */
-
-// ----- grpdependencies Subgroups -----
-
-/** \defgroup grpdepresolver Dependency resolution
- *
- * \ingroup grpdependencies
- */
-
-/** \defgroup grpuninstalllist Uninstall (reverse dependency) resolution
- *
- * \ingroup grpdependencies
- */
-
-/** \defgroup grpdepspecs Dependency specs
- *
- * \ingroup grpdependencies
- */
-
-/** \defgroup grpdepparser Dependency parsing
- *
- * \ingroup grpdependencies
- */
-
-/** \defgroup grpmatchpackage Match package
- *
- * \ingroup grpdependencies
- */
-
-// ----- grpdepparser Subgroups -----
-
-/** \defgroup grpdeplexer Dependency lexing
- *
- * \ingroup grpdepparser
- */
-
-// ----- grplibpaludisutil Subgroups -----
-
-/** \defgroup grpcollections Collections
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpcompare Comparisons
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpclone Clone
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpoperators Operators
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpgraph Graphs
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpiterators Iterators
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpoptions Options Container
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpnamedarguments Named arguments
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grppatterns Patterns
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grppipe Pipes
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpfdotputstream FD Output
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grppointers Pointers
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpdeleter Deleter
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpfilesystem Filesystem
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpstrings Strings
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grplog Log
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpsystem System
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grprandom Random numbers
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpsave Save
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpsr Smart Record
- *
- * \ingroup grplibpaludisutil
- */
-
-/** \defgroup grpvalidated Validated
- *
- * \ingroup grplibpaludisutil
- */
-
-// ----- grppatterns Subgroups -----
-
-/** \defgroup grpinstance Instance patterns
- *
- * \ingroup grppatterns
- */
-
-/** \defgroup grppimp Private implementation pattern
- *
- * \ingroup grppatterns
- */
-
-/** \defgroup grpvc Virtual constructor
- *
- * \ingroup grppatterns
- */
-
-/** \defgroup grpvisitor Visitor
- *
- * \ingroup grppatterns
- */
-
-// ----- grpstrings Subgroups -----
-
-/** \defgroup grpdestringify Destringify
- *
- * \ingroup grpstrings
- */
-
-/** \defgroup grpjoin Join
- *
- * \ingroup grpstrings
- */
-
-/** \defgroup grpstringify Stringify
- *
- * \ingroup grpstrings
- */
-
-/** \defgroup grptokenise Tokenise
- *
- * \ingroup grpstrings
- */
-
-/** \defgroup grpmatch Match
- *
- * \ingroup grpstrings
- */
-
-/** \defgroup grpstrippers Strippers
- *
- * \ingroup grpstrings
- */
-
-// ----- grplibpaludisqa Subgroups -----
-
-/** \defgroup grpqa QA
- *
- * \ingroup libpaludisqa
- */
-
-/** \defgroup grpqacheck QA Checks
- *
- * \ingroup libpaludisqa
- */
-
-
diff --git a/doc/doc_mainpage.doxygen b/doc/doc_mainpage.doxygen
index 95fc6b7..a938998 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/doc_mainpage.doxygen
@@ -2,12 +2,7 @@
/** \mainpage
-This is the documentation for the Paludis C++ core API. There is rather a lot
-of it, and you will probably have trouble finding your way around if you just
-jump right into the middle of it. Instead, start by reading the
-<a href="/programmingwithpaludis.html">Programming with Paludis</a> guide.
-Once you've done that, try the <a href="modules.html">Modules</a> link rather
-than the full class lists.
+This is the Paludis core API documentation.
Some classes you may find useful:
diff --git a/doc/doxygen.conf.in b/doc/doxygen.conf.in
index b4a13c0..0b8d361 100644
--- a/doc/doxygen.conf.in
+++ b/doc/doxygen.conf.in
@@ -461,7 +461,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = ../paludis ../paludis/args ../paludis/dep_list ../paludis/digests ../paludis/environments ../paludis/environments/no_config ../paludis/environments/adapted ../paludis/environments/portage ../paludis/environments/paludis ../paludis/environments/test ../paludis/fetchers ../paludis/merger ../paludis/repositories ../paludis/repositories/cran ../paludis/repositories/fake ../paludis/repositories/gems ../paludis/repositories/e ../paludis/repositories/virtuals ../paludis/selinux ../paludis/syncers ../paludis/tasks ../paludis/util ../doc
+INPUT = ../paludis ../paludis/args ../paludis/dep_list ../paludis/digests ../paludis/environments ../paludis/environments/no_config ../paludis/environments/adapted ../paludis/environments/portage ../paludis/environments/paludis ../paludis/environments/test ../paludis/fetchers ../paludis/merger ../paludis/repositories ../paludis/repositories/cran ../paludis/repositories/fake ../paludis/repositories/gems ../paludis/repositories/e ../paludis/repositories/virtuals ../paludis/selinux ../paludis/syncers ../paludis/tasks ../paludis/util ../doc ../doc/examples
# 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
@@ -470,7 +470,7 @@ INPUT = ../paludis ../paludis/args ../paludis/dep_list ../paludis/digests ../pal
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
-FILE_PATTERNS = *.hh *.doxygen
+FILE_PATTERNS = *.hh *.doxygen example_*.cc
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index 35bf9a3..54bbba1 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -9,20 +9,24 @@ DEFS= \
SUBDIRS = .
-if ! MONOLITHIC
-
noinst_PROGRAMS = \
- pwp_basic_cplusplus_app
+ example_about \
+ example_action \
+ example_dep_label
-noinst_SCRIPTS = \
- pwp_basic_ruby_app.rb
+EXTRA_DIST = $(noinst_SCRIPTS)
-endif
+example_about_SOURCES = example_about.cc
+example_about_LDFLAGS = \
+ $(top_builddir)/paludis/libpaludis.la
-EXTRA_DIST = $(noinst_SCRIPTS)
+example_action_SOURCES = example_action.cc
+example_action_LDFLAGS = \
+ $(top_builddir)/paludis/libpaludis.la \
+ $(top_builddir)/paludis/environments/libpaludisenvironments.la
-pwp_basic_cplusplus_app_SOURCES = pwp_basic_cplusplus_app.cc
-pwp_basic_cplusplus_app_LDFLAGS = \
+example_dep_label_SOURCES = example_dep_label.cc
+example_dep_label_LDFLAGS = \
$(top_builddir)/paludis/libpaludis.la \
$(top_builddir)/paludis/environments/libpaludisenvironments.la
diff --git a/doc/examples/example_about.cc b/doc/examples/example_about.cc
new file mode 100644
index 0000000..84c52cc
--- /dev/null
+++ b/doc/examples/example_about.cc
@@ -0,0 +1,34 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_about.cc "example_about.cc" .
+ *
+ * \ingroup g_about
+ */
+
+/** \example example_about.cc
+ *
+ * A simple example showing how to use Paludis version macros.
+ */
+
+#include <paludis/paludis.hh>
+#include <iostream>
+#include <cstdlib>
+
+using std::cout;
+using std::endl;
+
+int main(int, char *[])
+{
+ cout << "Built using Paludis " << PALUDIS_VERSION_MAJOR << "." << PALUDIS_VERSION_MINOR
+ << "." << PALUDIS_VERSION_MICRO;
+
+ if (! std::string(PALUDIS_SUBVERSION_REVISION).empty())
+ cout << " " << PALUDIS_SUBVERSION_REVISION;
+
+ cout << endl;
+
+ return EXIT_SUCCESS;
+}
+
diff --git a/doc/examples/example_action.cc b/doc/examples/example_action.cc
new file mode 100644
index 0000000..4b852e6
--- /dev/null
+++ b/doc/examples/example_action.cc
@@ -0,0 +1,107 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_action.cc "example_action.cc" .
+ *
+ * \ingroup g_actions
+ */
+
+/** \example example_action.cc
+ *
+ * This example demonstrates how to use actions. It uses FetchAction to fetch
+ * source files for all versions of sys-apps/paludis that support fetching.
+ */
+
+#include <paludis/paludis.hh>
+#include <iostream>
+
+using namespace paludis;
+using std::cout;
+using std::endl;
+
+int main(int, char *[])
+{
+ int exit_status(0);
+
+ /* We start with an Environment. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(""));
+
+ /* Fetch package IDs for 'sys-apps/paludis'. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::Matches(PackageDepSpec("sys-apps/paludis", pds_pm_permissive)),
+ qo_order_by_version));
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ /* Do we support a FetchAction? We find out by creating a
+ * SupportsActionTest<FetchAction> object, and querying via the
+ * PackageID::supports_action method. */
+ SupportsActionTest<FetchAction> supports_fetch_action;
+ if (! (*i)->supports_action(supports_fetch_action))
+ {
+ cout << "ID '" << **i << "' does not support the fetch action." << endl;
+ }
+ else
+ {
+ cout << "ID '" << **i << "' supports the fetch action, trying to fetch:" << endl;
+
+ /* Carry out a FetchAction. We need to specify various options when
+ * creating a FetchAction, controlling whether safe resume is used
+ * and whether unneeded (e.g. due to disabled USE flags) source
+ * files should still be fetched. */
+ FetchAction fetch_action(FetchActionOptions::create()
+ .fetch_unneeded(false)
+ .safe_resume(true)
+ );
+ try
+ {
+ (*i)->perform_action(fetch_action);
+ }
+ catch (const FetchActionError & e)
+ {
+ exit_status |= 1;
+
+ cout << "Caught FetchActionError, with the following details:" << endl;
+
+ /* We might get detailed information about individual fetch
+ * failures. */
+ for (Sequence<FetchActionFailure>::ConstIterator f(e.failures()->begin()), f_end(e.failures()->end()) ;
+ f != f_end ; ++f)
+ {
+ cout << " * File '" << f->target_file << "': ";
+
+ bool need_comma(false);
+ if (f->requires_manual_fetching)
+ {
+ cout << "requires manual fetching";
+ need_comma = true;
+ }
+
+ if (f->failed_automatic_fetching)
+ {
+ if (need_comma)
+ cout << ", ";
+ cout << "failed automatic fetching";
+ need_comma = true;
+ }
+
+ if (! f->failed_integrity_checks.empty())
+ {
+ if (need_comma)
+ cout << ", ";
+ cout << "failed integrity checks: " << f->failed_integrity_checks;
+ need_comma = true;
+ }
+ }
+
+ cout << endl;
+ }
+ }
+ }
+
+ return exit_status;
+}
+
diff --git a/doc/examples/example_dep_label.cc b/doc/examples/example_dep_label.cc
new file mode 100644
index 0000000..914c299
--- /dev/null
+++ b/doc/examples/example_dep_label.cc
@@ -0,0 +1,186 @@
+/* vim: set sw=4 sts=4 et foldmethod=syntax : */
+
+/** \file
+ *
+ * Example \ref example_dep_label.cc "example_dep_label.cc" .
+ *
+ * \ingroup g_dep_spec
+ */
+
+/** \example example_dep_label.cc
+ *
+ * This example demonstrates how to handle dependency labels. It produces a
+ * summary of distfiles for all installed packages, together with a notice of
+ * whether that distfile is fetch-restricted.
+ */
+
+#include <paludis/paludis.hh>
+#include <iostream>
+#include <iomanip>
+#include <algorithm>
+#include <cstdlib>
+#include <list>
+#include <map>
+
+using namespace paludis;
+using std::cout;
+using std::endl;
+using std::setw;
+
+/* We store our results in a map from distfile name to whether it is fetch
+ * restricted. */
+typedef std::map<std::string, bool> ResultsMap;
+
+namespace
+{
+ /* This visitor class is used to determine whether a label represents a
+ * fetch restriction. */
+ class IsLabelRestrictedVisitor :
+ public ConstVisitor<URILabelVisitorTypes>
+ {
+ public:
+ bool result;
+
+ IsLabelRestrictedVisitor(const bool initial) :
+ result(initial)
+ {
+ }
+
+ void visit(const URIListedThenMirrorsLabel &)
+ {
+ result = false;
+ }
+
+ void visit(const URIListedOnlyLabel &)
+ {
+ result = false;
+ }
+
+ void visit(const URIMirrorsOnlyLabel &)
+ {
+ result = false;
+ }
+
+ void visit(const URIMirrorsThenListedLabel &)
+ {
+ result = false;
+ }
+
+ void visit(const URILocalMirrorsOnlyLabel &)
+ {
+ result = true;
+ }
+
+ void visit(const URIManualOnlyLabel &)
+ {
+ result = true;
+ }
+ };
+
+ /* This visitor class collects src_uri entries and stores the result in
+ * a provided map. Label statuses are handled by a stack. When we enter
+ * a block (an AllDepSpec or a UseDepSpec), we duplicate the top item
+ * of the stack, since labels recurse into subblocks. When we encounter
+ * a label, we replace the top item of the stack. */
+ class DistfilesCollector :
+ public ConstVisitor<URISpecTree>
+ {
+ private:
+ ResultsMap & _results;
+ std::list<bool> _restricted;
+
+ public:
+ DistfilesCollector(ResultsMap & r, const bool initial) :
+ _results(r)
+ {
+ _restricted.push_back(initial);
+ }
+
+ void visit_sequence(const AllDepSpec &,
+ URISpecTree::ConstSequenceIterator cur,
+ URISpecTree::ConstSequenceIterator end)
+ {
+ /* When we encounter an AllDepSpec, duplicate the top item of
+ * our restricted stack, and then recurse over all of its
+ * children, and then restore the stack. */
+ _restricted.push_back(_restricted.back());
+ std::for_each(cur, end, accept_visitor(*this));
+ _restricted.pop_back();
+ }
+
+ void visit_sequence(const UseDepSpec &,
+ URISpecTree::ConstSequenceIterator cur,
+ URISpecTree::ConstSequenceIterator end)
+ {
+ /* Always recurse over a UseDepSpec's children. In real world
+ * code, we would more likely check whether the use flag is
+ * accepted. */
+ _restricted.push_back(_restricted.back());
+ std::for_each(cur, end, accept_visitor(*this));
+ _restricted.pop_back();
+ }
+
+ void visit_leaf(const URIDepSpec & s)
+ {
+ /* When we encounter a URIDepSpec, store its distfile name.
+ * We handle 'a -> b' style specs by taking 'b' as the
+ * distfile name. */
+ _results.insert(std::make_pair(s.renamed_url_suffix(), _restricted.back()));
+ }
+
+ void visit_leaf(const LabelsDepSpec<URILabelVisitorTypes> & l)
+ {
+ /* Find out whether the label represents a fetch restriction.
+ * Change the top item of the stack as appropriate. Although
+ * a LabelsDepSpec can contain multiple labels, only the last
+ * one is relevant. */
+ IsLabelRestrictedVisitor v(_restricted.back());
+ std::for_each(indirect_iterator(l.begin()), indirect_iterator(l.end()), accept_visitor(v));
+ _restricted.back() = v.result;
+ }
+ };
+}
+
+int main(int, char *[])
+{
+ /* We start with an Environment. */
+ tr1::shared_ptr<Environment> env(EnvironmentMaker::get_instance()->make_from_spec(""));
+
+ /* Fetch package IDs for all installed packages. */
+ tr1::shared_ptr<const PackageIDSequence> ids(env->package_database()->query(
+ query::SupportsAction<InstalledAction>(),
+ qo_whatever));
+
+ /* Store a map from distfile name to whether it is fetch restricted. */
+ ResultsMap results;
+
+ /* For each ID: */
+ for (PackageIDSet::ConstIterator i(ids->begin()), i_end(ids->end()) ;
+ i != i_end ; ++i)
+ {
+ /* If we don't have a src_uri key, skip this package. All PackageID
+ * _key() functions can potentially return zero pointers, so checking is
+ * essential. */
+ if (! (*i)->src_uri_key())
+ continue;
+
+ /* We need to know whether the default label for this package's src_uri
+ * is restricted. */
+ IsLabelRestrictedVisitor is_initial_label_restricted(false);
+ (*i)->src_uri_key()->initial_label()->accept(is_initial_label_restricted);
+
+ /* Create a visitor that will collect distfiles, and do the collecting. */
+ DistfilesCollector collector(results, is_initial_label_restricted.result);
+ (*i)->src_uri_key()->value()->accept(collector);
+ }
+
+ /* Display summary of results */
+ cout << setw(60) << "Distfile Name" << ": " << "Fetch Restricted?" << endl;
+ for (ResultsMap::const_iterator r(results.begin()), r_end(results.end()) ;
+ r != r_end ; ++r)
+ cout << setw(60) << r->first << ": " << (r->second ? "yes" : "no") << endl;
+
+ return EXIT_SUCCESS;
+}
+
+
diff --git a/doc/examples/pwp_basic_cplusplus_app.cc b/doc/examples/pwp_basic_cplusplus_app.cc
deleted file mode 100644
index 4a327ae..0000000
--- a/doc/examples/pwp_basic_cplusplus_app.cc
+++ /dev/null
@@ -1,39 +0,0 @@
-/* vim: set sw=4 sts=4 et foldmethod=syntax : */
-
-#include <paludis/paludis.hh>
-#include <paludis/environments/environment_maker.hh>
-
-#include <iostream>
-#include <cstdlib>
-
-using std::cout;
-using std::cerr;
-using std::endl;
-
-int main(int, char *[])
-{
- try
- {
- paludis::tr1::shared_ptr<paludis::Environment> env(
- paludis::EnvironmentMaker::get_instance()->make_from_spec(""));
-
- paludis::tr1::shared_ptr<const paludis::PackageIDSequence> packages(
- env->package_database()->query(
- paludis::query::Matches(paludis::PackageDepSpec("app-editors/vim", paludis::pds_pm_eapi_0_strict)) &
- paludis::query::InstalledAtRoot(env->root()), paludis::qo_order_by_version));
-
- if (packages->empty())
- cout << "Vim is not installed" << endl;
- else
- cout << "Vim " << (*packages->last())->canonical_form(paludis::idcf_version) << " is installed" << endl;
- }
- catch (const paludis::Exception & e)
- {
- cerr << "Caught exception '" << e.message() << "' ("
- << e.what() << ")" << endl;
- return EXIT_FAILURE;
- }
-
- return EXIT_SUCCESS;
-}
-
diff --git a/doc/examples/pwp_basic_ruby_app.rb b/doc/examples/pwp_basic_ruby_app.rb
deleted file mode 100644
index 7f47558..0000000
--- a/doc/examples/pwp_basic_ruby_app.rb
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/usr/bin/ruby
-# vim: set sw=4 sts=4 et tw=80 :
-
-require 'Paludis'
-
-packages = Paludis::EnvironmentMaker.instance.make_from_spec('').package_database.query(
- "app-editors/vim", Paludis::InstallState::InstalledOnly, Paludis::QueryOrder::OrderByVersion)
-
-if packages.empty?
- puts "Vim is not installed"
-else
- puts "Vim " + packages.last.version.to_s + " is installed"
-end
-
diff --git a/doc/header.html b/doc/header.html
index 9f7adff..7eb915a 100644
--- a/doc/header.html
+++ b/doc/header.html
@@ -57,6 +57,7 @@
<div class="qindex">Code Documentation: [
<a class="qindex" href="modules.html">Modules</a> |
+ <a class="qindex" href="examples.html">Examples</a> |
<a class="qindex" href="namespaces.html">Namespaces</a> |
<a class="qindex" href="annotated.html">Classes</a> |
<a class="qindex" href="files.html">Files</a> |
diff --git a/doc/index.html.skel b/doc/index.html.skel
index d0d9b8e..2bd316a 100644
--- a/doc/index.html.skel
+++ b/doc/index.html.skel
@@ -78,10 +78,6 @@
is also <a href="http://paludis.pioto.org/trac/browser">Trac's
code browser</a> for viewing via the web.</li>
- <li>An <a href="programmingwithpaludis.html">overview of
- Programming with Paludis</a>, covering both the C++ and the
- Ruby APIs, is available.</li>
-
<li>There is <a href="doxygen/html"/>extensive C++ core API and implementation
documentation</a>. This is also available via <code>make
doxygen</code>.</li>
diff --git a/doc/programmingwithpaludis.html.skel b/doc/programmingwithpaludis.html.skel
deleted file mode 100644
index 5e78cce..0000000
--- a/doc/programmingwithpaludis.html.skel
+++ /dev/null
@@ -1,278 +0,0 @@
-<!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>Programming with Paludis, the Other Package Mangler</h1>
-
-<p>You can get a <a href="http://paludis.pioto.org/trac/browser/">Subversion
- checkout</a> of <code>trunk/</code> rather than working off a tarball. If you're
-planning to submit patches, you'll have to do this.</p>
-
-<p>It's best to start by skimming over the main program to get a feel for how
-everything fits together. The interface code is kept in the src/ directory,
-and library code is in paludis/ .</p>
-
-<h2>Basics</h2>
-
-<p>There are currently two APIs available:</p>
-
-<ul>
- <li>The C++ API. This offers the full range of functionality. <a
- href="doxygen/html/">Full Doxygen documentation</a> is available.</li>
- <li>The Ruby API. This offers a subset of the functionality and is aimed at script and utility
- authors. Not every class or method is currently available; support for more classes and
- methods can be added as needed. Some things (for example, defining new Environment subclasses)
- will likely never be available through this interface. <a href="ruby/">Full
- Rdoc documentation</a> is available.</li>
-</ul>
-
-<p>A basic C++ application will look something like:</p>
-
-<pre>
-@BASIC_CPP_APP@
-</pre>
-
-<p>Compile this using <code>g++ -Wall -lpaludis
- -lpaludisenvironments</code>. If your compiler lacks tr1 support, you
-may also need <code>-I/usr/include/paludis/compat</code>.</p>
-
-<p>The same application written in Ruby will look something like:</p>
-
-<pre>
-@BASIC_RUBY_APP@
-</pre>
-
-<p>Notice how various Rubyisms (singleton styles, question mark methods, constants
-for enums) are used. The Ruby interface aims to be natural to Ruby programmers
-and behave like a Ruby library, rather than being an exact translation.</p>
-
-<p>Make sure you can run both of these examples before reading on.</p>
-
-<h2>Common Patterns</h2>
-
-<p>A number of common patterns are used throughout the code.</p>
-
-<h3>Iterators</h3>
-
-<p>STL style iterator pairs crop up in various places. Where this happens, there is
-usually a member typedef named <code>Iterator</code> or <code>FooIterator</code>,
-along with members named <code>begin</code> and <code>end</code> or <code>begin_foo</code>
-and <code>end_foo</code>. See <a href="doxygen/html/References.html">TCppSL</a>
-if you are unfamiliar with this style.</p>
-
-<p>The underlying iterator format is usually hidden from the library programmer by a
-<code>libwrapiter::ForwardIterator</code>. This is to speed up compile times and to avoid breaking
-lots of things when underlying data types change.</p>
-
-<p>Ruby works better with blocks than external iterators. Thus, instead of providing
-<code>begin_foo</code> and <code>end_foo</code> methods, Ruby classes typically have
-a single <code>foo</code> member function that returns an array made from the
-iterator range. This is slower, but much easier.</p>
-
-<h3>Pointers</h3>
-
-<p>We make extensive use of <code>std::tr1::shared_ptr</code>. Make sure you know how it
-works. See <a href="doc/html/References.html">TCppSLE</a>.</p>
-
-<p>This is all hidden in the Ruby interface. You shouldn't have to care about
-memory management.</p>
-
-<h3>Validated Names</h3>
-
-<p>Rather than using <code>std::string</code> for package, category etc names, we have a wrapper
-class template called <code>paludis::Validated</code>, and a bunch of typedefs
-(<code>paludis::CategoryNamePart</code>, <code>paludis::PackageNamePart</code>,
-<code>paludis::SlotName</code> etc). This gives a couple of benefits:</p>
-
-<ul>
- <li>It catches certain screwups (e.g. passing the wrong parameter types) at
- compile time.</li>
- <li>It means exceptions caused by weird data (e.g. from user input) are caught at a sensible
- place, rather than sometime weird later on.</li>
-</ul>
-
-<p>Ruby doesn't do static checking, so it just uses raw <code>String</code>
-instances for all of these.</p>
-
-<h3>Collections</h3>
-
-<p>Sometimes we need to pass around a collection of items. The
-<code>paludis::SortedCollection</code>,
-<code>paludis::SequentialCollection</code> and
-<code>paludis::AssociativeCollection</code> wrappers handle this.
-They are passed around via smart pointers to avoid copying.</p>
-
-<p>The basic classes are abstract. Use
-<code>paludis::SortedCollection::Concrete</code> etc if you need
-to make one yourself.</p>
-
-<p>In Ruby these are converted to arrays.</p>
-
-<h3>Smart Records</h3>
-
-<p>Smart records are a bit smarter than Plain Old Data structs. They might define comparison
-operators and constructors. They're used in quite a few places. Try not to worry
-about how these work internally unless you want to get a very sore head.</p>
-
-<p>Some smart records support named parameter constructors. A typical call to one of these
-looks like:</p>
-
-<pre>
-PackageDatabaseEntry my_pde(PackageDatabaseEntryParams::create()
- .package(QualifiedPackageName("app-editors/vim"))
- .version(VersionSpec("7.0.147"))
- .repository(RepositoryName("gentoo")));
-</pre>
-
-<p>Named parameters can be specified in any order.</p>
-
-<h3>Stringify</h3>
-
-<p>Many types can be converted to a <code>std::string</code> for display
-purposes. The <code>paludis::stringify()</code>
-template function will handle this. It also works for any internal and standard library data
-type that can be written to a <code>std::ostream</code>.</p>
-
-<h2>The Environment</h2>
-
-<p>At the heart of the Paludis API is a <code>paludis::Environment</code> subclass instance. All
-non-trivial clients will use one of the Environment subclasses as their starting
-point for obtaining data (<code>Environment</code> itself contains abstract members and cannot
-be used directly).</p>
-
-<h3>PaludisEnvironment and PortageEnvironment</h3>
-
-<p>The <code>paludis::PaludisEnvironment</code> and <code>paludis::PortageEnvironment</code>
-classes should be used when user configuration is to be honoured. These classes are not usually
-created directly; instead, <code>paludis::EnvironmentMaker</code> is used to obtain an
-instance:</p>
-
-<pre>
- std::string my_spec_string(...);
- std::tr1::shared_ptr&lt;paludis::Environment&gt; env(
- paludis::EnvironmentMaker::get_instance()-&lt;make_from_spec(my_spec_string));
-</pre>
-
-<p>The specification string should usually be the command line parameter value for <code>-E</code>
-or <code>--environment</code>. An empty string will give the default <code>PaludisEnvironment</code>
-or <code>PortageEnvironment</code>.</p>
-
-<p>When using <code>EnvironmentMaker</code>, linking should include
-<code>-lpaludisenvironments</code>.</p>
-
-<p>In Ruby, instances must be obtained using <code>Paludis::EnvironmentMaker</code>.</p>
-
-<h3>NoConfigEnvironment</h3>
-
-<p>The <code>paludis::NoConfigEnvironment</code> class should be used when user configuration should
-not be read, and instead the repository should be from a single particular directory.
-Multiple instances of this environment can be created if necessary.</p>
-
-<p>When using <code>NoConfigEnvironment</code>, linking should include
-<code>-lpaludisnoconfigenvironment</code>.</p>
-
-<p>In Ruby the class is <code>Paludis::NoConfigEnvironment</code>.</p>
-
-<h3>Other Environments</h3>
-
-<p>The <code>paludis::qa::QAEnvironment</code> class is used for QA environments. There is also a
-<code>paludis::TestEnvironment</code> class that is used in some test cases. These are less useful
-for most client authors.</p>
-
-<p>In Ruby the class for a QA environment is <code>Paludis::QA::QAEnvironment</code>, there is
-currently no Ruby wrapper for the test environment.</p>
-
-<h2>The Package Database</h2>
-
-<p>Every <code>paludis::Environment</code> has a
-<code>paludis::PackageDatabase</code>, which can be obtained
-via the <code>paludis::Environment::package_database()</code> method.</p>
-
-<p>The <code>PackageDatabase</code> contains a number of
-<code>paludis::Repository</code> subclass instances. These
-can be obtained using the
-paludis<code>::PackageDatabase::begin_repositories()</code> and
-<code>paludis::PackageDatabase::end_repositories()</code> pair or the
-<code>paludis::PackageDatabase::fetch_repository()</code> method.</p>
-
-<p>The <code>PackageDatabase</code> also provides a number of utility functions.
-<code>paludis::PackageDatabase::query()</code>
-can be used to fetch a <code>paludis::PackageDatabaseEntryCollection</code> containing packages
-matching a particular <code>paludis::PackageDepSpec</code>.
-<code>paludis::PackageDatabase::fetch_unique_qualified_package_name()</code>
-can be used to convert a <code>paludis::PackageNamePart</code> with no
-associated <code>paludis::CategoryNamePart</code> into
-a full <code>paludis::QualifiedPackageName</code>.</p>
-
-<p>In Ruby, the class is <code>Paludis::PackageDatabase</code> and an instance can
-only be obtained by calling <code>some_environment.package_database</code>.
-Rather than providing iterator pairs, repositories are available through the
-<code>repositories</code> method, whose return value behaves like an array of
-<code>Paludis::Repository</code> subclass instances. The
-<code>fetch_repository</code>, <code>query</code> and
-<code>fetch_unique_qualified_package_name</code> methods are available.</p>
-
-<h2>Repositories</h2>
-
-<p>The <code>paludis::Repository</code> class is an abstract base class representing a
-repository. Each <code>paludis::Repository</code> subclass provides various core functions,
-along with various optional others based upon the repository's capabilities.</p>
-
-<p>The commonly used subclasses are:</p>
-
-<ul>
- <li>paludis::ERepository, which is used for Gentoo-style ebuild
- repositories.</li>
- <li>paludis::VDBRepository, which is used for installed packages.</li>
- <li>paludis::VirtualsRepository, which is used for old-style virtuals.</li>
- <li>paludis::InstalledVirtualsRepository, which is used for old-style
- provided virtuals.</li>
-</ul>
-
-<p>Others include:</p>
-
-<ul>
-<li>paludis::CRANRepository, which is used for CRAN packages.</li>
-<li>paludis::CRANInstalledRepository, which is used for installed CRAN
-packages.</li>
-<li>paludis::FakeRepository, which is used for some test cases.</li>
-</ul>
-
-<p>Repository creation is usually handled by the
-<code>paludis::Environment</code> subclass and its
-<code>associated paludis::PackageDatabase</code>. In Ruby, this is the only way to gain access
-to a repository.</p>
-
-<p>All repositories provide some basic functions for querying their contents. Commonly used
-functions are <code>paludis::Repository::version_metadata()</code>,
-<code>paludis::Repository::has_category_named()</code>,
-<code>paludis::Repository::has_package_named()</code>,
-<code>paludis::Repository::category_names()</code>,
-<code>paludis::Repository::package_names()</code>,
-<code>paludis::Repository::version_specs()</code> and
-<code>paludis::Repository::has_version()</code>. These are available through Ruby; the has_ functions
-have a question mark suffix as per Ruby convention.</p>
-
-<p>Additional capabilities are available through optional interfaces. These can be accessed
-via members named <code>paludis::Repository::mask_interface</code>,
-<code>paludis::Repository::sets_interface</code>
-and so on -- these members will either be a pointer to the interface or a zero
-pointer.</p>
-
-<p>A full list of optional capabilities can be seen in the documentation for
-<code>paludis::RepositoryCapabilities</code>,
-from which paludis::Repository inherits.</p>
-
-<p>In Ruby, this works a bit differently. Members that return either a self reference or nil
-are available for each interface. They are named as their C++ equivalents.</p>
-
-@FOOTER@
-</body>
-</html>
-
diff --git a/paludis/about.hh.in b/paludis/about.hh.in
index faa023a..5e3a101 100644
--- a/paludis/about.hh.in
+++ b/paludis/about.hh.in
@@ -1,7 +1,7 @@
/* vim: set sw=4 sts=4 et foldmethod=syntax : */
/*
- * Copyright (c) 2005, 2006 Ciaran McCreesh <ciaranm@ciaranm.org>
+ * Copyright (c) 2005, 2006, 2007 Ciaran McCreesh <ciaranm@ciaranm.org>
*
* This file is part of the Paludis package manager. Paludis is free software;
* you can redistribute it and/or modify it under the terms of the GNU General
@@ -26,41 +26,45 @@
* Defines constants giving the Paludis version number and information about
* how Paludis was built.
*
- * \ingroup grpabout
+ * \section Examples
+ *
+ * - \ref example_about.cc "example_about.cc"
+ *
+ * \ingroup g_about
*/
/**
* The package name (eg Paludis).
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_PACKAGE "@PACKAGE@"
/**
* The major version (eg 0.4.1 -> 0).
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_VERSION_MAJOR @VERSION_MAJOR@
/**
* The minor version (eg 0.4.1 -> 4).
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_VERSION_MINOR @VERSION_MINOR@
/**
* The micro version (eg 0.4.1 -> 1).
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_VERSION_MICRO @VERSION_MICRO@
/**
* The version, two digits per part (eg 1.3.5 -> 10305).
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_VERSION ((100 * 100 * PALUDIS_VERSION_MAJOR) \
+ (100 * PALUDIS_VERSION_MINOR) + PALUDIS_VERSION_MICRO)
@@ -68,49 +72,49 @@
/**
* The subversion revision, if applicable (eg "65" or "65M" or "").
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_SUBVERSION_REVISION "@SVNVERSION@"
/**
* The CXXFLAGS used to build Paludis.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_CXXFLAGS "@CXXFLAGS@"
/**
* The LDFLAGS used to build Paludis.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_LDFLAGS "@LDFLAGS@"
/**
* The compiler used to build Paludis.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_CXX "@CXX@"
/**
* The user who built Paludis.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_USER "@BUILDUSER@"
/**
* The host on which Paludis was built.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_HOST "@BUILDHOST@"
/**
* The date when Paludis was built.
*
- * \ingroup grpabout
+ * \ingroup g_about
*/
#define PALUDIS_BUILD_DATE "@BUILDDATE@"
diff --git a/paludis/action-fwd.hh b/paludis/action-fwd.hh
index e83037d..c120f36 100644
--- a/paludis/action-fwd.hh
+++ b/paludis/action-fwd.hh
@@ -23,6 +23,12 @@
#include <iosfwd>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/action.hh .
+ *
+ * \ingroup g_actions
+ */
+
namespace paludis
{
class Action;
diff --git a/paludis/action.hh b/paludis/action.hh
index d126f1f..9b34557 100644
--- a/paludis/action.hh
+++ b/paludis/action.hh
@@ -30,11 +30,28 @@
#include <paludis/util/private_implementation_pattern.hh>
#include <paludis/util/sequence-fwd.hh>
+/** \file
+ * Declarations for action-related classes.
+ *
+ * \ingroup g_actions
+ *
+ * \section Examples
+ *
+ * - \ref example_action.cc "example_action.cc"
+ */
+
namespace paludis
{
#include <paludis/action-sr.hh>
+ /**
+ * Types for visiting an action.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
struct ActionVisitorTypes :
VisitorTypes<
ActionVisitorTypes,
@@ -50,6 +67,13 @@ namespace paludis
{
};
+ /**
+ * Types for visiting a supports action query.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
struct SupportsActionTestVisitorTypes :
VisitorTypes<
SupportsActionTestVisitorTypes,
@@ -65,80 +89,190 @@ namespace paludis
{
};
+ /**
+ * An Action represents an action that can be executed by a PackageID via
+ * PackageID::perform_action .
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE Action :
public virtual AcceptInterface<ActionVisitorTypes>
{
public:
+ ///\name Basic operations
+ ///\{
+
virtual ~Action() = 0;
+
+ ///\}
};
+ /**
+ * An InstallAction is used by InstallTask to perform a build / install on a
+ * PackageID.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE InstallAction :
public Action,
private PrivateImplementationPattern<InstallAction>,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, InstallAction>
{
public:
+ ///\name Basic operations
+ ///\{
+
InstallAction(const InstallActionOptions &);
~InstallAction();
+ ///\}
+
+ /// Options for the action.
const InstallActionOptions & options;
};
+ /**
+ * A FetchAction can be used to fetch source files for a PackageID using
+ * PackageID::perform_action .
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE FetchAction :
public Action,
private PrivateImplementationPattern<FetchAction>,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, FetchAction>
{
public:
+ ///\name Basic operations
+ ///\{
+
FetchAction(const FetchActionOptions &);
~FetchAction();
+ ///\}
+
+ /// Options for the action.
const FetchActionOptions & options;
};
+ /**
+ * An UninstallAction is used by UninstallTask to uninstall a PackageID.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE UninstallAction :
public Action,
private PrivateImplementationPattern<UninstallAction>,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, UninstallAction>
{
public:
+ ///\name Basic operations
+ ///\{
+
UninstallAction(const UninstallActionOptions &);
~UninstallAction();
+ ///\}
+
+ /// Options for the action.
const UninstallActionOptions & options;
};
+ /**
+ * InstalledAction is a dummy action used by SupportsActionTest and
+ * query::SupportsAction to determine whether a PackageID is installed.
+ *
+ * Performing an InstalledAction does not make sense and will do nothing.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE InstalledAction :
public Action,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, InstalledAction>
{
};
+ /**
+ * A PretendAction is used by InstallTask to handle install-pretend-phase
+ * checks on a PackageID.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE PretendAction :
public Action,
private PrivateImplementationPattern<PretendAction>,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, PretendAction>
{
public:
+ ///\name Basic operations
+ ///\{
+
PretendAction();
~PretendAction();
+ ///\}
+
+ /// Did our pretend phase fail?
const bool failed() const PALUDIS_ATTRIBUTE((warn_unused_result));
+
+ /// Mark the action as failed.
void set_failed();
};
+ /**
+ * A ConfigAction is used via PackageID::perform_action to execute
+ * post-install configuration (for example, via 'paludis --config')
+ * on a PackageID.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE ConfigAction :
public Action,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, ConfigAction>
{
};
+ /**
+ * An InfoAction is used via PackageID::perform_action to execute
+ * additional information (for example, via 'paludis --info')
+ * on a PackageID.
+ *
+ * This action potentially makes sense for both installed and
+ * installable packages. Unlike Ebuild EAPI-0 'pkg_info', this
+ * action is not specifically tied to installed packages.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE InfoAction:
public Action,
public AcceptInterfaceVisitsThis<ActionVisitorTypes, InfoAction>
{
};
+ /**
+ * Base class for SupportsActionTest<>.
+ *
+ * \see SupportsActionTest<>
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE SupportsActionTestBase :
public virtual AcceptInterface<SupportsActionTestVisitorTypes>
{
@@ -146,6 +280,21 @@ namespace paludis
virtual ~SupportsActionTestBase() = 0;
};
+ /**
+ * Instantiated with an Action subclass as its template parameter,
+ * SupportsActionTest<> is used by PackageID::supports_action and
+ * Repository::some_ids_might_support_action to query whether a
+ * particular action is supported by that PackageID or potentially
+ * supported by some IDs in that Repository.
+ *
+ * Use of a separate class, rather than a mere Action, avoids the
+ * need to create bogus options for the more complicated Action
+ * subclasses.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
template <typename A_>
class PALUDIS_VISIBLE SupportsActionTest :
public SupportsActionTestBase,
@@ -153,50 +302,81 @@ namespace paludis
{
};
+ /**
+ * An Action can be written to a std::ostream.
+ *
+ * \since 0.26
+ * \ingroup g_actions
+ * \nosubgrouping
+ */
std::ostream & operator<< (std::ostream &, const Action &) PALUDIS_VISIBLE;
/**
- * Parent class for action errors.
+ * Parent class for Action related errors.
*
- * \ingroup grpexceptions
+ * \ingroup g_actions
+ * \ingroup g_exceptions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE ActionError :
public Exception
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
ActionError(const std::string & msg) throw ();
+
+ ///\}
};
+ /**
+ * Thrown if a PackageID is asked to perform an Action that it does
+ * not support.
+ *
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
+ * \nosubgrouping
+ */
class PALUDIS_VISIBLE UnsupportedActionError :
public ActionError
{
public:
+ ///\name Basic operations
+ ///\{
+
UnsupportedActionError(const PackageID &, const Action &) throw ();
+
+ ///\}
};
/**
- * Thrown if an install fails.
+ * Thrown if a PackageID fails to perform an InstallAction.
*
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE InstallActionError : public ActionError
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
InstallActionError(const std::string & msg) throw ();
+
+ ///\}
};
/**
- * Thrown if a fetch fails.
+ * Thrown if a PackageID fails to perform a FetchAction.
*
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE FetchActionError :
@@ -206,55 +386,73 @@ namespace paludis
const tr1::shared_ptr<const Sequence<FetchActionFailure> > _failures;
public:
+ ///\name Basic operations
+ ///\{
+
FetchActionError(const std::string &) throw ();
FetchActionError(const std::string &, const tr1::shared_ptr<const Sequence<FetchActionFailure> > &) throw ();
+ ///\}
+
+ /// More information about failed fetches.
const tr1::shared_ptr<const Sequence<FetchActionFailure> > failures() const PALUDIS_ATTRIBUTE((warn_unused_result));
};
/**
- * Thrown if an uninstall fails.
+ * Thrown if a PackageID fails to perform an UninstallAction.
*
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE UninstallActionError : public ActionError
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
UninstallActionError(const std::string & msg) throw ();
+
+ ///\}
};
/**
- * Thrown if a configure fails.
+ * Thrown if a PackageID fails to perform a ConfigAction.
*
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE ConfigActionError : public ActionError
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
ConfigActionError(const std::string & msg) throw ();
+
+ ///\}
};
/**
- * Thrown if an info fails.
+ * Thrown if a PackageID fails to perform an InfoAction.
*
- * \ingroup grpexceptions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
class PALUDIS_VISIBLE InfoActionError : public ActionError
{
public:
- /**
- * Constructor.
- */
+ ///\name Basic operations
+ ///\{
+
InfoActionError(const std::string & msg) throw ();
+
+ ///\}
};
}
diff --git a/paludis/action.se b/paludis/action.se
index 7293b20..35be7b1 100644
--- a/paludis/action.se
+++ b/paludis/action.se
@@ -12,6 +12,13 @@ make_enum_InstallActionDebugOption()
doxygen_comment << "END"
/**
* Debug build mode for an InstallAction.
+ *
+ * May be ignored by some repositories, and by packages where there
+ * isn't a sensible concept of debugging.
+ *
+ * \see InstallAction
+ * \ingroup g_actions
+ * \since 0.26
*/
END
}
@@ -23,5 +30,16 @@ make_enum_InstallActionChecksOption()
key iaco_none "No checks"
key iaco_default "Checks where they would usually be carried out"
key iaco_always "Always use checks"
+
+ doxygen_comment << "END"
+ /**
+ * Whether to run post-build checks (for example, 'make check' or 'src_test'),
+ * if they are available.
+ *
+ * \see InstallAction
+ * \ingroup g_actions
+ * \since 0.26
+ */
+END
}
diff --git a/paludis/action.sr b/paludis/action.sr
index 5e4a4e9..4352373 100644
--- a/paludis/action.sr
+++ b/paludis/action.sr
@@ -14,6 +14,8 @@ make_class_FetchActionOptions()
* Options for FetchAction.
*
* \see FetchAction
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
END
@@ -35,6 +37,8 @@ make_class_InstallActionOptions()
* Options for InstallAction.
*
* \see InstallAction
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
END
@@ -52,6 +56,8 @@ make_class_UninstallActionOptions()
* Options for UninstallAction.
*
* \see UninstallAction
+ * \ingroup g_actions
+ * \since 0.26
* \nosubgrouping
*/
END
@@ -72,7 +78,9 @@ make_class_FetchActionFailure()
* A failed fetch action part.
*
* \see FetchActionError
- * \ingroup grpexceptions
+ * \ingroup g_actions
+ * \ingroup g_exceptions
+ * \ingroup g_actions
* \nosubgrouping
*/
END
diff --git a/paludis/contents-fwd.hh b/paludis/contents-fwd.hh
index 13563e9..01575ce 100644
--- a/paludis/contents-fwd.hh
+++ b/paludis/contents-fwd.hh
@@ -23,6 +23,12 @@
#include <iosfwd>
#include <paludis/util/attributes.hh>
+/** \file
+ * Forward declarations for paludis/contents.hh .
+ *
+ * \ingroup g_contents
+ */
+
namespace paludis
{
struct ContentsEntry;
@@ -38,16 +44,16 @@ namespace paludis
struct ContentsVisitorTypes;
/**
- * Write a ContentsSymEntry to a stream
+ * Write a ContentsSymEntry to a stream.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
*/
std::ostream & operator<< (std::ostream &, const ContentsSymEntry &) PALUDIS_VISIBLE;
/**
- * Write a ContentsEntry to a stream
+ * Write a ContentsEntry to a stream.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
*/
std::ostream & operator<< (std::ostream &, const ContentsEntry &) PALUDIS_VISIBLE;
}
diff --git a/paludis/contents.hh b/paludis/contents.hh
index 2f0191f..87fa028 100644
--- a/paludis/contents.hh
+++ b/paludis/contents.hh
@@ -33,7 +33,7 @@
/** \file
* Declarations for the Contents classes.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
*/
namespace paludis
@@ -41,7 +41,8 @@ namespace paludis
/**
* Visit a contents heirarchy.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
+ * \nosubgrouping
*/
struct ContentsVisitorTypes :
VisitorTypes<
@@ -60,7 +61,7 @@ namespace paludis
/**
* Base class for a contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsEntry :
@@ -93,7 +94,7 @@ namespace paludis
/**
* A file contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsFileEntry :
@@ -112,7 +113,7 @@ namespace paludis
/**
* A directory contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsDirEntry :
@@ -131,7 +132,7 @@ namespace paludis
/**
* A misc contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsMiscEntry :
@@ -150,7 +151,7 @@ namespace paludis
/**
* A fifo contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsFifoEntry :
@@ -169,7 +170,7 @@ namespace paludis
/**
* A device contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsDevEntry :
@@ -188,7 +189,7 @@ namespace paludis
/**
* A sym contents entry.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE ContentsSymEntry :
@@ -211,9 +212,9 @@ namespace paludis
};
/**
- * A package's contents.
+ * A package's contents, obtainable by PackageID::contents_key.
*
- * \ingroup grpcontents
+ * \ingroup g_contents
* \nosubgrouping
*/
class PALUDIS_VISIBLE Contents :