Wally Hartshorn has asked for the wisdom of the Perl Monks concerning the following question:

Does anyone have any recommendations for how to organize your Perl applications? I'm not talking about the Perl code -- I'm talking about the files themselves.

Let me give an example. We are a very small shop, just 2 Perl programmers within a programming staff of about 10. Most of our time is actually spent on non-programming activities (HTML "coding"). Time actually spent doing Perl is sporadic, but eagerly anticipated. Most of it is CGI stuff.

In the Beginning: One program, One file

Initially, we followed the beginners' road of procedural programs, with print statements writing out HTML tags. (We were at least lucky enough to start of with, though.) That meant any given program consisted of a single *.pl file, which was plopped down into the cgi-bin directory.

Enter the HTML template files

Later, we discovered the joys of HTML::Template. And there was much rejoicing! No more print statements banging out HTML tags. Life was good -- and slightly more complicated, because now, in addition to the *.pl file, we had some *.html files that contained the templates. No problem, we just created directories in cgi-bin for each program and placed the *.pl file and the accompanying *.html files in the appropriate subdirectories in cgi-bin.

And the config files

Then we discovered Config::IniFiles. Ah! No more editing of the *.pl file just to change someone's email address. Just create a *.ini file and put that in the directory with the *.pl file and the *.html files.

And the modules

Then we wrote our first module, to be used by multiple programs to do error reporting. Okay... well, that doesn't go in the cgi-bin directory, that gets installed as a Perl module. Okay, we'll call it something like OUR::Errors.

Now we've written our first program to use CGI::Application. Using that, you create just a very small *.pl file, with the bulk of the code in a module. Okay... well, then that means that the *.pl file, the *.html files, and the *.ini file go over in the cgi-bin directory, but the bulk of the actual code -- the module itself -- gets stored with the other Perl modules.

And the unit tests

Oh, and we've also taken our first stab at doing automated testing, so we've also got a file that should go... uh... somewhere.

Now store it all in CVS ... somewhere

Added to the mix is trying to figure out how to best use CVS to work with all of this. Previously, when we wanted to work on "project-x", we would just check out "project-x" and have all of the files there for us. After making the needed changes, implementing the updated program was a simple matter of copying our working directory into the appropriate cgi-bin directory. (Like I said, we're a very small shop.)

Now, however, things are going two different places, and I'm not sure how they should be organized for CVS.

CPAN to the rescue?

I have a feeling that ExtUtils::MakeMaker or Module::Build would somehow be a part of the solution. I've experimented with ExtUtils::MakeMaker for a while, and have figured out how to get it to "make test" and "make install". However, "make install" only installs the *.pm file -- it doesn't know to install the *.html, *.ini, and *.pl files into the appropriate cgi-bin directory, and the Makefile looks far too intimidating for me to figure out.

In addition, when I do a "cvs commit", CVS commits a whole bunch of directories in 'blib' that have no known function to me, as well as some files (e.g. 'pm_to_blib') that seem equally mysterious.

Mission: Incomprehensible

Most of the stuff that I've read about this generally talks just about Perl modules and getting them ready for CPAN. I haven't really seen anything that talks about all of the other stuff. Is there something obvious I'm missing? Do I need to RTFM a bit more on ExtUtils::MakeMaker or Module::Build?

So, given these files:

  • myprogram.ini
  • mytemplate.html

How would you organize this stuff? Should it all be in one CVS project, or should there be multiple CVS projects? Should most of it go in a subdirectory within cgi-bin? Or with the module? Or somewhere else entirely? When I do a "make install", how can I get everything to go where it should?

With just the 2 of us, the issue isn't critical at this point. However, we would like to "do the right thing" and make sure that we don't leave behind a maze of twisty little Perl files, all different, for those who will eventually follow us.

Wally Hartshorn

(Plug: Visit JavaJunkies, PerlMonks for Java)

Edited 2003-04-04 by Ovid