/ 
Devel-MaintBlead-0.08
River stage zero No dependents
/ Devel::MaintBlead

NAME

Devel::MaintBlead - handle maint / blead code paths for distributions

VERSION

This documentation describes version 0.08.

SYNOPSIS

# before
our $LIB_TREE= 'Foo/Bar';
our $REQUIRED= '5.014';
eval "use Devel::MaintBlead";

# after
our $LIB_TREE= 'Foo/Bar';
our $REQUIRED= '5.014';
eval "use Devel::MaintBlead; 1" or do 'maintblead';
# "maintblead" written and added to MANIFEST

DESCRIPTION

The Devel::MaintBlead module only serves a purpose in the development environment of an author of a CPAN distribution (or more precisely: a user of the ExtUtils::MakeMaker module). It only needs to be installed on the development environment of an author of a CPAN distribution.

It allows a developer to easily maintain two code paths of the same module(s) in the same distribution. Each code path has its own source in the "lib" directory, its own tests in the "t" directory, and its own MANIFEST.

If the "blead" version of the code is active, a "make dist" will create a distribution file for the "blead" version. If the "maint" version of the code is active, a "make dist" will create a distribution file for the "maint" version. It is important that the two code versions have different version numbers, as PAUSE / CPAN will only accept one upload per version number.

Usually, if both code paths have been updated and ready for CPAN, one will <first> upload the distribution file for the "maint" version. And then the distribution file for the "blead" version. This will make the most modern release of your distribution, also the most recent.

SETUP AND USAGE

Basically, one needs to set up a file structure first, and then make some changes to the Makefile.PL.

INITIAL SETUP

By default, the "blead" version is active and its files are:

lib/**.pm
t/*.t
MANIFEST

and the "maint" version of the files are:

lib_maint/**.pm_maint
t_main/*.t_maint
MANIFEST_maint

Please note that '**' here indicates any number of subdirectories.

If the "maint" version is active, then its files are:

lib/**.pm
t/*.t
MANIFEST

and then the "blead" files are:

lib_blead/**.pm_blead
t_blead/*.t_blead
MANIFEST_blead

Note that the inactive files have the type of code path added to their extension.

If you want to convert your distribution to use this module, you will have to basically:

copy all .pm files to lib_maint

In Unix terms:

$ cp -rp lib lib_maint
copy all .t files to t_maint

In Unix terms:

$ cp -rp t t_maint
add "_maint" to all files just copied

In perl terms:

$ perl -e 'rename $_, "${_}_maint" foreach ( <lib_maint/**>, <t_maint/*> )'
add _maint files to MANIFEST

Edit the MANIFEST file to add all of the files you just created, including a MANIFEST_maint file which you will create after this.

copy MANIFEST to MANIFEST_maint, and change _maint to _blead

This is the MANIFEST file that is active if the "maint" version of the code is active. In that state, all of the inactive files have "_blead" added to their file extension. This is easily achievable by changing all occurrences of "_maint" to "_blead" in the MANIFEST_maint file.

make versions different

The distribution versions of each code path should have a different version. This is usually the $VERSION of the main source file. Generally, one would increase the version number of the "blead" version of the code to the next major version, e.g. if the code is at "0.20", then the "blead" version should become "1.00", to really set it apart from the "maint" version.

It is currently considered too dangerous to automate this process. It might get automated later at some point in time.

There are basically three situations in which this module can get called.

INITIAL RUN BY DEVELOPER

If the developer has Devel::MaintBlead installed, and adds the lines:

our $LIB_TREE= 'Foo/Bar';
our $REQUIRED= '5.014';
eval "use Devel::MaintBlead";

to the Makefile.PL, then running the Makefile.PL will create a file called "maintblead" in the current directory. This file is intended to be called with a do. It contains the code version logic which performs the actual checks and moves files around if necessary.

The $LIB_TREE variable should contain the path to the directory with the source files without the lib/. So for the Foo::Bar::Baz module, this would be Foo/Bar.

The $REQUIRED variable should contain the minimum version of Perl that supports the blead version of the code.

The $MAINT variable will be set to 1 if the maint version of the code has been selected. Otherwise the $MAINT variable will be 0. It can be used to further adapt the functioning of your Makefile.PL, e.g. to be able to set different dependencies in the call to WriteMakefile.

It will also adapt the code in the Makefile.PL itself by changing it to:

our $LIB_TREE= 'Foo/Bar';
our $REQUIRED= '5.014';
eval "use Devel::MaintBlead; 1" or do "maintblead";

Finally, it will adapt all the MANIFEST files by adding the line:

maintblead                  maint/blead test (Added by Devel::MaintBlead)

This will cause the check file to be included in any distribution made for that Makefile.PL.

LATER RUNS BY DEVELOPER

Any subsequent loading of this module, will just execute the "maintblead" file, do any code path manipulation and not do anything else.

INSTALLATION BY USER

A user trying to install the distribution, will most likely not have the Devel::MaintBlead module installed. This is ok, because then the eval in:

eval "use Devel::MaintBlead; 1" or do 'maintblead';

will fail, and the "maintblead" file will get executed. And thus perform the necessary actions in the user environment.

REQUIRED MODULES

(none)

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

COPYRIGHT

Copyright (c) 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.