I am writing a perl program that I want to share with others, eventually via cpan. it's getting to the point where I should start thinking about this on a bigger scale.
a decade ago, I used the h2xs package maker once. is this still the most recommended way to get started? there used to be a couple of alternatives. because I am starting from scratch with very little recollection, anything simple will do at this point.
I need to read a few long text files (not perl modules) for configuration. where do I put them and how do I access them, no matter where the module is installed? (FindBin?) _DATA_ is inconvenient.
I need to provide an executable (linux and osx). can putting an executable into the user's path be part of the module installation? (how?)
I would like to be able to continue developing it, run it for test purposes, have a new version, repack it, and reupload it easily.
before uploading to cpan, can I share a cpan bundle for easy local installation to downloaders and testers?
# cpan < mybundle.cpanbundle
advice appreciated.
regards,
/iaw
If anything I say conflicts with Andy Lester, listen to him instead. He knows more than I ever will.
Module::Starter is a good, simple way to generate module scaffolding. My take is it's been the default for this sort of thing for a few years now.
For configuration/support files, I think you probably want File::ShareDir. Might be worth considering Data::Section if it's just a matter of needing multiple __DATA__ sections though.
You can certainly put scripts in the bin subdirectory of your distribution, the build tool will put it in the right place at install time.
A build tool will take care of the work-flow you describe.
Bundles are something different. You make a distribution and share the tarball/archive.
If you set up PERL5LIB appropriately, then repeat make test, make install, make dist to your heart's content. For development/sharing purposes a lot of projects do their work on github or similar - makes it easy to share. They have private accounts for business purposes too. Very useful if you want to rewind and see where/when a problem was introduced.
If you get a copy of cpanm (simple to install, fairly lightweight) then it can install from a tar.gz file or even direct from a git repository. You can also tell it to install to a local dir (local::lib compatible - another utility that's very useful).
Hopefully that's reasonably up-to-date as of 2014. You may see Dist::Zilla mentioned for module development. My understanding is that it's most useful for those with a large family of CPAN distributions to manage. Oh - if you (or other readers) aren't aware of them, do check out autodie and Try::Tiny around errors and exceptions, Moose (for a full-featured object-oriented framework) and Moo (for a smaller lightweight version).
I think that advice is all reasonably non-controversial. I find cpanm to be much more pleasant than the "full" cpan client, and Moo seems pretty popular nowadays too.
Take a look at Module::Starter and its much more capable (and complex) successor Dist::Zilla.
Whatever you do, don't use h2xs. Module::Starter was created specifically because h2xs was such an inappropriate tool for creating distributions.
Related
I'm getting ready to set up a full CPAN mirror for internal use at my company. However, we have several internal Module::Build based distributions that I'd like to make available to people from this mirror. These distributions should ONLY be available from our mirror; they are internal libraries only. Essentially, once people have set up their CPAN config file to load "cpan.mycompany.com' mirror, I'd like them to be able to do a
cpan install MyCompany::Bundle
cpan install MyCompany::Other::Module
On their command line to install any number of internal, custom module distributions. Ideally, as versions of these module distributions are incremented, all of those versions would be indexed by our internal CPAN mirror and made available, just as as previous versions of CPAN modules are made available.
After the initial question, I was able to come up with some other possibilities.
There's CPAN::Inject, but it looks like I can't use it to get a cpan install My::Module syntax.
Then there's MyCPAN::App::DPAN, which also looks interesting, and almost looks like what I need. Does anyone have experience with this tool?
Another one I just came across was CPAN::Site. This seems to also be able to set up a custom CPAN distribution. Any thoughts on this tool?
If you're using CPAN::Mini to create your mirror, then you use CPAN::Mini::Inject to add your own modules to it.
To do this with a full CPAN mirror, CPAN::Site covers this nicely. It lets you make a mirror, and then inject your own libraries right into it, complete with tools to help you manage setting it up and keeping it up to date.
I would like to second the suggestion for CPAN::Site - the author is responsive and will gladly apply fixes if you ask or file a bug report on the CPAN RT.
I've been using it recently to make a "micro-cpan" containing only what a particular application needs and nothing else, along with cpanminus to make installation in any environment dead-simple. However, don't ask me for my solution - miyagawa++ was at YAPC::NA this year and showed off "Carton" which does all that and more, way better than my hacky stuff.
CPAN::Mini::Inject is perhaps a bit too "low-level" in that it requires that you specify a whole lot of information about each dist up-front before injecting into the minicpan - I feel that just about all of that should be auto-detected by analyzing the dist, for example by using CPAN::ParseDistribution.
MyCPAN::App::DPAN is actually quite cool, but has a bit of a learning curve and may not be the right tool for the job. I've also found it has a tendency to choke on some badly-formed dists and detecting that involves treawling through the logs (as far as I can tell - maybe there's a better way to do it) However, I'd highly suggest checking it out.
If you're still interested in MyCPAN::App::DPAN, I've just posted how I use it to create a mini CPAN-like directory structure, in (one of) the answers to this question:
Internal CPAN - what module
(I don't know if it's OK to link to my own answer here. Let me know if it isn't.)
I've got a collection of Perl scripts and a couple XML data files that they depend on which I'd like to distribute. Currently, I've got a shell script which copies bin/* and share/* to a target installation tree. It seems a little clunky, so I'd like to go with something like the standard CPAN way of packaging Perl.
Does is make sense to bundle what I've got in a CPAN-style package? I suspect there is nothing wrong with it, but every tutorial I've looked at thinks that lib/Blah.pm is an essential file in any package - I don't even have a lib/ directory, let alone any .pm files.
Is there a standard solution for packaging a collection of Perl scripts, along with some data in a share/ directory?
Distributions don't care about modules. Most of the tools are set up to handle modules by default because that's the common case, but you can really distribute anything as long as you provide the logic to tell the build files what to do with whatever files that you provide.
ExtUtils::Makemaker is difficult to use for this sort of thing, but Module::Build (despite the word "Module") makes it much easier. However, you have to know a bit about custom Module::Build classes so you can override the default behavior that you don't want.
If you are talking about standalone scripts, you can look at my scriptdist distribution, or the Dr. Dobbs article I wrote about it. It won't handle the share/ portion for you, but it's not too hard to add.
I have read, at various times, both the documentation and a number of blog posts on Dist::Zilla. I have never felt confidence in my understanding of it.
In response to another question, #Ether raised the possibility of converting Crypt-SSLeay to use Dist::Zilla.
So, where can I find a concise guide showing me how to convert an existing CPAN module to use Dist::Zilla? Does the question even make sense?
Update:
The Makefile.PL for Crypt-SSLeay does a lot of work (a lot of it seems unnecessary and I am trying to prune it) to find platform specific include and lib directories, to deduce the version of OpenSSL on the machine where it is being installed. How can I include that functionality if I use Dist::Zilla?
The Dist::Zilla Choose Your Own Tutorial has a page on Converting a Dist to Dist::Zilla. One thing it doesn't mention there is my VersionFromModule plugin, which is useful if you want to replicate the way many people use MakeMaker, with the distribution taking its version number from the main module. (Many people use dzil the other way, with the version in dist.ini and a plugin to stick it into the module, but either way works.)
If I need a more complex Makefile.PL than the one dzil generates, I switch to Module::Build and use my ModuleBuild::Custom plugin, which lets me write my own Build.PL and have dzil drop in metadata like the prerequisites.
The MakeMaker::Awesome plugin lets you do something similar with Makefile.PL, but it wasn't quite what I wanted. Instead, I wrote a MakeMaker::Custom plugin that works much like my ModuleBuild::Custom plugin. The big advantage of
MakeMaker::Custom over MakeMaker::Awesome is that it makes it possible to build your dist for testing purposes without having to do dzil build. For an XS module that has to be rebuilt after every minor change, this is a big win.
These are the sites I have found the most helpful so far, as I'm in the middle of converting a CPAN distribution I comaintain to use it, as a learning exercise. I'm not there yet, but I haven't hit any super tricky bits so far!
The official Dist::Zilla site's Choose your own tutorial's guide to Converting an existing distribution
CPAN Dist::Zilla::Tutorial
Dave Golden's Why I'm using Dist::Zilla
Also, the #toolchain and #distzilla channels on irc.perl.org are full of helpful people, including the authors for Dist::Zilla and other related tools.
I started using Dist::Zilla several months ago. However, at YAPC::NA someone mentioned that they use ShipIt instead. Then today I noticed a .shipit file in miyagawa's cpanminus directory on github, so I decided to look into it some more...
My initial impression is that ShipIt has a subset of what is available with Dist::Zilla, but I don't want to jump to conclusions. So, for those who have had experience with both, what are the strengths/weaknesses of ShipIt vs Dist::Zilla?
crossposted at perlmonks
I'm the author of Dist::Zilla.
I evaluated ShipIt pretty extensively before choosing to go ahead and write Dist::Zilla, and initially they covered almost exactly the same problem space: doing all the boring grunt work of building and uploading a CPAN distribution. All of the features that Dist::Zilla now has beyond ShipIt are later additions, more or less.
If you only need the features of ShipIt, I still advise you to strongly consider Dist::Zilla, for one very simple reason: hackability. If I had been able to not write something new, I would've used ShipIt, but I found it to be underdocumented and difficult to extend. Its plugins were not generic enough and the core behavior made too many assumptions about how you'd like to work.
Dist::Zilla was inspired specifically by this problem: it turned everything into a plugin, and every plugin was given a very, very small interface so that its assumptions would be forcibly limited.
One benefit of ShipIt over Dist::Zilla is that ShipIt has (to the best of my knowledge) no plugins that will alter the way you actually write your code. This means your documentation will still look the same, you will still have a Makefile.PL, and so on. Some hackers don't like that so many DZ-based dists fundamentally change the assumptions of how to test and build CPAN code from its source repository. ShipIt will never change that.
It's possible to avoid using any such plugins with Dist::Zilla, but in general my experience is that people do use them, almost always, in one form or another.
As far as I can tell, my initial impressions were correct.
ShipIt provides functionality for releasing distributions:
keeping track of version numbers
integrating with version control
uploading to CPAN
displaying the changelog file in an editor so that you can edit it before release.
Dist::Zilla, by default, provides the ability to upload distributions to CPAN with a single command (i.e. dzil release). Dist::Zilla also has functionality for creating new distributions (i.e. dzil new My::New::Module). It also automatically generates so many of the files that I used to have to maintain by hand.
Using plugins, Dist::Zilla seems able to provide most, if not all, of the functionality available with ShipIt. It is also relatively easy to add brand new features using plugins.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
What's the best framework for writing modules -- ExtUtils::MakeMaker (h2xs) or Module::Build?
NOTE This advice is out of date. Module::Build has been removed from the Perl core but lives on as a CPAN module. The pros and cons still stand, and my opinions about MakeMaker still stand.
As the former maintainer of ExtUtils::MakeMaker, I like to recommend Module::Build because MakeMaker is a horror show. Module::Build is so much better put together. But those aren't your concerns and I'll present my "least hassle for you" answer.
Executive Summary:
Because Module::Build support is not 100% in place through all of Perl, start with MakeMaker. If you want to do any customization at all, switch to Module::Build. Since their basic layout, options and interface are almost identical this will be painless. As seductive as it looks, avoid Module::Install.
Fortunately, Module::Build can emulate MakeMaker which helps some, but doesn't help if you're going to do any customization. See Module::Build::Compat.
For CPAN releases using Module::Build is fine. There's enough Module::Build stuff on CPAN now that everyone's dealt with getting it bootstrapped already.
Finally, the new configure_requires option lets CPAN shells know to install Module::Build before they can start building the module. Unfortunately only the latest CPAN shells know about configure_requires.
Oh, whatever you do don't use h2xs (unless you're writing XS code... and even then think about it).
MakeMaker Pros:
Comes with Perl and used by the Perl core (therefore it is actively
maintained and will remain so forever)
Everything knows what to do with a Makefile.PL.
Most module authoring documentation will cover MakeMaker.
Uses make (those who know make can debug and patch the build
process)
MakeMaker Cons:
Requires make (think Windows)
Difficult to customize
Even harder to customize and make cross platform
Difficult to debug when something goes wrong (unless you understand make)
Module::Build Pros:
Easier to customize/subclass
Pure Perl
Easier to debug (it's Perl)
Can emulate MakeMaker in several ways
The CPAN shell will install Module::Build for you
Module::Build Cons:
The Module::Build maintainers (and indeed all of the Perl Toolchain Gang) hate it
Older versions of CPAN clients (including CPANPLUS) don't know anything about Module::Build.
Module::Install Pros:
Slick interface
Bundles itself, you have a known version
Everything knows how to deal with a Makefile.PL
Module::Install Cons:
Requires make
Always uses bundled version, vulnerable to external breakage
Difficult to customize outside its interface
Mucks with the guts of MakeMaker so a new MakeMaker release will eventually break it.
Does not know how to generate a META file using the v2 meta-spec
(increasingly a problem with newer tools)
There are two questions here.
First, never use h2xs. It's old outdated nastiness, though I suppose if you're actually trying to turn a header file into XS code, it might be useful (never done that myself).
2011 update: I strongly recommend taking a look at Dist::Zilla, especially if you think you'll be maintaining more than one module.
For creating a new module, use Module::Starter. It works great, and has some nice plugins for customizing the output.
Second, you're asking what build system you should use. The three contenders are ExtUtils::MakeMaker (EUMM), Module::Build (MB), and Module::Install (MI).
EUMM is a horrid nasty piece of work, but it works, and if you're not customizing your build process at all, works just fine.
MB is the new kid, and it has its detractors. It's big plus is that if you want to heavily customize your install and build process, it's quite possible to do this sanely (and in a cross-platform manner) using MB. It's really not possible using EUMM.
Finally, MI is basically a declarative wrapper on top of EUMM. It also packages itself along with your distro, in an attempt to work around problems with users trying to install modules with old toolchain modules. The downside of the "package self" trick is that if there's a bug in MI itself, you have to re-release all your modules just to fix it.
As far as customization goes, there are some plugins for MI, but if you want to go beyond them you'll be back at the problem of dealing with Makefiles and build tools across a dozen+ platforms, so it really isn't going to help you too much in that realm.
I just uploaded Distribution::Cooker to CPAN. It's what I use to make new distributions. The nice thing about it is that your distributions can be whatever you like: you're just cooking some templates. I don't care if anyone uses it. For me it's simple, low tech, and doesn't cause extra problems.
You might start with something like Module::Starter to make your starter templates then add your own boilerplate and favorite way of doing things. You choose not only whatever you want in each file, but which files show up in the distro. As you figure out how you like to do things, you simply update your own templates.
As for Makemaker and Module::Build, the future is Module::Build. It's only us old guys using Makemaker anymore. :) There are ways to use both (or pretend to use both) at the same time. Look at the Module::Build, Module::Build::Compat, and Module::Install docs. Module::Build was kicked out of Perl's Standard Library and it's future is uncertain. It's back to Makemaker as a build system.
Although this is a bit of a cop-out answer, try using each just to get a little experience with each.
You also might want to look at Dist-Zilla which is a new author-only tool to create distributions. Because it just helps build the distribution, it doesn't ship with your code or do any installation, it can do a lot of powerful stuff.
The only trouble with compatibility regarding Module::Build is when a user tries to install modules without updating their CPAN client (CPAN.pm or CPANPLUS.pm) If they are installing your module from the CPAN, they can just as easily upgrade their client from the same mirror.
If you don't want to do anything complicated in your build process, sure: use EUMM. But if you have a build problem on a different target platform, you might end up in the Makefile, which is different on every variation of make.
Module::Build gives you lots of features (anything you can think of if you extend it) and is all perl so you never end up debugging a makefile. Module::Install gives you features, but you have to bundle it and everything ends up running through 'make' in the end.
I also recommend Module::Build and Module::Starter (with the TT2 plugin).
Module::Build is better by any means, but it is less widely supported than ExtUtils::MakeMaker (more specifically, older versions of Perl don't support it out of the box). It depends on your needs.
Personally, I recommend Module::Install, as do a lot of folks I know - the likes of the Catalyst and Moose folks also use it.
Here's a little clarification of the direction I hoped the responses would take:
pros/cons of various of frameworks
compatibility/install base of frameworks
suitability for internal (local) vs. external (CPAN) releases
not bare "use X" answers
Dave's answer has some good pro/con info. Leon's answer alludes to compatibility but isn't explicit. As brian d foy mentioned, only the old hats use EUMM, but I'm not convinced that MB is a good framework for things destined for CPAN due to it not being part of the core until 5.9.
There are pros and cons to both. These days I use and recommend Module::Build and Module::Starter.
EU::MM still seems to be the most widely supported and popular one, but Module::Build is catching up. Also, check out Module::Starter for a module that will help you get started.