paludis  Version 2.6.0
action.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2007, 2008, 2009, 2010, 2011 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_ACTION_HH
21 #define PALUDIS_GUARD_PALUDIS_ACTION_HH 1
22 
23 #include <paludis/action-fwd.hh>
26 #include <paludis/contents-fwd.hh>
27 #include <paludis/output_manager-fwd.hh>
28 
30 #include <paludis/util/visitor.hh>
32 #include <paludis/util/pimp.hh>
34 #include <paludis/util/named_value.hh>
35 #include <paludis/util/fs_path-fwd.hh>
36 #include <paludis/util/options.hh>
37 #include <paludis/util/type_list.hh>
38 
39 #include <functional>
40 
41 /** \file
42  * Declarations for action-related classes.
43  *
44  * \ingroup g_actions
45  *
46  * \section Examples
47  *
48  * - \ref example_action.cc "example_action.cc"
49  */
50 
51 namespace paludis
52 {
53  namespace n
54  {
55  typedef Name<struct name_config_protect> config_protect;
56  typedef Name<struct name_destination> destination;
57  typedef Name<struct name_errors> errors;
58  typedef Name<struct name_exclude_unmirrorable> exclude_unmirrorable;
59  typedef Name<struct name_failed_automatic_fetching> failed_automatic_fetching;
60  typedef Name<struct name_failed_integrity_checks> failed_integrity_checks;
61  typedef Name<struct name_fetch_parts> fetch_parts;
62  typedef Name<struct name_if_for_install_id> if_for_install_id;
63  typedef Name<struct name_ignore_for_unmerge> ignore_for_unmerge;
64  typedef Name<struct name_ignore_unfetched> ignore_unfetched;
65  typedef Name<struct name_is_overwrite> is_overwrite;
66  typedef Name<struct name_make_output_manager> make_output_manager;
67  typedef Name<struct name_override_contents> override_contents;
68  typedef Name<struct name_perform_uninstall> perform_uninstall;
69  typedef Name<struct name_replacing> replacing;
70  typedef Name<struct name_requires_manual_fetching> requires_manual_fetching;
71  typedef Name<struct name_safe_resume> safe_resume;
72  typedef Name<struct name_target_file> target_file;
73  typedef Name<struct name_want_phase> want_phase;
74  typedef Name<struct name_ignore_not_in_manifest> ignore_not_in_manifest;
75  }
76 
77  /**
78  * Options for a FetchAction.
79  *
80  * \see FetchAction
81  * \ingroup g_actions
82  * \since 0.30
83  */
85  {
86  /**
87  * Any errors that occur will be added to this list. Must not be null.
88  *
89  * \since 0.40
90  */
92 
93  /**
94  * \since 0.32
95  */
97 
98  /**
99  * Which parts to fetch.
100  *
101  * \since 0.43
102  */
104 
105  /**
106  * Ignore if a package is or isn't referenced in the Manifest.
107  * It's useful for generating manifests, to avoid getting errors
108  * before generating it.
109  *
110  * \since 0.46
111  */
113 
114  /**
115  * Ignore any unfetched packages. Verify digests for anything that's
116  * already there, and if we know for sure manual fetching will be
117  * required, raise the appropriate error.
118  *
119  * \since 0.36
120  */
122 
123  /**
124  * This is a function to avoid chicken / egg problems when using
125  * Environment::create_output_manager.
126  *
127  * \since 0.36
128  */
130  const FetchAction &)> > make_output_manager;
131 
133 
134  /**
135  * \since 0.48
136  */
138  };
139 
140  /**
141  * Options for an InstallAction.
142  *
143  * \see InstallAction
144  * \ingroup g_actions
145  * \since 0.30
146  */
148  {
150 
151  /**
152  * This is a function to avoid chicken / egg problems when using
153  * Environment::create_output_manager.
154  *
155  * \since 0.36
156  */
158  const InstallAction &)> > make_output_manager;
159 
160  /**
161  * Callback to carry out an uninstall, for replacing.
162  *
163  * Won't necessarily be used. Some repositories have special code paths
164  * for reinstalls, and in some cases (e.g. accounts) an upgrade doesn't
165  * remove the old version at all.
166  *
167  * \since 0.36
168  */
169  NamedValue<n::perform_uninstall, std::function<void (
170  const std::shared_ptr<const PackageID> &,
171  const UninstallActionOptions &
173 
174  /**
175  * We must replace these.
176  *
177  * \since 0.36
178  */
180 
182  };
183 
184  /**
185  * Options for an UninstallAction.
186  *
187  * \see UninstallAction
188  * \ingroup g_actions
189  * \since 0.30
190  */
192  {
194 
195  /**
196  * If we're being uninstalled as part of an install, this is the ID
197  * that's being installed. Otherwise null.
198  *
199  * \since 0.36
200  */
202 
203  /**
204  * Sometimes we never want to unmerge certain files.
205  *
206  * \since 0.38
207  * \since 0.55 uses FSPath
208  */
210 
211  /**
212  * Some repositories need to do special handlings for direct overwrites
213  * (foo-1.2 replacing foo-1.2). Clients should set this to false.
214  *
215  * \since 0.36
216  */
218 
219  /**
220  * This is a function to avoid chicken / egg problems when using
221  * Environment::create_output_manager.
222  *
223  * \since 0.36
224  */
226  const UninstallAction &)> > make_output_manager;
227 
228  /**
229  * Sometimes we need to override the contents of an installed package,
230  * for example when doing 'overwrite' merges for VDB.
231  *
232  * Not all repositories support this, or do what you expect with it. Clients
233  * should always set this to null.
234  *
235  * \since 0.61
236  */
238 
239  /**
240  * \since 0.77
241  */
243  };
244 
245  /**
246  * A failed fetch action part.
247  *
248  * \see FetchActionError
249  * \ingroup g_actions
250  * \since 0.30
251  */
253  {
254  NamedValue<n::failed_automatic_fetching, bool> failed_automatic_fetching;
256  NamedValue<n::requires_manual_fetching, bool> requires_manual_fetching;
258  };
259 
260  /**
261  * An Action represents an action that can be executed by a PackageID via
262  * PackageID::perform_action.
263  *
264  * \since 0.26
265  * \ingroup g_actions
266  * \nosubgrouping
267  */
269  public virtual DeclareAbstractAcceptMethods<Action, MakeTypeList<
270  InstallAction, UninstallAction, PretendAction, ConfigAction, FetchAction,
271  InfoAction, PretendFetchAction>::Type>
272  {
273  public:
274  ///\name Basic operations
275  ///\{
276 
277  virtual ~Action() = 0;
278 
279  ///\}
280 
281  /**
282  * A simple string name (install, uninstall, pretend-fetch etc).
283  *
284  * \since 0.44
285  */
286  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result)) = 0;
287  };
288 
289  /**
290  * An InstallAction is used by InstallTask to perform a build / install on a
291  * PackageID.
292  *
293  * \since 0.26
294  * \ingroup g_actions
295  * \nosubgrouping
296  */
298  public Action,
299  public ImplementAcceptMethods<Action, InstallAction>
300  {
301  private:
302  Pimp<InstallAction> _imp;
303 
304  public:
305  ///\name Basic operations
306  ///\{
307 
309  ~InstallAction();
310 
311  ///\}
312 
313  /// Options for the action.
315 
316  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
317 
318  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
319  };
320 
321  /**
322  * A FetchAction can be used to fetch source files for a PackageID using
323  * PackageID::perform_action.
324  *
325  * \since 0.26
326  * \ingroup g_actions
327  * \nosubgrouping
328  */
330  public Action,
331  public ImplementAcceptMethods<Action, FetchAction>
332  {
333  private:
334  Pimp<FetchAction> _imp;
335 
336  public:
337  ///\name Basic operations
338  ///\{
339 
340  FetchAction(const FetchActionOptions &);
341  ~FetchAction();
342 
343  ///\}
344 
345  /// Options for the action.
347 
348  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
349 
350  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
351  static const std::string ignore_unfetched_flag_name() PALUDIS_ATTRIBUTE((warn_unused_result));
352  };
353 
354  /**
355  * An UninstallAction is used by UninstallTask to uninstall a PackageID.
356  *
357  * \since 0.26
358  * \ingroup g_actions
359  * \nosubgrouping
360  */
362  public Action,
364  {
365  private:
367 
368  public:
369  ///\name Basic operations
370  ///\{
371 
372  UninstallAction(const UninstallActionOptions &);
373  ~UninstallAction();
374 
375  ///\}
376 
377  /// Options for the action.
379 
380  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
381 
382  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
383  };
384 
385  /**
386  * Options for a PretendAction.
387  *
388  * \see PretendAction
389  * \ingroup g_actions
390  * \since 0.36
391  */
393  {
395 
396  /**
397  * This is a function to avoid chicken / egg problems when using
398  * Environment::create_output_manager.
399  *
400  * \since 0.36
401  */
403  const PretendAction &)> > make_output_manager;
404 
405  /**
406  * We will replace these.
407  *
408  * \since 0.55
409  */
411  };
412 
413  /**
414  * A PretendAction is used by InstallTask to handle install-pretend-phase
415  * checks on a PackageID.
416  *
417  * \since 0.26
418  * \ingroup g_actions
419  * \nosubgrouping
420  */
422  public Action,
423  public ImplementAcceptMethods<Action, PretendAction>
424  {
425  private:
426  Pimp<PretendAction> _imp;
427 
428  public:
429  ///\name Basic operations
430  ///\{
431 
432  /**
433  * \since 0.36
434  */
436  ~PretendAction();
437 
438  ///\}
439 
440  /// Did our pretend phase fail?
441  bool failed() const PALUDIS_ATTRIBUTE((warn_unused_result));
442 
443  /// Mark the action as failed.
444  void set_failed();
445 
446  /**
447  * \since 0.36
448  */
450 
451  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
452 
453  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
454  };
455 
456  /**
457  * A PretendFetchAction is used to get information about a fetch that will take
458  * place on a PackageID.
459  *
460  * \since 0.26
461  * \ingroup g_actions
462  * \nosubgrouping
463  */
465  public Action,
467  {
468  private:
470 
471  public:
472  ///\name Basic operations
473  ///\{
474 
475  PretendFetchAction(const FetchActionOptions &);
476  ~PretendFetchAction();
477 
478  ///\}
479 
480  /// Options for the FetchAction we will use.
482 
483  /// Signal that we will fetch a particular file.
484  virtual void will_fetch(const FSPath & destination, const unsigned long size_in_bytes) = 0;
485 
486  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
487 
488  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
489  };
490 
491  /**
492  * Options for a ConfigAction.
493  *
494  * \see ConfigAction
495  * \ingroup g_actions
496  * \since 0.36
497  */
499  {
500  /**
501  * This is a function to avoid chicken / egg problems when using
502  * Environment::create_output_manager.
503  *
504  * \since 0.36
505  */
507  const ConfigAction &)> > make_output_manager;
508  };
509 
510  /**
511  * A ConfigAction is used via PackageID::perform_action to execute
512  * post-install configuration (for example, via 'paludis --config')
513  * on a PackageID.
514  *
515  * \since 0.26
516  * \ingroup g_actions
517  * \nosubgrouping
518  */
520  public Action,
521  public ImplementAcceptMethods<Action, ConfigAction>
522  {
523  private:
524  Pimp<ConfigAction> _imp;
525 
526  public:
527  ///\name Basic operations
528  ///\{
529 
530  /**
531  * \since 0.36
532  */
534  ~ConfigAction();
535 
536  ///\}
537 
538  /**
539  * \since 0.36
540  */
542 
543  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
544 
545  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
546  };
547 
548  /**
549  * Options for an InfoAction.
550  *
551  * \see InfoAction
552  * \ingroup g_actions
553  * \since 0.36
554  */
556  {
557  /**
558  * This is a function to avoid chicken / egg problems when using
559  * Environment::create_output_manager.
560  *
561  * \since 0.36
562  */
564  const InfoAction &)> > make_output_manager;
565  };
566 
567  /**
568  * An InfoAction is used via PackageID::perform_action to execute
569  * additional information (for example, via 'paludis --info')
570  * on a PackageID.
571  *
572  * This action potentially makes sense for both installed and
573  * installable packages. Unlike Ebuild EAPI-0 'pkg_info', this
574  * action is not specifically tied to installed packages.
575  *
576  * \since 0.26
577  * \ingroup g_actions
578  * \nosubgrouping
579  */
581  public Action,
582  public ImplementAcceptMethods<Action, InfoAction>
583  {
584  private:
585  Pimp<InfoAction> _imp;
586 
587  public:
588  ///\name Basic operations
589  ///\{
590 
591  /**
592  * \since 0.36
593  */
594  InfoAction(const InfoActionOptions &);
595 
596  ~InfoAction();
597 
598  ///\}
599 
600  /**
601  * \since 0.36
602  */
604 
605  virtual const std::string simple_name() const PALUDIS_ATTRIBUTE((warn_unused_result));
606 
607  static const std::string class_simple_name() PALUDIS_ATTRIBUTE((warn_unused_result));
608  };
609 
610  /**
611  * Base class for SupportsActionTest<>.
612  *
613  * \see SupportsActionTest<>
614  * \since 0.26
615  * \ingroup g_actions
616  * \nosubgrouping
617  */
622  SupportsActionTest<InfoAction>, SupportsActionTest<PretendFetchAction> >::Type>
623  {
624  public:
625  virtual ~SupportsActionTestBase() = 0;
626  };
627 
628  /**
629  * Instantiated with an Action subclass as its template parameter,
630  * SupportsActionTest<> is used by PackageID::supports_action and
631  * Repository::some_ids_might_support_action to query whether a
632  * particular action is supported by that PackageID or potentially
633  * supported by some IDs in that Repository.
634  *
635  * Use of a separate class, rather than a mere Action, avoids the
636  * need to create bogus options for the more complicated Action
637  * subclasses.
638  *
639  * \since 0.26
640  * \ingroup g_actions
641  * \nosubgrouping
642  */
643  template <typename A_>
644  class PALUDIS_VISIBLE SupportsActionTest :
645  public SupportsActionTestBase,
646  public ImplementAcceptMethods<SupportsActionTestBase, SupportsActionTest<A_> >
647  {
648  };
649 
650  /**
651  * Thrown if an action fails.
652  *
653  * \ingroup g_actions
654  * \ingroup g_exceptions
655  * \since 0.42
656  */
658  public Exception
659  {
660  public:
661  ///\name Basic operations
662  ///\{
663 
664  ActionFailedError(const std::string & msg) noexcept;
665 
666  ///\}
667  };
668 
669  /**
670  * Thrown if an action is aborted.
671  *
672  * \ingroup g_actions
673  * \ingroup g_exceptions
674  * \since 0.42
675  */
677  public Exception
678  {
679  public:
680  ///\name Basic operations
681  ///\{
682 
683  ActionAbortedError(const std::string &) noexcept;
684 
685  ///\}
686  };
687 
688  extern template class Pimp<FetchAction>;
689  extern template class Pimp<InstallAction>;
690  extern template class Pimp<PretendAction>;
691  extern template class Pimp<PretendFetchAction>;
692  extern template class Pimp<UninstallAction>;
693  extern template class Pimp<InfoAction>;
694  extern template class Pimp<ConfigAction>;
695 }
696 
697 #endif
Definition: named_value-fwd.hh:29
NamedValue< n::exclude_unmirrorable, bool > exclude_unmirrorable
Definition: action.hh:96
Definition: pimp.hh:51
Definition: action.hh:580
Definition: about_metadata-fwd.hh:23
Definition: action.hh:464
NamedValue< n::if_for_install_id, std::shared_ptr< const PackageID > > if_for_install_id
Definition: action.hh:201
const FetchActionOptions & options
Options for the action.
Definition: action.hh:346
Definition: visitor-fwd.hh:52
const InstallActionOptions & options
Options for the action.
Definition: action.hh:314
Definition: action.hh:392
Definition: action.hh:421
NamedValue< n::replacing, std::shared_ptr< const PackageIDSequence > > replacing
Definition: action.hh:410
NamedValue< n::is_overwrite, bool > is_overwrite
Definition: action.hh:217
Definition: action.hh:329
Definition: action.hh:191
Definition: action.hh:252
Definition: action.hh:555
const InfoActionOptions & options
Definition: action.hh:603
STL namespace.
NamedValue< n::errors, std::shared_ptr< Sequence< FetchActionFailure > > > errors
Definition: action.hh:91
NamedValue< n::want_phase, std::function< WantPhase(const std::string &)> > want_phase
Definition: action.hh:137
NamedValue< n::ignore_for_unmerge, std::function< bool(const FSPath &)> > ignore_for_unmerge
Definition: action.hh:209
const UninstallActionOptions & options
Options for the action.
Definition: action.hh:378
const PretendActionOptions & options
Definition: action.hh:449
Definition: action.hh:297
NamedValue< n::fetch_parts, FetchParts > fetch_parts
Definition: action.hh:103
Definition: action.hh:657
Definition: action.hh:498
Definition: exception.hh:74
NamedValue< n::ignore_unfetched, bool > ignore_unfetched
Definition: action.hh:121
Definition: action.hh:519
Definition: type_list-fwd.hh:31
Definition: action.hh:84
Definition: action.hh:676
Definition: action.hh:268
Definition: named_value-fwd.hh:26
Definition: action.hh:147
NamedValue< n::override_contents, std::shared_ptr< const Contents > > override_contents
Definition: action.hh:237
NamedValue< n::ignore_not_in_manifest, bool > ignore_not_in_manifest
Definition: action.hh:112
NamedValue< n::perform_uninstall, std::function< void(const std::shared_ptr< const PackageID > &, const UninstallActionOptions &)> > perform_uninstall
Definition: action.hh:172
const FetchActionOptions & options
Options for the FetchAction we will use.
Definition: action.hh:481
Definition: action-fwd.hh:45
Definition: visitor-fwd.hh:49
Definition: fs_path.hh:33
NamedValue< n::want_phase, std::function< WantPhase(const std::string &)> > want_phase
Definition: action.hh:242
Definition: action.hh:618
Definition: action.hh:361
NamedValue< n::replacing, std::shared_ptr< const PackageIDSequence > > replacing
Definition: action.hh:179
const ConfigActionOptions & options
Definition: action.hh:541
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
#define PALUDIS_VISIBLE
Definition: attributes.hh:59