Setting up Perl under Apache

Question

I'm very disappointed with Apple over the very poor documentation and support for what is potentially an extremely valuable asset in the Mac OSX tool box i.e. being able to test Perl scripts locally using the Apache software included under OSX.
Because it's taken me 2 days to wade through the discussions here and find resources online I want to help others avoid my delays and post what I found. I would also like to comment that the unix community active on this list though so very helpful in many ways could resist scorning those who are entirely unfamiliar with terminal and the command line interface and try to condescend to explain in layman's terms what is essentially not that complex but is so shrouded in jargon, shorthand and arcana that it seems almost deliberately difficult to penetrate. I would ask Apple to please just post a simple 'how to' or if they see fit include this email in their FAQ's.
Thank you to the many who have posted on this subject on this list and I apologize if I have used your suggestions without personal credit. I am with this document merely giving back something of what I have taken out of this useful resource. Please feel free to offer amendments to any obvious mistakes or misunderstandings I am a novice at Unix attempting to help other novices because (Ibelieve) I still speak the same language.
This method is for starting Perl under Tiger OS 10.4x (may work for Panther or earlier I haven't tested it) on a desktop machine, not a server.
To start Apache under OSX
1) To turn on Apache just go to System prefs and turn on 'personal web sharing' under the 'sharing' control panel. Note the IP address that appears under the 'Select a service...' window as this is the IP address of your local web address or 'yourlocalhostaddress' (referenced below). This is what you type into the browser to view your pages locally.
2) It seems intuitive to place your web site in the user/yourusername/sites folder on your hard drive. While this is acceptable for basic web sites it seems to make configuration harder for Perl. I could not access a cgi-bin nor find documentation that satisfactorily informed me how to access a cgi-bin created in this location. That doesn't mean it's not possible just that I don't know how to do it.
Apple have created another folder with a pre-configured cgi folder at the following location;
yourharddrive/library/WebServer
Place your website in the 'Documents' folder and your Perl scripts in the 'CGI_Executables' folder. It's unnecessarily confusing to me that Apple have essentially renamed the cgi-bin to 'CGI_Executables' and the 'html' folder to 'documents' as they would be found under the Apache installation that I'm familiar with but that seems to be what's happened here.
To start Perl support in Apache under OSX
3) If you dont already have one it's useful to have an ultra simple Perl script on hand to test whether your configuration is working. More complex script such as formmail.pl may have additional settings that are confusing as to whether it's the file or the configuration that is causing a script error. To create a simple script copy and paste the following code;
#!/usr/bin/perl
print "Content-type: text/html\r\n\r\n";
print "Hello, World.";
into a new, empty document in a text editor and save it as 'first.pl' in your 'CGI_Executables' folder. You can open it in Safari using the following address;
http://yourlocalhostaddress/cgi-bin/first.pl
4) If you test your script now a call to the Perl script will merely open the page with the script as text and will not run it. This is because Apple supplies their copy of Apache with Perl disabled, it's necessary to edit a file called 'httpd.conf' in order to turn Perl on. The recommended way to turn this file on is using the terminal program but the file can also be located through the mac OS although it is partially hidden, it can be edited in a text editor that is suitable for coding such as BBEdit.
The best online documentation I found about how to edit the httpd.conf file using terminal is here;
http://www.macdevcenter.com/pub/a/mac/2001/12/14/apache_two.html?page=1
However I'm not sure that he is accurate (though I hesitate to disagree with the expert) my experience was significantly different see below(*).
Terminal has useful testing features but the command line is obscure and daunting to the novice. In addition UNIX programmers seem to delight in scaring away the cautious with silly, portentous warnings about privacy etc. This document is very sensitive to the way it's edited, however your computer will not blow up if you get it wrong and there is a back-up default version stored in the same folder so if you do screw up you can restore the defaults and start again.
If you wish to do it without going through the terminal the 'httpd.conf' file is located here;
/private/etc/httpd/httpd.conf
where private is an invisible folder so you cant navigate to it directly via the Mac OS. However if you copy and paste the above address into Safari's address bar the folder window will come up revealing the document (this is an undocumented feature and I discovered it by accident so use at your own risk). Alternatively you can navigate to it using an FTP program such as Transmit when you have 'show hidden files' turned on in the preferences. Transmit is a very useful tool because it also allows you to view and change the permissions (or CHMOD) of the files you view in the same manner as you would on a remote server. Something which you cannot do using the 'Get Info' on the Mac OS
You'll notice that there is an httpd.conf and an httpd.conf.default file. The latter is your backup so dont be overly scared of editing the first file, proceed with caution but not with trembling.
Once you have the program open in BBEdit (or your editor of choice) uncomment the following lines by deleting the # symbol;
#LoadModule perl_module libexec/httpd/libperl.so
#AddModule mod_perl.c
The quickest way to find these lines is to do a find on 'Perl' (something you cant do in Terminal). Dont change anything else just save and close, you will be required to enter your administrator password at this point.
(*)Please note;
Kevin Hemenway in the macdevcenter.com article says to uncomment the following lines;
#LoadModule cgi_module libexec/httpd/mod_cgi.so
#AddModule mod_cgi.c
And makes no mention of the lines ending in perl rather than CGI. His article is from 12/14/2001 so it may be out of date. In my httpd.conf file the lines ending 'cgi' were already uncommented but the lines ending 'perl' were commented out. I uncommented the lines ending 'perl' and now in my version both (cgi and perl) are uncommented and active. There are security implications to uncommenting any lines so I may have opened a security loophole that I'm not aware of however until I uncommented the 'perl' lines my scripts did not work. I would be grateful for an explanation of the implications from any Unix expert reading this.
5) The last thing you need to do is restart Apache so that it can load the new config file. To do this stop web sharing in the preferences pane and then restart it.
If you test your simple Perl script 'first.pl' now it should load and show the text "Hello World" in a browser window.
6) if you wish to load a more complex script and find that they will still not work, at least you know that Perl is working. You can check the error logs by opening the terminal and at the prompt (yourusername$) type;
tail /var/log/httpd/error_log
This enables you to trace the whether a permissions, configuration or other error has occurred.
WARNING;
The above is a distillation of my frustrating experience over the last 2 days, it details how I finally got it to work. With everything in scripting I find that I repeat the same method multiple times, convinced each time that I have it right and all of a sudden it works where it didn't work before. This always leaves me unsure that I may have inadvertently done some thing right (as logically I was obviously inadvertently doing something wrong before) that is not documented here. I offer this method as the product of my experience, because I hope it is helpful and because I have the confidence that there is a way to back out of it using the default config file. Despite the above use at your own risk.
G5 Dual 2.5Ghz + Pbook G4 867Mhz + 15GB iPod   Mac OS X (10.4.3)  

Answer 1

That sounds like a very good useful tip. I would hold on to it in your own computer's repository as well and post sections of it whenever you see someone needing help with it until you are able to add it to the contributions section of the User Tip forum here:
http://discussions.apple.com/category.jspa?categoryID=103