lib/CPANPLUS/Dist/Base.pm

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