paludis  Version 2.6.0
repository.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2013 Ciaran McCreesh
5  *
6  * This file is part of the Paludis package manager. Paludis is free software;
7  * you can redistribute it and/or modify it under the terms of the GNU General
8  * Public License version 2, as published by the Free Software Foundation.
9  *
10  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
11  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
13  * details.
14  *
15  * You should have received a copy of the GNU General Public License along with
16  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
17  * Place, Suite 330, Boston, MA 02111-1307 USA
18  */
19 
20 #ifndef PALUDIS_GUARD_PALUDIS_REPOSITORY_HH
21 #define PALUDIS_GUARD_PALUDIS_REPOSITORY_HH 1
22 
23 #include <paludis/action-fwd.hh>
25 #include <paludis/dep_spec-fwd.hh>
26 #include <paludis/spec_tree-fwd.hh>
27 #include <paludis/name.hh>
29 #include <paludis/partitioning-fwd.hh>
32 #include <paludis/util/fs_path.hh>
33 #include <paludis/util/wrapped_forward_iterator-fwd.hh>
34 #include <paludis/util/options.hh>
35 #include <paludis/util/named_value.hh>
36 #include <paludis/util/timestamp.hh>
38 #include <paludis/util/map-fwd.hh>
39 #include <paludis/output_manager-fwd.hh>
40 #include <paludis/version_spec.hh>
42 #include <paludis/metadata_key_holder.hh>
43 #include <paludis/merger-fwd.hh>
44 #include <paludis/hook-fwd.hh>
45 #include <string>
46 #include <functional>
47 
48 /** \file
49  * Declarations for Repository classes.
50  *
51  * \ingroup g_repository
52  *
53  * \section Examples
54  *
55  * - \ref example_repository.cc "example_repository.cc"
56  */
57 
58 namespace paludis
59 {
60  namespace n
61  {
62  typedef Name<struct name_arch> arch;
63  typedef Name<struct name_build_start_time> build_start_time;
64  typedef Name<struct name_check> check;
65  typedef Name<struct name_destination_interface> destination_interface;
66  typedef Name<struct name_environment_file> environment_file;
67  typedef Name<struct name_environment_variable_interface> environment_variable_interface;
68  typedef Name<struct name_image_dir> image_dir;
69  typedef Name<struct name_is_volatile> is_volatile;
70  typedef Name<struct name_manifest_interface> manifest_interface;
71  typedef Name<struct name_merged_entries> merged_entries;
72  typedef Name<struct name_options> options;
73  typedef Name<struct name_output_manager> output_manager;
74  typedef Name<struct name_package_id> package_id;
75  typedef Name<struct name_parts> parts;
76  typedef Name<struct name_path> path;
77  typedef Name<struct name_perform_uninstall> perform_uninstall;
78  typedef Name<struct name_permit_destination> permit_destination;
79  typedef Name<struct name_profile> profile;
80  typedef Name<struct name_replacing> replacing;
81  typedef Name<struct name_status> status;
82  typedef Name<struct name_used_this_for_config_protect> used_this_for_config_protect;
83  typedef Name<struct name_want_phase> want_phase;
84  }
85 
86  /**
87  * Optional interfaces that may be provided by a Repository.
88  *
89  * \see Repository
90  * \ingroup g_repository
91  * \since 0.30
92  */
94  {
98  };
99 
100  /**
101  * Parameters for RepositoryDestinationInterface::merge.
102  *
103  * \see RepositoryDestinationInterface
104  * \ingroup g_repository
105  * \since 0.30
106  */
107  struct MergeParams
108  {
109  /**
110  * The start of the build time (for binaries, should really be when the
111  * binary was originally built).
112  *
113  * \since 0.44
114  */
116 
117  /**
118  * Whether to check or perform the merge.
119  *
120  * A check must be performed before a merge.
121  *
122  * \since 0.59
123  */
125 
128 
129  /**
130  * Whether or not a file is volatile.
131  * \since 2.0.0
132  */
134 
135  /**
136  * We record things we merged here.
137  * \since 0.41
138  */
140 
144 
145  /**
146  * Package partioning.
147  * \since 1.1.0
148  */
150 
151  /**
152  * Some merges need to do an uninstall mid-way through the merge process.
153  *
154  * \see InstallActionOptions::perform_uninstall
155  * \since 0.36
156  */
157  NamedValue<n::perform_uninstall, std::function<void (
158  const std::shared_ptr<const PackageID> &,
160 
161  ///\since 0.66
163 
164  /**
165  * Someone needs to replace these (either the merge or the install).
166  *
167  * \since 0.57
168  */
170 
172 
173  /**
174  * Sometimes merging runs phase functions, possibly via perform_uninstall.
175  *
176  * \since 0.77
177  */
179  };
180 
181  /**
182  * Thrown if a Set does not exist
183  *
184  * \ingroup g_exceptions
185  * \ingroup g_repository
186  * \nosubgrouping
187  */
189  public Exception
190  {
191  private:
192  std::string _name;
193 
194  public:
195  ///\name Basic operations
196  ///\{
197 
198  NoSuchSetError(const std::string & name) noexcept;
199 
200  virtual ~NoSuchSetError();
201 
202  ///\}
203 
204  /**
205  * Name of the set.
206  */
207  const std::string name() const;
208  };
209 
210  /**
211  * Thrown if a Set is recursively defined
212  *
213  * \ingroup g_exceptions
214  * \ingroup g_repository
215  * \nosubgrouping
216  */
218  public Exception
219  {
220  private:
221  std::string _name;
222 
223  public:
224  ///\name Basic operations
225  ///\{
226 
227  RecursivelyDefinedSetError(const std::string & name) noexcept;
228 
229  virtual ~RecursivelyDefinedSetError();
230 
231  ///\}
232 
233  /**
234  * Name of the set.
235  */
236  const std::string name() const;
237  };
238 
239  /**
240  * A Repository provides a representation of a physical repository to an
241  * Environment.
242  *
243  * \ingroup g_repository
244  * \nosubgrouping
245  */
247  public RepositoryCapabilities,
248  public MetadataKeyHolder
249  {
250  private:
251  Pimp<Repository> _imp;
252 
253  protected:
254  ///\name Basic operations
255  ///\{
256 
257  Repository(const Environment * const, const RepositoryName &, const RepositoryCapabilities &);
258 
259  ///\}
260 
261  public:
262  ///\name Basic operations
263  ///\{
264 
265  virtual ~Repository();
266 
267  Repository(const Repository &) = delete;
268  Repository & operator= (const Repository &) = delete;
269 
270  ///\}
271 
272  ///\name Repository information
273  ///\{
274 
275  /**
276  * Return our name.
277  */
278  const RepositoryName name() const noexcept PALUDIS_ATTRIBUTE((warn_unused_result));
279 
280  ///\}
281 
282  ///\name Specific metadata keys
283  ///\{
284 
285  /**
286  * The format_key, if non-zero, holds our repository's format. Repository
287  * implementations should not return zero here, but clients should still
288  * check.
289  */
290  virtual const std::shared_ptr<const MetadataValueKey<std::string> > format_key() const = 0;
291 
292  /**
293  * The location_key, if non-zero, holds the file or directory containing
294  * our repository's data, the format of which depends on the value of
295  * format_key.
296  */
297  virtual const std::shared_ptr<const MetadataValueKey<FSPath> > location_key() const = 0;
298 
299  /**
300  * The installed_root_key, if non-zero, specifies that we contain installed
301  * packages at the specified root.
302  *
303  * This key is currently used in various places to determine whether a repository is
304  * an 'installed' repository or not.
305  */
306  virtual const std::shared_ptr<const MetadataValueKey<FSPath> > installed_root_key() const = 0;
307 
308  /**
309  * The sync_host_key, if present, should have value containing
310  * the host against which a sync will be performed for each suffix.
311  *
312  * This is used to avoid starting multiple parallel syncs against
313  * the same host.
314  *
315  * \since 0.44
316  * \since 0.55 is a Map<std::string, std::string>.
317  */
318  virtual const std::shared_ptr<const MetadataCollectionKey<Map<std::string, std::string> > > sync_host_key() const = 0;
319 
320  ///\}
321 
322  ///\name Repository content queries
323  ///\{
324 
325  /**
326  * Do we have a category with the given name?
327  *
328  * \since 0.59 takes repository_content_may_excludes
329  */
330  virtual bool has_category_named(const CategoryNamePart & c,
331  const RepositoryContentMayExcludes & repository_content_may_excludes) const = 0;
332 
333  /**
334  * Do we have a package in the given category with the given name?
335  */
336  virtual bool has_package_named(const QualifiedPackageName & q,
337  const RepositoryContentMayExcludes & repository_content_may_excludes) const = 0;
338 
339  /**
340  * Fetch our category names.
341  */
342  virtual std::shared_ptr<const CategoryNamePartSet> category_names(
343  const RepositoryContentMayExcludes & repository_content_may_excludes) const = 0;
344 
345  /**
346  * Fetch unimportant categories.
347  */
348  virtual std::shared_ptr<const CategoryNamePartSet> unimportant_category_names(
349  const RepositoryContentMayExcludes & repository_content_may_excludes) const;
350 
351  /**
352  * Are we unimportant?
353  *
354  * In disambiguation, anything gets preferred over packages from unimportant repositories.
355  *
356  * \since 0.46
357  */
358  virtual const bool is_unimportant() const = 0;
359 
360  /**
361  * Fetch categories that contain a named package.
362  */
363  virtual std::shared_ptr<const CategoryNamePartSet> category_names_containing_package(
364  const PackageNamePart & p,
365  const RepositoryContentMayExcludes & repository_content_may_excludes) const;
366 
367  /**
368  * Fetch our package names.
369  */
370  virtual std::shared_ptr<const QualifiedPackageNameSet> package_names(
371  const CategoryNamePart & c,
372  const RepositoryContentMayExcludes & repository_content_may_excludes) const = 0;
373 
374  /**
375  * Fetch our IDs.
376  */
377  virtual std::shared_ptr<const PackageIDSequence> package_ids(const QualifiedPackageName & p,
378  const RepositoryContentMayExcludes & repository_content_may_excludes) const = 0;
379 
380  /**
381  * Might some of our IDs support a particular action?
382  *
383  * Used to optimise various Generator and Filter queries. If a
384  * repository doesn't support, say, InstallAction, a query can skip
385  * searching it entirely when looking for installable packages.
386  */
387  virtual bool some_ids_might_support_action(const SupportsActionTestBase &) const = 0;
388 
389  /**
390  * Might some of our IDs be not masked?
391  *
392  * Used to optimise various Generator and Filter queries.
393  *
394  * \since 0.49
395  */
396  virtual bool some_ids_might_not_be_masked() const = 0;
397 
398  /**
399  * Possibly expand a licence.
400  *
401  * May return a null pointer, if we don't define any licence
402  * groups, or if the thing being passed in doesn't look like a
403  * licence group.
404  *
405  * This should not be recursive.
406  *
407  * Callers should Environment::expand_licence, not this method.
408  *
409  * \since 0.66
410  */
411  virtual const std::shared_ptr<const Set<std::string> > maybe_expand_licence_nonrecursively(
412  const std::string &) const = 0;
413 
414  ///\}
415 
416  ///\name Repository behaviour methods
417  ///\{
418 
419  /**
420  * Invalidate any in memory cache.
421  */
422  virtual void invalidate() = 0;
423 
424  /**
425  * Regenerate any on disk cache.
426  */
427  virtual void regenerate_cache() const;
428 
429  /**
430  * Purge any invalid on-disk cache entries.
431  */
432  virtual void purge_invalid_cache() const;
433 
434  /**
435  * Perform a hook.
436  *
437  * \since 0.40 (previously in an interface)
438  * \since 0.53 takes optional_output_manager
439  */
440  virtual HookResult perform_hook(
441  const Hook & hook,
442  const std::shared_ptr<OutputManager> & optional_output_manager)
443  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
444 
445  /**
446  * Sync, if necessary.
447  *
448  * \return True if we synced successfully, false if we skipped sync.
449  * \since 0.42 (previously in an interface)
450  * \since 0.55 takes a source (may be empty)
451  * \since 0.61 takes a revision (may be empty)
452  */
453  virtual bool sync(
454  const std::string & source,
455  const std::string & revision,
456  const std::shared_ptr<OutputManager> &) const = 0;
457 
458  /**
459  * Allow the Repository to drop any memory-cached metadata and
460  * PackageIDs it holds.
461  *
462  * \since 0.42
463  */
464  virtual void can_drop_in_memory_cache() const;
465 
466  ///\}
467 
468  ///\name Set methods
469  ///\{
470 
471  /**
472  * Call Environment::add_set for every set we define.
473  *
474  * Environment will call this method at most once, so no cache or check for
475  * repeats is required. Nothing else should call this method.
476  *
477  * \since 0.40
478  */
479  virtual void populate_sets() const = 0;
480 
481  ///\}
482  };
483 
484  /**
485  * Interface for environment variable querying for repositories.
486  *
487  * \see Repository
488  * \ingroup g_repository
489  * \nosubgrouping
490  */
492  {
493  public:
494  ///\name Environment query functionality
495  ///\{
496 
497  /**
498  * Query an environment variable
499  */
500  virtual std::string get_environment_variable(
501  const std::shared_ptr<const PackageID> & for_package,
502  const std::string & var) const
503  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
504 
505  ///\}
506 
508  };
509 
510  /**
511  * Interface for repositories that can be used as an install destination.
512  *
513  * \see Repository
514  * \ingroup g_repository
515  * \nosubgrouping
516  */
518  {
519  public:
520  ///\name Destination functions
521  ///\{
522 
523  /**
524  * Are we a suitable destination for the specified package?
525  *
526  * \since 0.58 takes id by shared_ptr
527  */
528  virtual bool is_suitable_destination_for(const std::shared_ptr<const PackageID> &) const
529  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
530 
531  /**
532  * If true, pre and post install phases will be used when writing to this
533  * destination.
534  *
535  * This should return true for 'real' filesystem destinations (whether or
536  * not root is /, if root merges are supported), and false for intermediate
537  * destinations such as binary repositories.
538  */
539  virtual bool want_pre_post_phases() const
540  PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
541 
542  /**
543  * Merge a package.
544  */
545  virtual void merge(const MergeParams &) = 0;
546 
547  ///\}
548 
550  };
551 
552  /**
553  * Interface for making and verifying Manifest2-style manifests
554  *
555  * \see Repository
556  * \ingroup g_repository
557  * \nosubgrouping
558  */
560  {
561  public:
562  /**
563  * Makes the Manifest for a given package. Requires that all
564  * the needed DIST files, etc, have already been fetched.
565  */
566  virtual void make_manifest(const QualifiedPackageName &) = 0;
567 
568  ///\name Basic operations
569  ///\{
570 
571  virtual ~RepositoryManifestInterface();
572 
573  ///\}
574  };
575 }
576 
577 #endif
NamedValue< n::perform_uninstall, std::function< void(const std::shared_ptr< const PackageID > &, const UninstallActionOptions &)> > perform_uninstall
Definition: repository.hh:159
Definition: named_value-fwd.hh:29
Definition: pimp.hh:51
Definition: about_metadata-fwd.hh:23
NamedValue< n::parts, std::shared_ptr< Partitioning > > parts
Definition: repository.hh:149
NamedValue< n::build_start_time, Timestamp > build_start_time
Definition: repository.hh:115
NamedValue< n::merged_entries, std::shared_ptr< FSPathSet > > merged_entries
Definition: repository.hh:139
NamedValue< n::want_phase, std::function< WantPhase(const std::string &)> > want_phase
Definition: repository.hh:178
Definition: name.hh:110
Definition: action.hh:191
NamedValue< n::check, bool > check
Definition: repository.hh:124
NamedValue< n::permit_destination, PermitDestinationFn > permit_destination
Definition: repository.hh:162
Definition: exception.hh:74
Definition: hook.hh:61
NamedValue< n::is_volatile, std::function< bool(const FSPath &)> > is_volatile
Definition: repository.hh:133
Definition: environment.hh:200
Definition: repository.hh:93
Definition: repository.hh:559
Definition: hook.hh:74
Definition: named_value-fwd.hh:26
Definition: wrapped_value-fwd.hh:29
NamedValue< n::replacing, std::shared_ptr< const PackageIDSequence > > replacing
Definition: repository.hh:169
Definition: options-fwd.hh:34
Definition: repository.hh:217
Definition: repository.hh:188
Definition: repository.hh:246
Definition: repository.hh:107
Definition: action.hh:618
Definition: metadata_key_holder.hh:38
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
#define PALUDIS_VISIBLE
Definition: attributes.hh:59
Definition: repository.hh:517