CPANPL...::Base(3pm)

✨ CPANPLUS::Dist::Base — the base class glow-up ✨

okay so bestie, you know that page CPANPL...::Base(3pm) in the User Contributed Perl Documentation? That's this one 💖 and it's genuinely so useful, so let's get into it.

---

🌸 NAME 🌸

CPANPLUS::Dist::Base — the base class for custom distribution classes. she's the blueprint, the template, the blueprint-template situation 🎀

---

🦋 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 );
}

like, that's the whole vibe. inherit, call SUPER::, do your own little thing, set the status. no cap 💅

---

💜 DESCRIPTION 💜

CPANPLUS::Dist::Base is the base class for all custom distribution implementations. Basically it does all the mundane, boring, chores-y work that CPANPLUS would have done if you'd never made a custom distribution at all — so you can override just the parts you need to make your own implementation work. iconic behavior honestly. she does the dishes so you can do the fun part 🫶

---

🌈 FLOW 🌈

here's the lil outline of when and in what order the methods in this class get called. it's giving choreography 💃

$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)

note that uninstall is marked OPTIONAL — she comes and goes as she pleases 🙈

---

👑 METHODS 👑

🍓 @subs = $Class->methods

Returns a list of methods that this class implements that you can override. go off, pick your faves ✨

🍓 $bool = $Class->format_available

This one gets called when someone requests a module to be installed via the superclass. It's your moment — your opportunity — to check if all the needed requirements to build and install this distribution have actually been met.

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

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

The CPANPLUS::Dist::Base implementation always returns true. she's an optimist 💖

🍓 $bool = $dist->init

This method is called just after the new dist object is set up and before the prepare method is called. This is the time to set up the object so it can be used with your class. it's giving getting-ready-in-the-mirror 🪞

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

$dist->status->mk_accessors( qw[my_implementation_accessor] );

The status object is implemented as an instance of the Object::Accessor class. Please refer to its documentation for details.

Return true if the initialization was successful, and false if it was not.

The CPANPLUS::Dist::Base implementation does not alter your object and always returns true. respectful queen, she touches nothing 🌸

🍓 $bool = $dist->prepare

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

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

⚠️ Sets $dist->status->prepared to the return value of this function. If you override this method, you should make sure to set this value. do not forget, bestie, I am begging 😭

🍓 $bool = $dist->create

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

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

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

⚠️ Sets $dist->status->created to the return value of this function. If you override this method, you should make sure to set this value. two things to set here, don't skip either 🫶

🍓 $bool = $dist->install

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

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

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

🍓 $bool = $dist->uninstall

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

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

⚠️ Sets $dist->status->uninstalled to the return value of this function. If you override this method, you should make sure to set this value. last one, you got this 🎀

---

and that's the whole page, bestie!! no cap, every option, every method, every status field, all of it. this one's from perl v5.40.1, dated 2025-03-01 — so yeah, she's current, she's fresh, she's serving 💖✨🦋 slay, go write your custom dist class, I believe in you 🫶👑