File Coverage

lib/CPANPLUS/Dist/Base.pm
Criterion Covered Total %
statement 10 40 25.0
branch 0 6 0.0
condition n/a
subroutine 4 10 40.0
pod 7 7 100.0
total 21 63 33.3


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