[Summary view] [Print] [Text view]

   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: