Publish your first CPAN module

in less than 5 minutes

Eric Johnson / @kablamo_

How to publish to CPAN

  1. Create a PAUSE.perl.org account
  2. Use Minilla to create a distribution (.tar.gz)
  3. Use Carton to manage dependencies for your code
  4. Use Minilla to upload your distribution (.tar.gz) to PAUSE

How to publish to CPAN

  1. Create a PAUSE.perl.org account
  2. Use Minilla to create a distribution (.tar.gz)
  3. Use Carton to manage dependencies for your code
  4. Use Minilla to upload your distribution (.tar.gz) to PAUSE

PAUSE

  • PAUSE is the Perl Authors Upload SErver
  • You need a PAUSE account to upload/manage CPAN modules
  • MetaCPAN.org uses PAUSE accounts for authentication
  • When you upload a module, you will upload it to PAUSE
  • After you upload a module to PAUSE, its indexed, and then distributed to CPAN mirrors

Create a PAUSE account

Go to pause.perl.org

  1. Click 'Create account'
  2. Do the things

Save your credentials in ~/.pause


user <YOUR-PAUSE-ID>
password <your-password>

This will be used by Minilla to upload your code to CPAN

How to publish to CPAN

  1. Create a PAUSE.perl.org account
  2. Use Minilla to create a distribution (.tar.gz)
  3. Use Carton to manage dependencies for your code
  4. Use Minilla to upload your distribution (.tar.gz) to PAUSE

Minilla

  • Minilla is a kiaju -- the first of several young Godzillas
  • A simple alternative to Dist::Zilla
  • Not extensible
  • Created by Tokuhirom

Create a new project with Minilla


cpanm Minilla
minil new Space::Cowboy

minil new

generated 9 boiler plate files


$ tree Space-Cowboy
.
├── Build.PL            # script to install Space::Cowboy
├── Changes             # changes for each release
├── cpanfile            # dependencies
├── lib
│   └── Space
│       └── Cowboy.pm
├── LICENSE
├── META.json           # meta data about the module for metacpan
├── minil.toml          # config file for minilla
├── README.md           # used by Github
└── t
    └── 00_compile.t   

3 directories, 9 files

How to publish to CPAN

  1. Create a PAUSE.perl.org account
  2. Use Minilla to create a distribution (.tar.gz)
  3. Use Carton to manage dependencies for your code
  4. Use Minilla to upload your distribution (.tar.gz) to PAUSE

Carton

  • Created by Miyagawa
  • Carton installs and tracks dependencies
  • Similar to bundler (ruby) or pip (python)
  • Installs dependencies to the './local' directory
  • You create a cpanfile to list your dependencies
  • Carton generates a cpanfile.snapshot which enables other developers to use the exact same deps

Install Carton


cpanm Carton

cpanfile example


requires Moo,     '0.2000';
requires Plack,   '== 0.9980';
requires Starman, '>= 0.2000';

on test => sub {
    requires 'Test::More';
};

on develop => sub {
    recommends 'Dist::Zilla'; 
};
  • You can specify minimum versions
  • You can pin a version

Using Carton


carton                       # installs dependencies to ./local
carton exec bin/space-cowboy # adds ./local to $PERL5LIB

Bash environment shortcuts


export PERL5LIB=./local/lib/perl5:./lib:$PERL5LIB
export PATH=./local/bin:$PATH

How to publish to CPAN

  1. Create a PAUSE.perl.org account
  2. Use Minilla to create a distribution (.tar.gz)
  3. Use Carton to manage dependencies for your code
  4. Use Minilla to upload your distribution (.tar.gz) to PAUSE

Write your code, then release


# hack
# hack
# hack
vi lib/Space/Cowboy.pm t/space-cowboy.t cpanfile
git commit -a

# release
carton exec minil release

minil release

...does the following awesome things

  • checks if you forgot to check in any files
  • runs your tests
  • runs extra tests
  • generates a README.md from your pod
  • generates a META.json file for MetaCPAN.org
  • generates a BUILD.pl file for MetaCPAN.org
  • bumps the version number
  • builds a distribution (tar.gz)
  • uploads your distribution (tar.gz) to CPAN using credentials from ~/.pause
  • tags your release in git
  • pushes your code and tags to github

Quick summary of everything in this talk

Quick summary: Setup

Install stuff


cpanm Carton
cpanm Minilla

Add your pause credentials to ~/.pause


user <YOUR-PAUSE-ID>
password <your-password>

Quick summary: First release


# create a new project with Minilla
minil new Space::Cowboy
cd Space-Cowboy

# write your code
vi lib/Space/Cowboy.pm t/space-cowboy.t

# manage your dependencies with Carton
vi cpanfile                       

# release
git commit -a
carton exec minil release

Quick summary: Followup releases


# hack, hack, hack
vi ...
git commit ...

# release
carton exec minil release

THE END

These slides are online