lib/CPANPLUS/Dist/Base.pm

   1 package CPANPLUS::Dist::Base;
   2
   3 use strict;
   4
   5 use base    qw[CPANPLUS::Dist];
   6 use vars    qw[$VERSION];
   7 $VERSION =  $CPANPLUS::Internals::VERSION = $CPANPLUS::Internals::VERSION;
   8
   9
  10 =head1 NAME
  11
  12 CPANPLUS::Dist::Base - Base class for custom distribution classes
  13
  14 =head1 SYNOPSIS
  15
  16     package CPANPLUS::Dist::MY_IMPLEMENTATION
  17
  18     use base 'CPANPLUS::Dist::Base';
  19
  20     sub prepare {
  21         my $dist = shift;
  22
  23         ### do the 'standard' things
  24         $dist->SUPER::prepare( @_ ) or return;
  25
  26         ### do MY_IMPLEMENTATION specific things
  27         ...
  28
  29         ### don't forget to set the status!
  30         return $dist->status->prepared( $SUCCESS ? 1 : 0 );
  31     }
  32
  33
  34 =head1 DESCRIPTION
  35
  36 CPANPLUS::Dist::Base functions as a base class for all custom
  37 distribution implementations. It does all the mundane work
  38 CPANPLUS would have done without a custom distribution, so you
  39 can override just the parts you need to make your own implementation
  40 work.
  41
  42 =head1 FLOW
  43
  44 Below is a brief outline when and in which order methods in this
  45 class are called:
  46
  47     $Class->format_available;   # can we use this class on this system?
  48
  49     $dist->init;                # set up custom accessors, etc
  50     $dist->prepare;             # find/write meta information
  51     $dist->create;              # write the distribution file
  52     $dist->install;             # install the distribution file
  53
  54     $dist->uninstall;           # remove the distribution (OPTIONAL)
  55
  56 =head1 METHODS
  57
  58 =cut
  59
  60 =head2 @subs = $Class->methods
  61
  62 Returns a list of methods that this class implements that you can
  63 override.
  64
  65 =cut
  66
  67 sub methods {
  68     return qw[format_available init prepare create install uninstall]
  69 }
  70
  71 =head2 $bool = $Class->format_available
  72
  73 This method is called when someone requests a module to be installed
  74 via the superclass. This gives you the opportunity to check if all
  75 the needed requirements to build and install this distribution have
  76 been met.
  77
  78 For example, you might need a command line program, or a certain perl
  79 module installed to do your job. Now is the time to check.
  80
  81 Simply return true if the request can proceed and false if it can not.
  82
  83 The C<CPANPLUS::Dist::Base> implementation always returns true.
  84
  85 =cut
  86
  87 sub format_available { return 1 }
  88
  89
  90 =head2 $bool = $dist->init
  91
  92 This method is called just after the new dist object is set up and
  93 before the C<prepare> method is called. This is the time to set up
  94 the object so it can be used with your class.
  95
  96 For example, you might want to add extra accessors to the C<status>
  97 object, which you might do as follows:
  98
  99     $dist->status->mk_accessors( qw[my_implementation_accessor] );
 100
 101 The C<status> object is implemented as an instance of the
 102 C<Object::Accessor> class. Please refer to its documentation for
 103 details.
 104
 105 Return true if the initialization was successul, and false if it was
 106 not.
 107
 108 The C<CPANPLUS::Dist::Base> implementation does not alter your object
 109 and always returns true.
 110
 111 =cut
 112
 113 sub init { return 1; }
 114
 115 =head2 $bool = $dist->prepare
 116
 117 This runs the preparation step of your distribution. This step is meant
 118 to set up the environment so the C<create> step can create the actual
 119 distribution(file).
 120 A C<prepare> call in the standard C<ExtUtils::MakeMaker> distribution
 121 would, for example, run C<perl Makefile.PL> to find the dependencies
 122 for a distribution. For a C<debian> distribution, this is where you
 123 would write all the metafiles required for the C<dpkg-*> tools.
 124
 125 The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
 126 distribution class (Typically C<CPANPLUS::Dist::MM> or
 127 C<CPANPLUS::Dist::Build>).
 128
 129 Sets C<< $dist->status->prepared >> to the return value of this function.
 130 If you override this method, you should make sure to set this value.
 131
 132 =cut
 133
 134 sub prepare {
 135     ### just in case you already did a create call for this module object
 136     ### just via a different dist object
 137     my $dist        = shift;
 138     my $self        = $dist->parent;
 139     my $dist_cpan   = $self->status->dist_cpan;
 140
 141     my $cb   = $self->parent;
 142     my $conf = $cb->configure_object;
 143
 144     $dist->status->prepared( $dist_cpan->prepare( @_ ) );
 145 }
 146
 147 =head2 $bool = $dist->create
 148
 149 This runs the creation step of your distribution. This step is meant
 150 to follow up on the C<prepare> call, that set up your environment so
 151 the C<create> step can create the actual distribution(file).
 152 A C<create> call in the standard C<ExtUtils::MakeMaker> distribution
 153 would, for example, run C<make> and C<make test> to build and test
 154 a distribution. For a C<debian> distribution, this is where you
 155 would create the actual C<.deb> file using C<dpkg>.
 156
 157 The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
 158 distribution class (Typically C<CPANPLUS::Dist::MM> or
 159 C<CPANPLUS::Dist::Build>).
 160
 161 Sets C<< $dist->status->dist >> to the location of the created
 162 distribution.
 163 If you override this method, you should make sure to set this value.
 164
 165 Sets C<< $dist->status->created >> to the return value of this function.
 166 If you override this method, you should make sure to set this value.
 167
 168 =cut
 169
 170 sub create {
 171     ### just in case you already did a create call for this module object
 172     ### just via a different dist object
 173     my $dist        = shift;
 174     my $self        = $dist->parent;
 175     my $dist_cpan   = $self->status->dist_cpan;
 176     $dist           = $self->status->dist   if      $self->status->dist;
 177     $self->status->dist( $dist )            unless  $self->status->dist;
 178
 179     my $cb      = $self->parent;
 180     my $conf    = $cb->configure_object;
 181     my $format  = ref $dist;
 182
 183     ### make sure to set this variable, if the caller hasn't yet
 184     ### just so we have some clue where the dist left off.
 185     $dist->status->dist( $dist_cpan->status->distdir )
 186         unless defined $dist->status->dist;
 187
 188     $dist->status->created( $dist_cpan->create(prereq_format => $format, @_) );
 189 }
 190
 191 =head2 $bool = $dist->install
 192
 193 This runs the install step of your distribution. This step is meant
 194 to follow up on the C<create> call, which prepared a distribution(file)
 195 to install.
 196 A C<create> call in the standard C<ExtUtils::MakeMaker> distribution
 197 would, for example, run C<make install> to copy the distribution files
 198 to their final destination. For a C<debian> distribution, this is where
 199 you would run C<dpkg --install> on the created C<.deb> file.
 200
 201 The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
 202 distribution class (Typically C<CPANPLUS::Dist::MM> or
 203 C<CPANPLUS::Dist::Build>).
 204
 205 Sets C<< $dist->status->installed >> to the return value of this function.
 206 If you override this method, you should make sure to set this value.
 207
 208 =cut
 209
 210 sub install {
 211     ### just in case you already did a create call for this module object
 212     ### just via a different dist object
 213     my $dist        = shift;
 214     my $self        = $dist->parent;
 215     my $dist_cpan   = $self->status->dist_cpan;
 216
 217     my $cb   = $self->parent;
 218     my $conf = $cb->configure_object;
 219
 220     $dist->status->installed( $dist_cpan->install( @_ ) );
 221 }
 222
 223 =head2 $bool = $dist->uninstall
 224
 225 This runs the uninstall step of your distribution. This step is meant
 226 to remove the distribution from the file system.
 227 A C<uninstall> call in the standard C<ExtUtils::MakeMaker> distribution
 228 would, for example, run C<make uninstall> to remove the distribution
 229 files the file system. For a C<debian> distribution, this is where you
 230 would run C<dpkg --uninstall PACKAGE>.
 231
 232 The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
 233 distribution class (Typically C<CPANPLUS::Dist::MM> or
 234 C<CPANPLUS::Dist::Build>).
 235
 236 Sets C<< $dist->status->uninstalled >> to the return value of this function.
 237 If you override this method, you should make sure to set this value.
 238
 239 =cut
 240
 241 sub uninstall {
 242     ### just in case you already did a create call for this module object
 243     ### just via a different dist object
 244     my $dist        = shift;
 245     my $self        = $dist->parent;
 246     my $dist_cpan   = $self->status->dist_cpan;
 247
 248     my $cb   = $self->parent;
 249     my $conf = $cb->configure_object;
 250
 251     $dist->status->uninstalled( $dist_cpan->uninstall( @_ ) );
 252 }
 253
 254 1;
 255
 256 # Local variables:
 257 # c-indentation-style: bsd
 258 # c-basic-offset: 4
 259 # indent-tabs-mode: nil
 260 # End:
 261 # vim: expandtab shiftwidth=4: