CPAN2DIST(1p)

📦
version 0.9916 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ CPAN2DIST 💅

okay bestie, so this is the manual page for cpan2dist from the User Contributed Perl Documentation — it's a Perl script, she's iconic, she makes packages, and we're gonna go through every single thing she does. no skimming, no skipping, we're doing the whole thing 🫶

🌸 NAME 🌸

cpan2dist — the CPANPLUS distribution creator 👑

🦋 DESCRIPTION 🦋

so basically, this script will create distributions of CPAN modules in the format you specify, and it grabs all their prerequisites too. once you've got those packages, you can install them with the matching package manager for whatever format you picked. slay.

also important: you can do this interactively from the default shell, CPANPLUS::Shell::Default. check out the CPANPLUS::Dist documentation, plus the docs for whichever format you chose, for any format-specific deets. iykyk 💖

⭐ USAGE ⭐

 Usage: cpan2dist [--format FMT] [OPTS] Mod::Name [Mod::Name, ...]
        cpan2dist [--format FMT] [OPTS] --modulelist /tmp/mods.list
        cpan2dist [--format FMT] [OPTS] --archive /tmp/dist [/tmp/dist2]

    Will create a distribution of type FMT of the modules
    specified on the command line, and all their prerequisites.

    Can also create a distribution of type FMT from a local
    archive and all of its prerequisites.

so yeah — it'll build a distribution of type FMT of all the modules you list on the command line, prerequisites included. and it can also build a distribution of type FMT from a local archive, plus everything that archive needs. 💅

🎀 Options 🎀

take no argument:

  • --help — shows you this help message. bestie behavior tbh.
  • --install — installs this package (and any prerequisites you built) after building it.
  • --skiptest — skips the tests. you can negate it with --noskiptest.
  • --force — forces the operation. you can negate it with --noforce.
  • --verbose — be verbose. you can negate it with --noverbose.
  • --keepsource — keeps the sources after building the distribution. you can negate it with --nokeepsource. heads up: may not be supported by all formats 🫠
  • --makefile — prefers Makefile.PL over Build.PL. you can negate it with --nomakefile. defaults to your config setting.
  • --buildprereq — builds packages for any prerequisites, even if they're already uptodate on your local system. you can negate it with --nobuildprereq. defaults to false.
  • --archive — says that all the modules you listed are actually archives.
  • --flushcache — updates CPANPLUS' cache before starting any operation.
  • --defaults — tells ExtUtils::MakeMaker and Module::Build to use default answers during the 'perl Makefile.PL' or 'perl Build.PL' calls, wherever possible.
  • --edit-metafile — lets you edit the distribution's metafile(s) before the distribution gets built. requires a configured editor.

take argument:

  • --format — the installer format to use (defaults to your config setting).
  • --ban — patterns of module names to skip during installation, case-insensitive (and yes, it affects prerequisites too). may be given multiple times.
  • --banlist — a file containing patterns that could be given to --ban. they get appended to the ban list built up by --ban. may be given multiple times.
  • --ignore — patterns of modules to exclude from the prereq list. super useful when a prereq listed by a CPAN module gets resolved some other way than from its corresponding CPAN package. (the match is done on both the module name and the package name of the package the module is in — case-insensitive 💅)
  • --ignorelist — a file containing patterns that may be given to --ignore. they get appended to the ban list built up by --ignore. may be given multiple times.
  • --modulelist — a file containing a list of modules that should be built. they get appended to the list of command line modules. may be given multiple times.
  • --logfile — a file to log all output to. by default, all output goes to the console.
  • --timeout — the allowed time for building a distribution before aborting. this is useful for terminating any build that hangs, or that happens to be interactive even though it was told not to be 🙈. defaults to 300 seconds. to turn it off, you can set it to 0.
  • --set-config — change any options as specified in your config, for this invocation only. see CPANPLUS::Config for a list of supported options.
  • --set-program — change any programs as specified in your config, for this invocation only. see CPANPLUS::Config for a list of supported programs.
  • --dist-opts — arbitrary options passed along to the chosen installer format's prepare()/create() routine. please see the documentation of the installer of your choice for the options it accepts.

builtin lists

  • --default-banlist — use our builtin banlist. works just like --ban and --banlist, but with pre-set lists. see the "Builtin Lists" section for details.
  • --default-ignorelist — use our builtin ignorelist. works just like --ignore and --ignorelist but with pre-set lists. see the "Builtin Lists" section for details.

💖 Examples 💖

### build a debian package of DBI and its prerequisites,
### don't bother running tests
cpan2dist --format CPANPLUS::Dist::Deb --buildprereq --skiptest DBI

### build a debian package of DBI and its prerequisites and install them
cpan2dist --format CPANPLUS::Dist::Deb --buildprereq --install DBI

### Build a package, whose format is determined by your config, of
### the local tarball, reloading cpanplus' indices first and using
### the tarballs Makefile.PL if it has one.
cpan2dist --makefile --flushcache --archive /path/to/Cwd-1.0.tgz

### build a package from Net::FTP, but don't build any packages or
### dependencies whose name match 'Foo', 'Bar' or any of the
### patterns mentioned in /tmp/ban
cpan2dist --ban Foo --ban Bar --banlist /tmp/ban Net::FTP

### build a package from Net::FTP, but ignore its listed dependency
### on IO::Socket, as it's shipped per default with the OS we're on
cpan2dist --ignore IO::Socket Net::FTP

### building all modules listed, plus their prerequisites
cpan2dist --ignorelist /tmp/modules.ignore --banlist /tmp/modules.ban
  --modulelist /tmp/modules.list --buildprereq --flushcache
  --makefile --defaults

### pass arbitrary options to the format's prepare()/create() routine
cpan2dist --dist-opts deb_version=3 --dist-opts prefix=corp

🌈 Built-In Filter Lists 🌈

some modules you'd just rather not package. some because they're part of core-perl and you don't want a new package. some because they won't build on your system. some because your package manager of choice already packages them for you. 🙃

there may be a myriad of reasons. you can use the --ignore and --ban options for this, but we also provide some built-in lists that catch common cases. use the built-in ones if you like, or supply your own if you need to. no cap.

🍓 Built-In Ignore List 🍓

you can use this list of regexes to ignore modules matching it, so they don't get listed as prerequisites of a package. particularly useful if they're bundled with core-perl anyway and they have known issues building. 😭

toggle it by supplying the --default-ignorelist option.

^IO$                    # Provided with core anyway
^Cwd$                   # Provided with core anyway
^File::Spec             # Provided with core anyway
^Config$                # Perl's own config, not shipped separately
^ExtUtils::MakeMaker$   # Shipped with perl, recent versions
                        # have bug 14721 (see rt.cpan.org)
^ExtUtils::Install$     # Part of of EU::MM, same reason

💀 Built-In Ban list 💀

you can use this list of regexes to disable building of these modules altogether. periodt.

toggle it by supplying the --default-banlist option.

^GD$                # Needs c libraries
^Berk.*DB           # DB packages require specific options & linking
^DBD::              # DBD drivers require database files/headers
^XML::              # XML modules usually require expat libraries
Apache              # These usually require apache libraries
SSL                 # These usually require SSL certificates & libs
Image::Magick       # Needs ImageMagick C libraries
Mail::ClamAV        # Needs ClamAV C Libraries
^Verilog            # Needs Verilog C Libraries
^Authen::PAM$       # Needs PAM C libraries & Headers

👑 SEE ALSO 👑

CPANPLUS::Dist, CPANPLUS::Module, CPANPLUS::Shell::Default, "cpanp"

🙈 BUG REPORTS 🙈

please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>. (yes, literally that string, bestie, i'm not touching it 💀)

💜 AUTHOR 💜

this module by Jos Boumans <kane@cpan.org>.

the CPAN++ interface (of which this module is a part of) is copyright (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. all rights reserved.

this library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie — this one's from perl v5.40.1, dated 2025-03-01 🦋 go build something gorgeous 💅✨

📦 where this page comes from