Devel::MaintBlead - handle maint / blead code paths for distributions
This documentation describes version 0.08.
# 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
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.
Basically, one needs to set up a file structure first, and then make some changes to the Makefile.PL.
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:
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:
In Unix terms:
$ cp -rp lib lib_maint
$ cp -rp t t_maint
In perl terms:
$ perl -e 'rename $_, "${_}_maint" foreach ( <lib_maint/**>, <t_maint/*> )'
Edit the MANIFEST file to add all of the files you just created, including a MANIFEST_maint file which you will create after this.
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.
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.
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.
do
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.
$LIB_TREE
lib/
Foo::Bar::Baz module
Foo/Bar
The $REQUIRED variable should contain the minimum version of Perl that supports the blead version of the code.
$REQUIRED
blead
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.
$MAINT
maint
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.
Any subsequent loading of this module, will just execute the "maintblead" file, do any code path manipulation and not do anything else.
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.
(none)
Elizabeth Mattijsen, <liz@dijkmat.nl>.
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.
To install Devel::MaintBlead, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::MaintBlead
CPAN shell
perl -MCPAN -e shell install Devel::MaintBlead
For more information on module installation, please visit the detailed CPAN module installation guide.