repository.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2005, 2006, 2007, 2008, 2009 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_PALUDIS_REPOSITORY_HH
00021 #define PALUDIS_GUARD_PALUDIS_REPOSITORY_HH 1
00022 
00023 #include <paludis/action-fwd.hh>
00024 #include <paludis/repository-fwd.hh>
00025 #include <paludis/dep_spec-fwd.hh>
00026 #include <paludis/spec_tree-fwd.hh>
00027 #include <paludis/name.hh>
00028 #include <paludis/package_id-fwd.hh>
00029 #include <paludis/qa-fwd.hh>
00030 #include <paludis/util/attributes.hh>
00031 #include <paludis/util/exception.hh>
00032 #include <paludis/util/fs_entry.hh>
00033 #include <paludis/util/wrapped_forward_iterator-fwd.hh>
00034 #include <paludis/util/options.hh>
00035 #include <paludis/util/named_value.hh>
00036 #include <paludis/output_manager-fwd.hh>
00037 #include <paludis/version_spec.hh>
00038 #include <paludis/metadata_key-fwd.hh>
00039 #include <paludis/metadata_key_holder.hh>
00040 #include <paludis/merger-fwd.hh>
00041 #include <string>
00042 #include <tr1/functional>
00043 
00044 /** \file
00045  * Declarations for Repository classes.
00046  *
00047  * \ingroup g_repository
00048  *
00049  * \section Examples
00050  *
00051  * - \ref example_repository.cc "example_repository.cc"
00052  */
00053 
00054 namespace paludis
00055 {
00056     namespace n
00057     {
00058         struct arch;
00059         struct destination_interface;
00060         struct e_interface;
00061         struct environment_file;
00062         struct environment_variable_interface;
00063         struct hook_interface;
00064         struct image_dir;
00065         struct installed_this;
00066         struct make_virtuals_interface;
00067         struct manifest_interface;
00068         struct mirrors_interface;
00069         struct options;
00070         struct output_manager;
00071         struct package_id;
00072         struct path;
00073         struct perform_uninstall;
00074         struct profile;
00075         struct provided_by;
00076         struct provided_by_spec;
00077         struct provides_interface;
00078         struct qa_interface;
00079         struct status;
00080         struct syncable_interface;
00081         struct used_this_for_config_protect;
00082         struct virtual_name;
00083         struct virtuals_interface;
00084     }
00085 
00086     /**
00087      * Optional interfaces that may be provided by a Repository.
00088      *
00089      * \see Repository
00090      * \ingroup g_repository
00091      * \since 0.30
00092      */
00093     struct RepositoryCapabilities
00094     {
00095         NamedValue<n::destination_interface, RepositoryDestinationInterface *> destination_interface;
00096         NamedValue<n::e_interface, RepositoryEInterface *> e_interface;
00097         NamedValue<n::environment_variable_interface, RepositoryEnvironmentVariableInterface *> environment_variable_interface;
00098         NamedValue<n::hook_interface, RepositoryHookInterface *> hook_interface;
00099         NamedValue<n::make_virtuals_interface, RepositoryMakeVirtualsInterface *> make_virtuals_interface;
00100         NamedValue<n::manifest_interface, RepositoryManifestInterface *> manifest_interface;
00101         NamedValue<n::mirrors_interface, RepositoryMirrorsInterface *> mirrors_interface;
00102         NamedValue<n::provides_interface, RepositoryProvidesInterface *> provides_interface;
00103         NamedValue<n::qa_interface, RepositoryQAInterface *> qa_interface;
00104         NamedValue<n::syncable_interface, RepositorySyncableInterface *> syncable_interface;
00105         NamedValue<n::virtuals_interface, RepositoryVirtualsInterface *> virtuals_interface;
00106     };
00107 
00108     /**
00109      * A profiles.desc line in a Repository implementing RepositoryEInterface.
00110      *
00111      * \see Repository
00112      * \see RepositoryEInterface
00113      * \ingroup g_repository
00114      * \since 0.30
00115      */
00116     struct RepositoryEInterfaceProfilesDescLine
00117     {
00118         NamedValue<n::arch, std::string> arch;
00119         NamedValue<n::path, FSEntry> path;
00120         NamedValue<n::profile, std::tr1::shared_ptr<const RepositoryEInterfaceProfilesDescLineProfile> > profile;
00121         NamedValue<n::status, std::string> status;
00122     };
00123 
00124     /**
00125      * A provides entry in a Repository implementing RepositoryProvidesInterface.
00126      *
00127      * \see Repository
00128      * \see RepositoryProvidesInterface
00129      * \ingroup g_repository
00130      * \since 0.30
00131      */
00132     struct RepositoryProvidesEntry
00133     {
00134         NamedValue<n::provided_by, std::tr1::shared_ptr<const PackageID> > provided_by;
00135         NamedValue<n::virtual_name, QualifiedPackageName> virtual_name;
00136     };
00137 
00138     /**
00139      * A virtuals entry in a Repository implementing RepositoryVirtualsInterface.
00140      *
00141      * \see Repository
00142      * \see RepositoryVirtualsInterface
00143      * \ingroup g_repository
00144      * \since 0.30
00145      */
00146     struct RepositoryVirtualsEntry
00147     {
00148         NamedValue<n::provided_by_spec, std::tr1::shared_ptr<const PackageDepSpec> > provided_by_spec;
00149         NamedValue<n::virtual_name, QualifiedPackageName> virtual_name;
00150     };
00151 
00152     /**
00153      * Parameters for RepositoryDestinationInterface::merge.
00154      *
00155      * \see RepositoryDestinationInterface
00156      * \ingroup g_repository
00157      * \since 0.30
00158      */
00159     struct MergeParams
00160     {
00161         NamedValue<n::environment_file, FSEntry> environment_file;
00162         NamedValue<n::image_dir, FSEntry> image_dir;
00163 
00164         /**
00165          * Some callers need to know what we merged.
00166          *
00167          * \since 0.38
00168          */
00169         NamedValue<n::installed_this, std::tr1::function<void (const FSEntry &)> > installed_this;
00170 
00171         NamedValue<n::options, MergerOptions> options;
00172         NamedValue<n::output_manager, std::tr1::shared_ptr<OutputManager> > output_manager;
00173         NamedValue<n::package_id, std::tr1::shared_ptr<const PackageID> > package_id;
00174 
00175         /**
00176          * Some merges need to do an uninstall mid-way through the merge process.
00177          *
00178          * \see InstallActionOptions::perform_uninstall
00179          * \since 0.36
00180          */
00181         NamedValue<n::perform_uninstall, std::tr1::function<void (
00182                 const std::tr1::shared_ptr<const PackageID> &,
00183                 const UninstallActionOptions &)> > perform_uninstall;
00184 
00185         NamedValue<n::used_this_for_config_protect, std::tr1::function<void (const std::string &)> > used_this_for_config_protect;
00186     };
00187 
00188     /**
00189      * Thrown if a Set does not exist
00190      *
00191      * \ingroup g_exceptions
00192      * \ingroup g_repository
00193      * \nosubgrouping
00194      */
00195     class PALUDIS_VISIBLE NoSuchSetError :
00196         public Exception
00197     {
00198         private:
00199             std::string _name;
00200 
00201         public:
00202             ///\name Basic operations
00203             ///\{
00204 
00205             NoSuchSetError(const std::string & name) throw ();
00206 
00207             virtual ~NoSuchSetError() throw ();
00208 
00209             ///\}
00210 
00211             /**
00212              * Name of the set.
00213              */
00214             const std::string name() const;
00215     };
00216 
00217     /**
00218      * Thrown if a Set is recursively defined
00219      *
00220      * \ingroup g_exceptions
00221      * \ingroup g_repository
00222      * \nosubgrouping
00223      */
00224     class PALUDIS_VISIBLE RecursivelyDefinedSetError :
00225         public Exception
00226     {
00227         private:
00228             std::string _name;
00229 
00230         public:
00231             ///\name Basic operations
00232             ///\{
00233 
00234             RecursivelyDefinedSetError(const std::string & name) throw ();
00235 
00236             virtual ~RecursivelyDefinedSetError() throw ();
00237 
00238             ///\}
00239 
00240             /**
00241              * Name of the set.
00242              */
00243             const std::string name() const;
00244     };
00245 
00246     /**
00247      * A Repository provides a representation of a physical repository to a
00248      * PackageDatabase.
00249      *
00250      * \ingroup g_repository
00251      * \nosubgrouping
00252      */
00253     class PALUDIS_VISIBLE Repository :
00254         private InstantiationPolicy<Repository, instantiation_method::NonCopyableTag>,
00255         private PrivateImplementationPattern<Repository>,
00256         public RepositoryCapabilities,
00257         public MetadataKeyHolder
00258     {
00259         private:
00260             PrivateImplementationPattern<Repository>::ImpPtr & _imp;
00261 
00262         protected:
00263             ///\name Basic operations
00264             ///\{
00265 
00266             Repository(const Environment * const, const RepositoryName &, const RepositoryCapabilities &);
00267 
00268             ///\}
00269 
00270         public:
00271             ///\name Basic operations
00272             ///\{
00273 
00274             virtual ~Repository();
00275 
00276             ///\}
00277 
00278             ///\name Repository information
00279             ///\{
00280 
00281             /**
00282              * Return our name.
00283              */
00284             const RepositoryName name() const PALUDIS_ATTRIBUTE((nothrow))
00285                 PALUDIS_ATTRIBUTE((warn_unused_result));
00286 
00287             /**
00288              * Are we allowed to be favourite repository?
00289              */
00290             virtual bool can_be_favourite_repository() const;
00291 
00292             ///\}
00293 
00294             ///\name Specific metadata keys
00295             ///\{
00296 
00297             /**
00298              * The format_key, if non-zero, holds our repository's format. Repository
00299              * implementations should not return zero here, but clients should still
00300              * check.
00301              */
00302             virtual const std::tr1::shared_ptr<const MetadataValueKey<std::string> > format_key() const = 0;
00303 
00304             /**
00305              * The location_key, if non-zero, holds the file or directory containing
00306              * our repository's data, the format of which depends on the value of
00307              * format_key.
00308              */
00309             virtual const std::tr1::shared_ptr<const MetadataValueKey<FSEntry> > location_key() const = 0;
00310 
00311             /**
00312              * The installed_root_key, if non-zero, specifies that we contain installed
00313              * packages at the specified root.
00314              *
00315              * This key is currently used in various places to determine whether a repository is
00316              * an 'installed' repository or not.
00317              */
00318             virtual const std::tr1::shared_ptr<const MetadataValueKey<FSEntry> > installed_root_key() const = 0;
00319 
00320             ///\}
00321 
00322             ///\name Repository content queries
00323             ///\{
00324 
00325             /**
00326              * Do we have a category with the given name?
00327              */
00328             virtual bool has_category_named(const CategoryNamePart & c) const = 0;
00329 
00330             /**
00331              * Do we have a package in the given category with the given name?
00332              */
00333             virtual bool has_package_named(const QualifiedPackageName & q) const = 0;
00334 
00335             /**
00336              * Fetch our category names.
00337              */
00338             virtual std::tr1::shared_ptr<const CategoryNamePartSet> category_names() const = 0;
00339 
00340             /**
00341              * Fetch unimportant categories.
00342              */
00343             virtual std::tr1::shared_ptr<const CategoryNamePartSet> unimportant_category_names() const;
00344 
00345             /**
00346              * Fetch categories that contain a named package.
00347              */
00348             virtual std::tr1::shared_ptr<const CategoryNamePartSet> category_names_containing_package(
00349                     const PackageNamePart & p) const;
00350 
00351             /**
00352              * Fetch our package names.
00353              */
00354             virtual std::tr1::shared_ptr<const QualifiedPackageNameSet> package_names(
00355                     const CategoryNamePart & c) const = 0;
00356 
00357             /**
00358              * Fetch our IDs.
00359              */
00360             virtual std::tr1::shared_ptr<const PackageIDSequence> package_ids(const QualifiedPackageName & p) const = 0;
00361 
00362             /**
00363              * Might some of our IDs support a particular action?
00364              *
00365              * Used to optimise PackageDatabase::query. If a repository doesn't
00366              * support, say, InstallAction, a query can skip searching it
00367              * entirely when looking for installable packages.
00368              */
00369             virtual bool some_ids_might_support_action(const SupportsActionTestBase &) const = 0;
00370 
00371             ///\}
00372 
00373             ///\name Repository behaviour methods
00374             ///\{
00375 
00376             /**
00377              * Invalidate any in memory cache.
00378              */
00379             virtual void invalidate() = 0;
00380 
00381             /**
00382              * Invalidate cached masks.
00383              */
00384             virtual void invalidate_masks() = 0;
00385 
00386             /**
00387              * Regenerate any on disk cache.
00388              */
00389             virtual void regenerate_cache() const;
00390 
00391             /**
00392              * Purge any invalid on-disk cache entries.
00393              */
00394             virtual void purge_invalid_cache() const;
00395 
00396             ///\}
00397 
00398             ///\name Set methods
00399             ///\{
00400 
00401             /**
00402              * Call Environment::add_set for every set we define.
00403              *
00404              * Environment will call this method at most once, so no cache or check for
00405              * repeats is required. Nothing else should call this method.
00406              *
00407              * \since 0.40
00408              */
00409             virtual void populate_sets() const = 0;
00410 
00411             ///\}
00412     };
00413 
00414     /**
00415      * Interface for syncing for repositories.
00416      *
00417      * \see Repository
00418      * \ingroup g_repository
00419      * \nosubgrouping
00420      */
00421     class PALUDIS_VISIBLE RepositorySyncableInterface
00422     {
00423         public:
00424             ///\name Sync functions
00425             ///\{
00426 
00427             /**
00428              * Sync, if necessary.
00429              *
00430              * \return True if we synced successfully, false if we skipped sync.
00431              */
00432             virtual bool sync(const std::tr1::shared_ptr<OutputManager> &) const = 0;
00433 
00434             ///\}
00435 
00436             virtual ~RepositorySyncableInterface();
00437     };
00438 
00439     /**
00440      * Interface for environment variable querying for repositories.
00441      *
00442      * \see Repository
00443      * \ingroup g_repository
00444      * \nosubgrouping
00445      */
00446     class PALUDIS_VISIBLE RepositoryEnvironmentVariableInterface
00447     {
00448         public:
00449             ///\name Environment query functionality
00450             ///\{
00451 
00452             /**
00453              * Query an environment variable
00454              */
00455             virtual std::string get_environment_variable(
00456                     const std::tr1::shared_ptr<const PackageID> & for_package,
00457                     const std::string & var) const
00458                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00459 
00460             ///\}
00461 
00462             virtual ~RepositoryEnvironmentVariableInterface();
00463     };
00464 
00465     /**
00466      * Interface for mirror querying for repositories.
00467      *
00468      * \see Repository
00469      * \ingroup g_repository
00470      * \nosubgrouping
00471      */
00472     class PALUDIS_VISIBLE RepositoryMirrorsInterface
00473     {
00474         public:
00475             ///\name Iterate over our mirrors
00476             ///\{
00477 
00478             struct MirrorsConstIteratorTag;
00479             typedef WrappedForwardIterator<MirrorsConstIteratorTag,
00480                     const std::pair<const std::string, std::string> > MirrorsConstIterator;
00481 
00482             virtual MirrorsConstIterator begin_mirrors(const std::string & s) const
00483                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00484             virtual MirrorsConstIterator end_mirrors(const std::string & s) const
00485                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00486 
00487             /**
00488              * Is the named item a mirror?
00489              */
00490             bool is_mirror(const std::string & s) const;
00491 
00492             ///\}
00493 
00494             virtual ~RepositoryMirrorsInterface();
00495     };
00496 
00497     /**
00498      * Interface for repositories that define virtuals.
00499      *
00500      * \see Repository
00501      * \ingroup g_repository
00502      * \nosubgrouping
00503      */
00504     class PALUDIS_VISIBLE RepositoryVirtualsInterface
00505     {
00506         public:
00507             ///\name Virtuals functionality
00508             ///\{
00509 
00510             /**
00511              * A collection of virtuals.
00512              */
00513             typedef Sequence<RepositoryVirtualsEntry> VirtualsSequence;
00514 
00515             /**
00516              * Fetch our virtual packages.
00517              */
00518             virtual std::tr1::shared_ptr<const VirtualsSequence> virtual_packages() const
00519                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00520 
00521             ///\}
00522 
00523             virtual ~RepositoryVirtualsInterface();
00524     };
00525 
00526     /**
00527      * Interface for repositories that can make virtuals on the fly.
00528      *
00529      * \see Repository
00530      * \ingroup g_repository
00531      * \nosubgrouping
00532      */
00533     class PALUDIS_VISIBLE RepositoryMakeVirtualsInterface
00534     {
00535         public:
00536             virtual ~RepositoryMakeVirtualsInterface();
00537 
00538             virtual const std::tr1::shared_ptr<const PackageID> make_virtual_package_id(
00539                     const QualifiedPackageName & virtual_name, const std::tr1::shared_ptr<const PackageID> & provider) const
00540                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00541     };
00542 
00543     /**
00544      * Interface for repositories that provide packages.
00545      *
00546      * \see Repository
00547      * \ingroup g_repository
00548      * \nosubgrouping
00549      */
00550     class PALUDIS_VISIBLE RepositoryProvidesInterface
00551     {
00552         public:
00553             ///\name Provides functionality
00554             ///\{
00555 
00556             /**
00557              * A collection of provided packages.
00558              */
00559             typedef Sequence<RepositoryProvidesEntry> ProvidesSequence;
00560 
00561             /**
00562              * Fetch our provided packages.
00563              */
00564             virtual std::tr1::shared_ptr<const ProvidesSequence> provided_packages() const
00565                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00566 
00567             ///\}
00568 
00569             virtual ~RepositoryProvidesInterface();
00570     };
00571 
00572     /**
00573      * Interface for repositories that can be used as an install destination.
00574      *
00575      * \see Repository
00576      * \ingroup g_repository
00577      * \nosubgrouping
00578      */
00579     class PALUDIS_VISIBLE RepositoryDestinationInterface
00580     {
00581         public:
00582             ///\name Destination functions
00583             ///\{
00584 
00585             /**
00586              * Are we a suitable destination for the specified package?
00587              */
00588             virtual bool is_suitable_destination_for(const PackageID &) const
00589                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00590 
00591             /**
00592              * Are we to be included in the Environment::default_destinations list?
00593              */
00594             virtual bool is_default_destination() const
00595                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00596 
00597             /**
00598              * If true, pre and post install phases will be used when writing to this
00599              * destination.
00600              *
00601              * This should return true for 'real' filesystem destinations (whether or
00602              * not root is /, if root merges are supported), and false for intermediate
00603              * destinations such as binary repositories.
00604              */
00605             virtual bool want_pre_post_phases() const
00606                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00607 
00608             /**
00609              * Merge a package.
00610              */
00611             virtual void merge(const MergeParams &) = 0;
00612 
00613             ///\}
00614 
00615             virtual ~RepositoryDestinationInterface();
00616     };
00617 
00618     /**
00619      * Interface for handling ERepository specific functionality.
00620      *
00621      * \see Repository
00622      * \ingroup g_repository
00623      * \nosubgrouping
00624      */
00625     class PALUDIS_VISIBLE RepositoryEInterface
00626     {
00627         public:
00628             ///\name Information about a ERepository
00629             ///\{
00630 
00631             virtual std::string profile_variable(const std::string &) const = 0;
00632             virtual std::string accept_keywords_variable() const = 0;
00633             virtual std::string arch_variable() const = 0;
00634 
00635             ///\}
00636 
00637             ///\name Profile setting and querying functions
00638             ///\{
00639 
00640             typedef RepositoryEInterfaceProfilesDescLine ProfilesDescLine;
00641 
00642             struct ProfilesConstIteratorTag;
00643             typedef WrappedForwardIterator<ProfilesConstIteratorTag, const ProfilesDescLine> ProfilesConstIterator;
00644             virtual ProfilesConstIterator begin_profiles() const = 0;
00645             virtual ProfilesConstIterator end_profiles() const = 0;
00646 
00647             virtual ProfilesConstIterator find_profile(const FSEntry & location) const = 0;
00648             virtual void set_profile(const ProfilesConstIterator & iter) = 0;
00649             virtual void set_profile_by_arch(const std::string &) = 0;
00650 
00651             ///\}
00652 
00653             virtual ~RepositoryEInterface();
00654     };
00655 
00656     /**
00657      * Interface for handling QA tasks.
00658      *
00659      * \see Repository
00660      * \ingroup g_repository
00661      * \nosubgrouping
00662      */
00663     class PALUDIS_VISIBLE RepositoryQAInterface
00664     {
00665         public:
00666             /**
00667              * Perform QA checks on the repository.
00668              */
00669             virtual void check_qa(
00670                     QAReporter &,
00671                     const QACheckProperties &,
00672                     const QACheckProperties &,
00673                     const QAMessageLevel,
00674                     const FSEntry &
00675                     ) const = 0;
00676 
00677             ///\name Basic operations
00678             ///\{
00679 
00680             virtual ~RepositoryQAInterface();
00681 
00682             ///\}
00683     };
00684 
00685     /**
00686      * Interface for making and verifying Manifest2-style manifests
00687      *
00688      * \see Repository
00689      * \ingroup g_repository
00690      * \nosubgrouping
00691      */
00692     class PALUDIS_VISIBLE RepositoryManifestInterface
00693     {
00694         public:
00695             /**
00696              * Makes the Manifest for a given package. Requires that all
00697              * the needed DIST files, etc, have already been fetched.
00698              */
00699             virtual void make_manifest(const QualifiedPackageName &) = 0;
00700 
00701             ///\name Basic operations
00702             ///\{
00703 
00704             virtual ~RepositoryManifestInterface();
00705 
00706             ///\}
00707     };
00708 
00709     /**
00710      * Interface for handling hooks.
00711      *
00712      * \see Repository
00713      * \ingroup g_repository
00714      * \nosubgrouping
00715      */
00716     class PALUDIS_VISIBLE RepositoryHookInterface
00717     {
00718         public:
00719             /**
00720              * Perform a hook.
00721              */
00722             virtual HookResult perform_hook(const Hook & hook) const
00723                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00724 
00725             ///\name Basic operations
00726             ///\{
00727 
00728             virtual ~RepositoryHookInterface();
00729 
00730             ///\}
00731     };
00732 }
00733 
00734 #endif

Generated on Mon Sep 21 10:36:08 2009 for paludis by  doxygen 1.5.4