[wiki:howto <- Back to the HOWTO section]

= How to create portfiles for CPAN Perl modules =

 * Audience: Perl users
 * Requires additional Perl modules (available as MacPorts perl ports: see step [#Step4:Getcpan2port Get cpan2port])
 * I assume you are building your modules in a standard location, so commands that will write files in standard locations are preceded with 'sudo'.
 *   If you are building file in directories you own, leave off the 'sudo' when using these commands.



== Introduction ==

When you find you need a Perl modules from CPAN that does not yet have a MacPorts port, cpan2port can help you create a port file.

=== Step 1: '''Set up cpan client''' ===

You must have a properly configured cpan client for cpan2port to work.
You can either step through the questions, or let it auto-configure.
{{{
$ sudo cpan
CPAN is the world-wide archive of perl resources. It consists of about
[...]
Would you like me to configure as much as possible automatically? [yes] ''yes''
[...]
cpan shell -- CPAN exploration and modules installation (v1.9301)
ReadLine support available (maybe install Bundle::CPAN or Bundle::CPANxxl?)

cpan[1]> ^D
}}}
=== Step 2: '''Find the CPAN package name''' ===
{{{
$ perl -MCPAN -e shell
cpan[1]> m Date::Parse
Module id = Date::Parse
   DESCRIPTION  ASCII Date parser using regexp's
   CPAN_USERID  GBARR (Graham Barr <gbarr@pobox.com>)
   CPAN_VERSION 2.30
   **CPAN_FILE    G/GB/GBARR/TimeDate-1.20.tar.gz**
   DSLIP_STATUS Rdpf? (released,developer,perl,functions,)
   MANPAGE      Date::Parse - Parse date strings into time values
   INST_FILE    /opt/local/lib/perl5/vendor_perl/5.8.9/Date/Parse.pm
   INST_VERSION 2.27
}}}

So you want the TimeDate module.

=== Step 3: '''Check that port is not available''' ===

Perl modules have names of the form p5-modulename.

{{{
$ port search p5-timedate
}}}

This particular port actually is available, but we'll pretend it isn't.

=== Step 4: '''Read up on local port repositories''' ===

[http://guide.macports.org/chunked/development.local-repositories.html]

If you're new to creating ports, reading the guide will help you enter your ~/macports directory in /opt/local/etc/macports/source.conf so port can find your personal ports directory when you do 'port search', or 'port install', etc.

=== Step 5: '''Get cpan2port ===
Install using macports (will automatically install prerequisite Perl modules: p5-list-moreutils, p5-cpan-meta, p5-module-depends, p5-cpan-meta-yaml):
{{{
$ sudo port install cpan2port
}}}

Or, from a system without macports:
{{{
$ mkdir ~/macports
$ cd ~/macports
$ curl -O https://raw.githubusercontent.com/macports/macports-contrib/master/cpan2port/cpan2port
$ chmod u+x cpan2port
}}}
Then install the Perl modules (from e.g. CPAN or package manager of choice): [https://metacpan.org/release/List-MoreUtils List::MoreUtils], [https://metacpan.org/release/CPAN-Meta CPAN::Meta], [https://metacpan.org/release/Module-Depends Module::Depends], [https://metacpan.org/release/CPAN-Meta-YAML CPAN::Meta::YAML]

=== Step 6: '''Create the port file''' ===
{{{
$ mkdir ~/macports
$ cd ~/macports
$ cpan2port -t Date::Parse
[...]
TimeDate-1.20/
TimeDate-1.20/ChangeLog
[...]
trying to find dist in /Users/dtls/.cpan/build/TimeDate-1.20*
---
md5: 7da7452bce4c684e4238e6d09b390200
rmd160: 513094a2d2fb3678c1ad893abc28c94d344ec7b8
sha1: 6394cd243e05c3c2073fa73348a4ad90d8d5963e
creating perl/p5-timedate/Portfile
}}}

=== Step 7: '''Build the port''' ===
First you can review the portfile:
{{{
$ cd ~/macports/perl/p5-timedate
$ cat Portfile
}}}
{{{
# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf8:ft=tcl:et:sw=4:ts=4:sts=4
# $Id$

PortSystem      1.0
PortGroup       perl5 1.0

perl5.setup     TimeDate 1.20
platforms       darwin
maintainers     cpan2port
description     ASCII Date parser using regexp's
extract.suffix  .tar.gz
master_sites    http://search.cpan.org/CPAN/authors/id/G/GB/GBARR
checksums sha1 6394cd243e05c3c2073fa73348a4ad90d8d5963e md5 7da7452bce4c684e4238e6d09b390200 rmd160 513094a2d2fb3678c1ad893abc28c94d344ec7b8
}}}

Then build it:
   # Note: make sure you're in the Portfile directory for the port you want to build. In our case ~/macports/perl/p5-timedate.

{{{
$ sudo port build
Warning: MacPorts running without privileges. You may be unable to complete certain actions (e.g. install).
--->  Computing dependencies for p5-timedate
--->  Fetching p5-timedate
--->  Attempting to fetch TimeDate-1.20.tar.gz from http://distfiles.macports.org/perl5
--->  Attempting to fetch TimeDate-1.20.tar.gz from http://lil.fr.distfiles.macports.org/perl5
--->  Attempting to fetch TimeDate-1.20.tar.gz from http://aarnet.au.distfiles.macports.org/pub/macports/mpdistfiles/perl5
--->  Attempting to fetch TimeDate-1.20.tar.gz from http://search.cpan.org/CPAN/authors/id/G/GB/GBARR
--->  Verifying checksum(s) for p5-timedate
--->  Extracting p5-timedate
--->  Configuring p5-timedate
--->  Building p5-timedate
}}}

If you get an error similar to:
{{{ Error: p5-timedate depends on p5.28-timedate }}}
when trying to build, try the following command
{{{ sudo port build subport=p5.28-timedate }}}

=== Step 8: '''Fix the Portfile''' ===

The Portfile as generated is in rough form and not ready for submission as a new or updated port. Please at least check and update the following in the Portfile:

  * Check if the port compiles any files or is simply straight perl code. If the latter, then uncomment the following line and delete the comment above it. Otherwise delete the lines entirely. 
{{{
# Uncomment this line if you know there will be no arch-specific code:
#supported_archs     noarch
}}}

  * Determine and add the correct license. There is a commented license line that is common to many perl ports. 
{{{
#license             {Artistic-1 GPL}
}}}

  * Dependencies need to be put into an if block so that they only appear in the sub-ports, not the stub p5 port. See below as an example.
{{{
if {${perl5.major} != ""} {
    depends_lib-append  port:p${perl5.major}-digest-md5 \
                        port:p${perl5.major}-io-compress
}
}}}

  * Check the appropriate perl versions supported by the port. At the time of writing, 5.26 is the current and only version in use.
{{{
perl5.branches      5.26
}}}


If you make changes to the Portfile, remember to re-build it:
{{{
$ cd ~/macports/perl/p5-timedate
$ sudo port build
}}}

=== Step 9: '''Update your PortIndex Files''' ===

Before you can install your new port, you will need to create/update the PortIndex files in your macports directory.

{{{
$ cd ~/macports
$ portindex
}}}
----

[wiki:howto <- Back to the HOWTO section]