view release on metacpan or  search on metacpan

lib/Alt.pod  view on Meta::CPAN

be short-lived, it can just be the author's CPAN id.

=item Makefile.PL Changes

Due to experience with L<http://cpantesters.org/> problems, it is important to
make your Alt module B<not> install without explicit direction. You can
accomplish this easily in a Makefile.PL, with something like this:

    my $alt = $ENV{PERL_ALT_INSTALL} || '';
    $WriteMakefileArgs{DESTDIR} =
      $alt ? $alt eq 'OVERWRITE' ? '' : $alt : 'no-install-alt';

Similar techniques should be available for other module release frameworks.

=item Module for CPAN Indexing

You will need to provide a module like C<Alt::IO::All::MSTROUT> so that
CPAN will index something that can cause your distribution to get installed
by people:

    PERL_ALT_INSTALL=OVERWRITE cpanm Alt::IO::All::MSTROUT

Since you are adding this module, you should add some doc to it explaining
your alternate version's improvements.

The Alt:: module can be as simple as this:

    package Alt::IO::All::MSTROUT;
    our $VERSION = '0.01';

=item no_index

It is important to use the C<no_index> directive on the modules you are
providing an alternates for. This is especially important if you are the
author of the original, as PAUSE will reindex CPAN to your Alt- version which
defeats the purpose. Even if you are not the same author, it will make your
index reports not show failures.

=item Versioning

It is important to not declare a C<$VERSION> in any of the modules that you
are providing alternates for. This will help ensure that your alternate
module does not satisfy the version requirements for something that wants the
real module.

If you want to depend on the alternate versions, then set the dependency on
the C<Alt::> module.

NOTE: If you provide an alternate Foo::Bar (with no VERSION) it B<will>
      satisfy the version requirements for someone who requires C<<
      Foo::Bar => 0 >>. In a sense, depending on version 0 means that
      alternates are OK.

=item C<use> the Alt

You should add this line to your alternate modules:

    use Alt::IO::All::MSTROUT;

That way the Alt:: module gets loaded any time you C<use IO::All> (with the
alternate version installed). This gives debugging clues since the Alt::
module is now in C<%INC>.

=item Other Concerns

If you have em, I(ngy) would like to know them. Discuss on #toolchain on
irc.perl.org for now.

=back

=head1 WHENCE ALT?

The Alt- concept was thought up by Ingy as he tried to figure out how to
revamp the somewhat popular IO::All and YAML.pm modules. Alternates can now be
released and alpha/beta tested, while the originals remain stable.

When Alt-IO-All-new is "community approved" it can replace IO-All. If people
want the old code, they can can install Alt-IO-All-old.

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT

Copyright 2012-2014. Ingy döt Net.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut