environment.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_ENVIRONMENT_HH
00021 #define PALUDIS_GUARD_PALUDIS_ENVIRONMENT_HH 1
00022 
00023 #include <paludis/environment-fwd.hh>
00024 #include <paludis/util/instantiation_policy.hh>
00025 #include <paludis/util/options-fwd.hh>
00026 #include <paludis/util/fs_entry-fwd.hh>
00027 #include <paludis/util/tribool-fwd.hh>
00028 #include <paludis/util/simple_visitor.hh>
00029 #include <paludis/output_manager-fwd.hh>
00030 #include <paludis/util/private_implementation_pattern.hh>
00031 #include <paludis/name-fwd.hh>
00032 #include <paludis/hook-fwd.hh>
00033 #include <paludis/repository-fwd.hh>
00034 #include <paludis/dep_spec.hh>
00035 #include <paludis/spec_tree-fwd.hh>
00036 #include <paludis/package_id-fwd.hh>
00037 #include <paludis/mask-fwd.hh>
00038 #include <paludis/package_database-fwd.hh>
00039 #include <paludis/selection-fwd.hh>
00040 #include <paludis/metadata_key_holder.hh>
00041 #include <paludis/choice-fwd.hh>
00042 #include <paludis/create_output_manager_info-fwd.hh>
00043 #include <paludis/notifier_callback-fwd.hh>
00044 
00045 /** \file
00046  * Declarations for the Environment class.
00047  *
00048  * \ingroup g_environment
00049  *
00050  * \section Examples
00051  *
00052  * - \ref example_environment.cc "example_environment.cc"
00053  */
00054 
00055 namespace paludis
00056 {
00057     /**
00058      * Represents a working environment, which contains an available packages
00059      * database and provides various methods for querying package visibility
00060      * and options.
00061      *
00062      * Contains a PackageDatabase, which in turn contains a number of Repository
00063      * instances.
00064      *
00065      * Environment itself is purely an interface class. Actual Environment
00066      * implementations usually descend from EnvironmentImplementation, which
00067      * provides much of the common implementation details. EnvironmentFactory is
00068      * often used to create the appropriate Environment subclass for an
00069      * application.
00070      *
00071      * \ingroup g_environment
00072      * \see PackageDatabase
00073      * \see EnvironmentFactory
00074      * \see EnvironmentImplementation
00075      * \nosubgrouping
00076      */
00077     class PALUDIS_VISIBLE Environment :
00078         private InstantiationPolicy<Environment, instantiation_method::NonCopyableTag>,
00079         public MetadataKeyHolder
00080     {
00081         public:
00082             ///\name Basic operations
00083             ///\{
00084 
00085             virtual ~Environment() = 0;
00086 
00087             ///\}
00088 
00089             ///\name Choice-related queries
00090             ///\{
00091 
00092             /**
00093              * Do we want a choice enabled for a particular package?
00094              *
00095              * Only for use by Repository, to get defaults from the environment.
00096              * Clients should query the metadata key directly.
00097              *
00098              * The third parameter is the name of the value, which might not
00099              * have been created yet.
00100              */
00101             virtual const Tribool want_choice_enabled(
00102                     const std::tr1::shared_ptr<const PackageID> &,
00103                     const std::tr1::shared_ptr<const Choice> &,
00104                     const UnprefixedChoiceName &
00105                     ) const
00106                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00107 
00108             /**
00109              * What string value, if any, is set for the parameter for a particular
00110              * choice for a particular package?
00111              *
00112              * There is no difference between "not set" and "set to an empty
00113              * string".
00114              *
00115              * Only for use by Repository, to get defaults from the environment.
00116              * Clients should query the metadata key directly.
00117              *
00118              * The third parameter is the name of the value, which might not
00119              * have been created yet.
00120              *
00121              * \since 0.40
00122              */
00123             virtual const std::string value_for_choice_parameter(
00124                     const std::tr1::shared_ptr<const PackageID> &,
00125                     const std::tr1::shared_ptr<const Choice> &,
00126                     const UnprefixedChoiceName &
00127                     ) const
00128                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00129 
00130             /**
00131              * Return a collection of known value names for a particular
00132              * choice.
00133              *
00134              * Only for use by Repository, to get defaults from the environment.
00135              * Clients should query the metadata key directly.
00136              *
00137              * This is to deal with cases like USE_EXPAND values, where the
00138              * repository doesn't know all possible values.
00139              */
00140             virtual std::tr1::shared_ptr<const Set<UnprefixedChoiceName> > known_choice_value_names(
00141                     const std::tr1::shared_ptr<const PackageID> &,
00142                     const std::tr1::shared_ptr<const Choice> &
00143                     ) const
00144                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00145 
00146             ///\}
00147 
00148             ///\name Mask-related queries
00149             ///\{
00150 
00151             /**
00152              * Do we accept a particular license for a particular package?
00153              *
00154              * Used by PackageID implementations. Generally PackageID's masks methods
00155              * should be used rather than calling this directly.
00156              */
00157             virtual bool accept_license(const std::string &, const PackageID &) const
00158                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00159 
00160             /**
00161              * Do we accept any of the specified keywords for a particular package?
00162              *
00163              * If the collection includes "*", should return true.
00164              *
00165              * Used by PackageID implementations. Generally PackageID's masks methods
00166              * should be used rather than calling this directly.
00167              */
00168             virtual bool accept_keywords(const std::tr1::shared_ptr<const KeywordNameSet> &, const PackageID &) const
00169                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00170 
00171             /**
00172              * Do we have a 'breaks' mask for a particular package?
00173              *
00174              * Returns a zero pointer if no.
00175              *
00176              * Used by PackageID implementations. Generally PackageID's masks methods
00177              * should be used rather than calling this directly.
00178              */
00179             virtual const std::tr1::shared_ptr<const Mask> mask_for_breakage(const PackageID &) const
00180                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00181 
00182             /**
00183              * Do we have a 'user' mask for a particular package?
00184              *
00185              * Returns a zero pointer if no.
00186              *
00187              * If the second parameter is true, return a Mask suitable for
00188              * being added to an OverriddenMask.
00189              *
00190              * Used by PackageID implementations. Generally PackageID's masks methods
00191              * should be used rather than calling this directly.
00192              */
00193             virtual const std::tr1::shared_ptr<const Mask> mask_for_user(const PackageID &,
00194                     const bool will_be_used_for_overridden) const
00195                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00196 
00197             /**
00198              * Do we have a user unmask for a particular package?
00199              *
00200              * This is only applied to repository and profile style masks, not
00201              * keywords, licences etc. If true, user_mask shouldn't be used.
00202              *
00203              * Used by PackageID implementations. Generally PackageID's masks methods
00204              * should be used rather than calling this directly.
00205              */
00206             virtual bool unmasked_by_user(const PackageID &) const
00207                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00208 
00209             ///\}
00210 
00211             ///\name Database-related functions
00212             ///\{
00213 
00214             virtual std::tr1::shared_ptr<PackageDatabase> package_database()
00215                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00216 
00217             virtual std::tr1::shared_ptr<const PackageDatabase> package_database() const
00218                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00219 
00220             /**
00221              * Select some packages.
00222              */
00223             virtual std::tr1::shared_ptr<PackageIDSequence> operator[] (const Selection &) const
00224                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00225 
00226             ///\}
00227 
00228             ///\name System information
00229             ///\{
00230 
00231             /**
00232              * Return a collection of bashrc files to be used by the various components
00233              * that are implemented in bash.
00234              */
00235             virtual std::tr1::shared_ptr<const FSEntrySequence> bashrc_files() const
00236                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00237 
00238             /**
00239              * Return directories to search for syncer scripts.
00240              */
00241             virtual std::tr1::shared_ptr<const FSEntrySequence> syncers_dirs() const
00242                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00243 
00244             /**
00245              * Return directories to search for fetcher scripts.
00246              */
00247             virtual std::tr1::shared_ptr<const FSEntrySequence> fetchers_dirs() const
00248                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00249 
00250             /**
00251              * Return directories to search for hooks.
00252              */
00253             virtual std::tr1::shared_ptr<const FSEntrySequence> hook_dirs() const
00254                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00255 
00256             /**
00257              * Return the command used to launch paludis (the client).
00258              */
00259             virtual std::string paludis_command() const
00260                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00261 
00262             /**
00263              * Change the command used to launch paludis (the client).
00264              */
00265             virtual void set_paludis_command(const std::string &) = 0;
00266 
00267             /**
00268              * Our root location for installs.
00269              */
00270             virtual const FSEntry root() const = 0;
00271 
00272             /**
00273              * User id to use when reduced privs are permissible.
00274              */
00275             virtual uid_t reduced_uid() const = 0;
00276 
00277             /**
00278              * Group id to use when reduced privs are permissible.
00279              */
00280             virtual gid_t reduced_gid() const = 0;
00281 
00282             /**
00283              * Is the specified package Paludis?
00284              *
00285              * Used by InstallTask to decide whether to exec() after installing
00286              * a package.
00287              */
00288             virtual bool is_paludis_package(const QualifiedPackageName &) const
00289                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00290 
00291             ///\}
00292 
00293             ///\name Mirror information
00294             ///\{
00295 
00296             /**
00297              * Return the mirror URI prefixes for a named mirror.
00298              */
00299             virtual std::tr1::shared_ptr<const MirrorsSequence> mirrors(const std::string &) const
00300                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00301 
00302             ///\}
00303 
00304             ///\name Package sets
00305             ///\{
00306 
00307             /**
00308              * Add a package set.
00309              *
00310              * Generally called by repositories, when Repository::populate_sets is called.
00311              *
00312              * \param base_name The basic name of the set, such as 'security'.
00313              *
00314              * \param combined_name The name to use for this set when combine is true, such
00315              *     as 'security.myrepo'. If combine is false, should be the same as base_name.
00316              *
00317              * \param func A function that returns the set.
00318              *
00319              * \param combine If true, rename the set from foo to foo.reponame, and make
00320              *     the foo set contain foo.reponame, along with any other repositories'
00321              *     sets named foo. If false, throw if the set already exists.
00322              *
00323              * \since 0.40
00324              */
00325             virtual void add_set(
00326                     const SetName & base_name,
00327                     const SetName & combined_name,
00328                     const std::tr1::function<std::tr1::shared_ptr<const SetSpecTree> ()> & func,
00329                     const bool combine) const = 0;
00330 
00331             /**
00332              * Return all known named sets.
00333              */
00334             virtual std::tr1::shared_ptr<const SetNameSet> set_names() const
00335                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00336 
00337             /**
00338              * Return a named set.
00339              *
00340              * If the named set is not known, returns a zero pointer.
00341              */
00342             virtual const std::tr1::shared_ptr<const SetSpecTree> set(const SetName &) const
00343                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00344 
00345             ///\}
00346 
00347             ///\name Destination information
00348             ///\{
00349 
00350             /**
00351              * Default destination candidates for installing packages.
00352              */
00353             virtual std::tr1::shared_ptr<const DestinationsSet> default_destinations() const
00354                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00355 
00356             ///\}
00357 
00358             ///\name Hook methods
00359             ///\{
00360 
00361             /**
00362              * Perform a hook.
00363              */
00364             virtual HookResult perform_hook(const Hook &) const
00365                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00366 
00367             ///\}
00368 
00369             ///\name Distribution information
00370             ///\{
00371 
00372             virtual std::string distribution() const
00373                 PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
00374 
00375             ///\}
00376 
00377             ///\name World functionality
00378             ///\{
00379 
00380             /**
00381              * Add this package to world.
00382              */
00383             virtual void add_to_world(const QualifiedPackageName &) const = 0;
00384 
00385             /**
00386              * Add this set to world.
00387              */
00388             virtual void add_to_world(const SetName &) const = 0;
00389 
00390             /**
00391              * Remove this package from world, if it is present.
00392              */
00393             virtual void remove_from_world(const QualifiedPackageName &) const = 0;
00394 
00395             /**
00396              * Remove this set from world, if it is present.
00397              */
00398             virtual void remove_from_world(const SetName &) const = 0;
00399 
00400             ///\}
00401 
00402             ///\name Specific metadata keys
00403             ///\{
00404 
00405             /**
00406              * The format_key, if non-zero, holds our environment's format. Environment
00407              * implementations should not return zero here, but clients should still
00408              * check.
00409              */
00410             virtual const std::tr1::shared_ptr<const MetadataValueKey<std::string> > format_key() const = 0;
00411 
00412             /**
00413              * The config_location_key, if non-zero, specifies the location of the configuration file or directory,
00414              * the contents of which depends on the format returned by format_key.
00415              */
00416             virtual const std::tr1::shared_ptr<const MetadataValueKey<FSEntry> > config_location_key() const = 0;
00417 
00418             ///\}
00419 
00420             ///\name Output management
00421             ///\{
00422 
00423             /**
00424              * Create an output manager.
00425              *
00426              * \since 0.36
00427              */
00428             virtual const std::tr1::shared_ptr<OutputManager> create_output_manager(
00429                     const CreateOutputManagerInfo &) const = 0;
00430 
00431             /**
00432              * Set a callback function to use when a particular event occurs.
00433              *
00434              * The return value can be passed to remove_notifier_callback.
00435              *
00436              * \since 0.40
00437              */
00438             virtual NotifierCallbackID add_notifier_callback(const NotifierCallbackFunction &) = 0;
00439 
00440             /**
00441              * Remove a function added with add_notifier_callback.
00442              *
00443              * \since 0.40
00444              */
00445             virtual void remove_notifier_callback(const NotifierCallbackID) = 0;
00446 
00447             /**
00448              * Trigger a notifier callback.
00449              *
00450              * \since 0.40
00451              */
00452             virtual void trigger_notifier_callback(const NotifierCallbackEvent &) const = 0;
00453 
00454             ///\}
00455     };
00456 
00457 #ifdef PALUDIS_HAVE_EXTERN_TEMPLATE
00458     extern template class PrivateImplementationPattern<CreateOutputManagerForRepositorySyncInfo>;
00459     extern template class PrivateImplementationPattern<CreateOutputManagerForPackageIDActionInfo>;
00460 #endif
00461 
00462 }
00463 
00464 #endif

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