Alt(3pm)

✨ Alt — the whole vibe ✨

okay so bestie, you know how CPAN only lets ONE version of a module name exist at a time? Well Alt is the lil namespace that fixes that, and this page is the whole explanation: what it is, how it works, and how to do it right. Manual name? It's Alt(3pm), and yes it's a Perl thing, and yes it's giving genius 💅

---

🌸 NAME 🌸

Alt — Alternate Module Implementations. That's it, that's the name 🎀

---

⭐ SYNOPSIS ⭐

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

Like. That's the entire flex. One env var, one install, boom 🔥

---

🦋 DESCRIPTION 🦋

Alt:: is the namespace for alternate implementations of CPAN modules. That's the whole point of it.

The Alt module exists to give you documentation — it explains the Alt concept, how the whole thing works, and the guidelines for using it well. It's not code you run, it's the lore 📖

---

💀 THE PROBLEM 💀

So here's the tea. For any given piece of software, CPAN only allows for one implementation of a given module/distribution name. One. Singular. No exceptions.

GitHub, on the other hand? Not limited this way at all. Any author can make a fork, because GitHub repos are namespaced by author id. Everyone gets their own sandbox 🫶

On CPAN, even the author(s) of the module in question is limited by this, because they cannot release newer or older forks of their code without introducing a new name. Imagine being the author and still getting blocked from your own code. Not me crying 😭

---

👑 THE SOLUTION 👑

A module Foo::Bar is distributed on CPAN as Foo-Bar. It may have submodules like Foo::Bar::Baz.

To make an alternate CPAN version, leave everything exactly the same, except distribute the new version as Alt-Foo-Bar-AltIdentifier.

When a user installs your module like so:

PERL_ALT_INSTALL=OVERWRITE cpanm Alt::Foo::Bar::better

they will get your version of the Foo::Bar framework (Foo::Bar, Foo::Bar::Baz). Slay.

Obviously, this completely overlays the old Foo::Bar install, but that's the whole idea. The user isn't surprised by this because they just asked for an Alternate implementation — they knew what they were doing, main character energy. If they don't like it, they can simply reinstall the original Foo-Bar, or try some other alternate. No harm, no foul 💖

---

🌈 ALT BEST PRACTICES 🌈

This idea is new, and the details should be sorted out through proper discussions. Pull requests welcome, fr fr.

Here are the basic guidelines for best using the Alt namespace:

🎀 Name Creation 🎀

Names for alternate modules should be minted like this:

"Alt-$Original_Dist_Name-$phrase"

For instance, if MSTROUT wants to make an alternate IO-All distribution to have it be Moo-based, he might call it:

Alt-IO-All-Moo

He might also just call it:

Alt-IO-All-MSTROUT

By having 'Alt' at the start, it guarantees that it does not mess with future IO::All development — the way that protects everyone's future, iconic. The "phrase" at the end can be anything unique to CPAN, but should describe the spirit of the alternate. If the alternate is meant to be short-lived, it can just be the author's CPAN id.

💅 Makefile.PL Changes 💅

Due to experience with <http://cpantesters.org/> problems, it is important to make your Alt module 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. iykyk ✨

🧚 Module for CPAN Indexing 🧚

You will need to provide a module like 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. Give the people the info bestie 💜

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

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

🍓 no_index 🍓

It is important to use the 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. Highkey do not skip this one 🙈

⭐ Versioning ⭐

It is important to not declare a $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 Alt:: module.

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

🌸 "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 use IO::All (with the alternate version installed). This gives debugging clues since the Alt:: module is now in %INC. Little breadcrumbs of truth, we love to see it 🫶

💖 Other Concerns 💖

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

---

🌟 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. Best of both worlds, no cap.

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. (Yes the double "can can" is in the original and we respect the original 💅)

---

🦋 AUTHOR 🦋

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

---

🎀 COPYRIGHT 🎀

Copyright 2012-2014. Ingy döt Net.

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

---

and that's the whole page, bestie!! this was perl v5.36.0, dated 2022-11-27, and it's the Alt(3pm) page from the User Contributed Perl Documentation crew 🫶 go forth and make alternates responsibly, mwah 💖✨