[p5sagit/p5-mst-13.2.git] / ext / CPANPLUS / lib / CPANPLUS / Dist / Base.pm

package CPANPLUS::Dist::Base;

use strict;

use base    qw[CPANPLUS::Dist];
use vars    qw[$VERSION];
$VERSION =  $CPANPLUS::Internals::VERSION = $CPANPLUS::Internals::VERSION;


=head1 NAME

CPANPLUS::Dist::Base - Base class for custom distribution classes

=head1 SYNOPSIS

    package CPANPLUS::Dist::MY_IMPLEMENTATION

    use base 'CPANPLUS::Dist::Base';

    sub prepare {
        my $dist = shift;
        
        ### do the 'standard' things
        $dist->SUPER::prepare( @_ ) or return;
    
        ### do MY_IMPLEMENTATION specific things
        ...
        
        ### don't forget to set the status!
        return $dist->status->prepared( $SUCCESS ? 1 : 0 );
    }


=head1 DESCRIPTION

CPANPLUS::Dist::Base functions as a base class for all custom
distribution implementations. It does all the mundane work 
CPANPLUS would have done without a custom distribution, so you
can override just the parts you need to make your own implementation
work.

=head1 FLOW

Below is a brief outline when and in which order methods in this
class are called:

    $Class->format_available;   # can we use this class on this system?

    $dist->init;                # set up custom accessors, etc
    $dist->prepare;             # find/write meta information
    $dist->create;              # write the distribution file
    $dist->install;             # install the distribution file
    
    $dist->uninstall;           # remove the distribution (OPTIONAL)

=head1 METHODS

=cut

=head2 @subs = $Class->methods

Returns a list of methods that this class implements that you can
override.

=cut

sub methods { 
    return qw[format_available init prepare create install uninstall] 
}

=head2 $bool = $Class->format_available

This method is called when someone requests a module to be installed
via the superclass. This gives you the opportunity to check if all
the needed requirements to build and install this distribution have
been met.

For example, you might need a command line program, or a certain perl
module installed to do your job. Now is the time to check.

Simply return true if the request can proceed and false if it can not.

The C<CPANPLUS::Dist::Base> implementation always returns true.

=cut 

sub format_available { return 1 }


=head2 $bool = $dist->init

This method is called just after the new dist object is set up and
before the C<prepare> method is called. This is the time to set up
the object so it can be used with your class. 

For example, you might want to add extra accessors to the C<status>
object, which you might do as follows:

    $dist->status->mk_accessors( qw[my_implementation_accessor] );
    
The C<status> object is implemented as an instance of the 
C<Object::Accessor> class. Please refer to its documentation for 
details.
    
Return true if the initialization was successul, and false if it was
not.
    
The C<CPANPLUS::Dist::Base> implementation does not alter your object 
and always returns true.

=cut

sub init { return 1; }

=head2 $bool = $dist->prepare

This runs the preparation step of your distribution. This step is meant
to set up the environment so the C<create> step can create the actual
distribution(file). 
A C<prepare> call in the standard C<ExtUtils::MakeMaker> distribution 
would, for example, run C<perl Makefile.PL> to find the dependencies
for a distribution. For a C<debian> distribution, this is where you 
would write all the metafiles required for the C<dpkg-*> tools.

The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
distribution class (Typically C<CPANPLUS::Dist::MM> or 
C<CPANPLUS::Dist::Build>).

Sets C<< $dist->status->prepared >> to the return value of this function.
If you override this method, you should make sure to set this value.

=cut

sub prepare { 
    ### just in case you already did a create call for this module object
    ### just via a different dist object
    my $dist        = shift;
    my $self        = $dist->parent;
    my $dist_cpan   = $self->status->dist_cpan;

    my $cb   = $self->parent;
    my $conf = $cb->configure_object;

    $dist->status->prepared( $dist_cpan->prepare( @_ ) );
}

=head2 $bool = $dist->create

This runs the creation step of your distribution. This step is meant
to follow up on the C<prepare> call, that set up your environment so 
the C<create> step can create the actual distribution(file). 
A C<create> call in the standard C<ExtUtils::MakeMaker> distribution 
would, for example, run C<make> and C<make test> to build and test
a distribution. For a C<debian> distribution, this is where you 
would create the actual C<.deb> file using C<dpkg>.

The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
distribution class (Typically C<CPANPLUS::Dist::MM> or 
C<CPANPLUS::Dist::Build>).

Sets C<< $dist->status->dist >> to the location of the created 
distribution.
If you override this method, you should make sure to set this value.

Sets C<< $dist->status->created >> to the return value of this function.
If you override this method, you should make sure to set this value.

=cut

sub create { 
    ### just in case you already did a create call for this module object
    ### just via a different dist object
    my $dist        = shift;
    my $self        = $dist->parent;
    my $dist_cpan   = $self->status->dist_cpan;
    $dist           = $self->status->dist   if      $self->status->dist;
    $self->status->dist( $dist )            unless  $self->status->dist;

    my $cb      = $self->parent;
    my $conf    = $cb->configure_object;
    my $format  = ref $dist;

    ### make sure to set this variable, if the caller hasn't yet
    ### just so we have some clue where the dist left off.
    $dist->status->dist( $dist_cpan->status->distdir )
        unless defined $dist->status->dist;

    $dist->status->created( $dist_cpan->create(prereq_format => $format, @_) );
}

=head2 $bool = $dist->install

This runs the install step of your distribution. This step is meant
to follow up on the C<create> call, which prepared a distribution(file)
to install.
A C<create> call in the standard C<ExtUtils::MakeMaker> distribution 
would, for example, run C<make install> to copy the distribution files
to their final destination. For a C<debian> distribution, this is where 
you would run C<dpkg --install> on the created C<.deb> file.

The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
distribution class (Typically C<CPANPLUS::Dist::MM> or 
C<CPANPLUS::Dist::Build>).

Sets C<< $dist->status->installed >> to the return value of this function.
If you override this method, you should make sure to set this value.

=cut

sub install { 
    ### just in case you already did a create call for this module object
    ### just via a different dist object
    my $dist        = shift;
    my $self        = $dist->parent;
    my $dist_cpan   = $self->status->dist_cpan;    

    my $cb   = $self->parent;
    my $conf = $cb->configure_object;

    $dist->status->installed( $dist_cpan->install( @_ ) );
}

=head2 $bool = $dist->uninstall

This runs the uninstall step of your distribution. This step is meant
to remove the distribution from the file system. 
A C<uninstall> call in the standard C<ExtUtils::MakeMaker> distribution 
would, for example, run C<make uninstall> to remove the distribution 
files the file system. For a C<debian> distribution, this is where you 
would run C<dpkg --uninstall PACKAGE>.

The C<CPANPLUS::Dist::Base> implementation simply calls the underlying
distribution class (Typically C<CPANPLUS::Dist::MM> or 
C<CPANPLUS::Dist::Build>).

Sets C<< $dist->status->uninstalled >> to the return value of this function.
If you override this method, you should make sure to set this value.

=cut

sub uninstall { 
    ### just in case you already did a create call for this module object
    ### just via a different dist object
    my $dist        = shift;
    my $self        = $dist->parent;
    my $dist_cpan   = $self->status->dist_cpan;    

    my $cb   = $self->parent;
    my $conf = $cb->configure_object;

    $dist->status->uninstalled( $dist_cpan->uninstall( @_ ) );
}

1;              

# Local variables:
# c-indentation-style: bsd
# c-basic-offset: 4
# indent-tabs-mode: nil
# End:
# vim: expandtab shiftwidth=4:
Commit	Line	Data
6aaee015	1	package CPANPLUS::Dist::Base;
	2
	3	use strict;
	4
4443dd53	5	use base qw[CPANPLUS::Dist];
	6	use vars qw[$VERSION];
	7	$VERSION = $CPANPLUS::Internals::VERSION = $CPANPLUS::Internals::VERSION;
	8
6aaee015	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
4443dd53	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	}
6aaee015	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
4443dd53	102	C<Object::Accessor> class. Please refer to its documentation for
6aaee015	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
e3b7d412	179	my $cb = $self->parent;
	180	my $conf = $cb->configure_object;
	181	my $format = ref $dist;
6aaee015	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
e3b7d412	188	$dist->status->created( $dist_cpan->create(prereq_format => $format, @_) );
6aaee015	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: