• MacPerl Flavors
• System Requirements
• Installing The Standalone Application
• Examine The Results
• A Walk Through The Menus
• On-line Help - Installing Internet Config
• A New Menu
• Running A Script
• Check The Preferences

These notes describe the installation of MacPerl and provide a brief "get acquainted" overview. If you already have a working copy of MacPerl on your disk, you may want to skip this material. Or, you may wish to read the sections on menus and preferences, in case you might see something new.

MacPerl Flavors

There are two flavors of MacPerl - the standalone application (app), which works similarly to most other Macintosh programs, and the MPW tool. The MPW tool is only useful if you also have a copy of MPW, Apple's Macintosh Programmer's Workbench. MPW is a complete Macintosh programming environment, consisting of a shell (command line interpreter) and various tools.

Although MPW is somewhat more readily available than it once was, it is not in widespread use except among Macintosh software developers. Thus, we do not expect that many readers of this book will be MPW users. If you do not plan to use MPW, you may wish to skip ahead to the next section, System Requirements.

If you plan to use Perl with MPW, be sure to follow the instructions below to install the standalone app. The installation script for the MacPerl MPW tool requires that the MacPerl application package be installed first!

The examples in this note were written (and tested) using the standalone app. In most cases, this will make little difference. Occasionally, MPW users may have to make slight adjustments to our examples in order to make them work under MPW.

Complete instructions for installing the MacPerl MPW tool, as well as special features pertaining to the tool, are described in "MacPerl: Power and Ease" (Vicki Brown and Chris Nandor, PTF, 1998, ISBN 1-881957-32-2). The book does not, however, provide detailed information about using the MPW environment. If you are not already familiar with MPW, we suggest that you familiarize yourself with MPW before you attempt to install or use the MacPerl MPW tool.

If you are familiar with MPW, but have never used Perl, we suggest that you install only the standalone app at first. After you have become comfortable with Perl, you can install the MacPerl tool under MPW.

System Requirements

MacPerl requires that your Macintosh be running Mac OS System 7 or later. Be sure you have at least 4 MB of memory available, more if you wish to run complex scripts or work with large amounts of data.

MacPerl can be installed in any of three ways. The Easy Install option installs an application most suited to your system: either Motorola 68K-based Macintoshes (the Mac II, early Powerbooks, the Centrus or Quadra series, etc.) or PowerPC systems (Power Macintosh, later Powerbooks, and Performa systems with 4-digit model numbers: 7500, 2300, 6400, ...). Alternatively, you may wish to install a "fat" version of MacPerl, which will run on any Macintosh model. (To do this, you will need to perform a Custom installation).

If you are installing MacPerl on a 68K-based Macintosh, however, the default installation may not be sufficient for your needs. The standard, or "small" 68K MacPerl has a "minimal" set of modules linked in statically; these are approximately the modules whose functionality has always been present in previous versions of MacPerl. These modules are: DB_File, DynaLoader, Fcntl, IO, MacPerl, NDBM_File, Opcode, Posix, and Socket.

Two alternative versions of the MacPerl application are also available for 68K Macintoshes. "Big MacPerl" has additionally linked in the GD module and all Mac Toolbox modules. Dynamic 68K or CFM68K, includes the same modules as "small", but is also able to load arbitrary modules dynamically.

Installing The Standalone Application

If you have downloaded a recent copy of the MacPerl application from one of the archive sites on the Internet, the file will most likely be compressed and encoded, usually with StuffIt (from Aladdin Systems) and BinHex.

In this case, you will need to decode and uncompress the archive before continuing. StuffIt Expander, an expansion utility from Aladdin, is freely available from many Macintosh archive sites or from Aladdin Systems at www.aladdinsys.com.

If you are installing MacPerl from the PTF MacPerl CD-ROM, you won't need to uncompress or decode an archive. (We have supplied the MacPerl Installer as a ready-to-run application.)

Once you have an unpacked the MacPerl Installer, life gets pretty easy. All you need to do is launch the Installer application, review the instructions for any important last-minute notes, select the installation location, and click Install. The Installer will install everything you need to use MacPerl, including examples, all libraries, documentation, and the "standard" MacPerl application.

If you wish to install one of the alternative (Big or CFM68K) standalone versions of MacPerl, or you wish to install the MacPerl MPW tool, be sure to complete the standard installation first. The alternative distributions contain only the alternative application (or tool) and a small number of additional files.

You should install distributions as suggested in the figure below, reading from bottom to top. That is, to get the big MPW tool, you should first install the standard application (appl), then the standard MPW tool distribution, then the bigtool distribution.

All distributions are available on the PTF MacPerl CD-ROM. Alternatively, they can be downloaded from any of the MacPerl archive sites.

Steps to Install the MacPerl standalone app

1. Double-click the Installer application to start the installation. Be sure to review the instructions in the initial screen for any important last-minute notes. Print or save these notes, then click Continue.

   

2. If you wish to install a fat binary, be sure to select Custom Install from the popup menu; otherwise, select Easy Install as shown. Choose the volume and folder where you wish to install MacPerl, then click Install.

   

3. The Installer will install everything you need to use MacPerl.

   

4. When the Installer completes successfully, choose Quit. You do not need to restart your Macintosh.

   If you have a 68K-based Macintosh and desire to do so, you may install the Big MacPerl application (...bigappl) or the CFM68K MacPerl application (...appl_cfm68K) at this time. Simply double-click the appropriate Installer and follow the instructions, making sure to install onto the same disk where you installed the standard (small) MacPerl application.

Examine The Results

The Installer installs two new folders in the location you chose. The first of these, MacPerl f, contains the MacPerl distribution, including the application, documentation, and libraries.

You can safely ignore most of the files and folders for now. There are, however, several items you should recognize and understand, as they will be useful to you shortly. Examine the contents of the MacPerl f folder.

• The MacPerl application has an icon of a camel and a pyramid. This is the actual double-clickable application which you will be running when you use MacPerl.

• The files README.MAC and README contain general information about MacPerl and Perl, respectively. These files contain release notes, information on known problems, special comments about the current release, etc. Be sure to take a look at these README files.

• The Perl Artistic License file contains information related to the circumstances under which you are permitted to use Perl, give it away, or sell software that is based on it. Be sure to read the License as well.

• The Perl online documentation is stored in the pod (Plain Old Documentation) folder. The pod files comprise your best user manual. Pod files are text and can be read with many applications, including MacPerl itself. However, they will look better if you use Shuck to view them. The Shuck application icon looks like an ear of corn.

• The lib folder contains MacPerl libraries, additional functions, and modules which you may include in your programs to give you additional capabilities.

• There are also a few files which contain information specific to MacPerl itself (as opposed to Perl documentation in general). You should read MacPerl.Frontend, MacPerl.Packages, and MacPerl.Specifics.

• Many of the remaining folders contain examples of Perl code. Feel free to peruse these at your leisure. We recommend, however, that you do not move, remove, or rename any of these folders or their contents, unless you are sure you know what you are doing, as this could cause problems with running MacPerl.

The Installer has also installed the Internet Config application in a separate folder, named for the current version of Internet Config, e.g., InternetConfig1.4.

Internet Config can be used for many things, including setting up standard preferences for many Internet programs, such as News or Email readers. It can also be used to assign helpers for reading various types of files such as text, html, and pod. We'll use Internet Config later in these notes to assign Shuck as the helper program for reading pod files.

A Walk Through The Menus

Now that you've familiarized yourself, at least a little, with the contents of the MacPerl folder, it's time to try out MacPerl. Double click the MacPerl application icon to launch MacPerl. The Menu bar should contain the standard File, Edit, and Help menus (Balloon Help prior to Mac OS 8.0), as well as a new menu called Script. If you have previously installed the Internet Config extension, you may see an additional menu as well.

You may not recognize the Revert item. This causes MacPerl to revert to the last saved version of a MacPerl document (or not, if you choose Cancel).

The Edit menu should also look very familiar, although you probably wonÕt recognize the Jump to... or Format... items. We'll come back to these later. Again, many of the menu items will be greyed-out. Most of these will become active when you begin to work on a new document.

If you have previously installed Internet Config, you may see a menu between the Edit and the Script menus, named for the text editor (e.g., SimpleText or BBEdit) which has been selected as the Internet Config editor helper.

The next menu is the Script menu, which drives MacPerl, letting you run the scripts (programs) you write or get from other people. Let's look at each item in the Script menu:

• Run Script... brings up a dialog allowing you to choose, and run, a script you may have stored on disk.

• Run Front Window runs the script in the frontmost MacPerl window. The menu item name will change to reflect the actual name of the script window. If there is no active script window, this item is inactive.

• Syntax Check brings up a dialog allowing you to choose, and perform a syntax check on, a script you may have stored on disk. The script will not be run, but is simply checked for syntactic errors. It is often useful to syntax check a new script before attempting to run it.

• Check Front Window performs a syntax check on the script in the frontmost window. Again, the menu item changes to reflect the actual name of the window; this item is only active when there is a window available. The script is not run.

• The next three items (Compiler Warnings, Perl Debugger, and Taint Checks) are options you can set before running scripts. The Compiler Warnings option provides additional warnings of potential problems and incorrect code. The Perl Debugger provides a complete debugging environment for searching out the cause of errors in scripts. Taint Checks monitors the use of outside (i.e., tainted) data in controlling program activities. Thie is very useful when you are writing CGI Scripts. For now, we recommend that you select and check Compiler Warnings and Taint Checks, but not Perl Debugger.

• The last item, One Liner, allows you to specify and run one line of MacPerl code. This isn't as powerful as writing a script, but it can come in handy on occasion. Note that One Liner requires Unix-style Perl "one liner" syntax. The One Liner dialog is written in MacPerl; you can find the script in the MacPerl Scripts folder inside the MacPerl f folder.

  

On-line Help - Installing Internet Config

The last menu is the Help menu. The Help menu provides links to MacPerl's extensive online help files.

Most of the help files are in pod format and are best read with the Shuck application. MacPerl uses the Internet Config extension, included in the MacPerl distribution, to tell it which helper application to use in browsing the help files.

If you select one of the Help topics, e.g. MacPerl Overview, and you have not installed Internet Config (or have not set up Shuck as your helper application), you will get the following dialog:

If Internet Config has not been installed:

If you have never installed Internet Config, you should install it. Open the InternetConfig folder that was installed along with MacPerl and double-click the Internet Config application. You should see a dialog asking if you would like to install Internet Config.

Click Install to install Internet Config. You should soon see another dialog informing you of a successful installation. You do not need to restart.

Once Internet Config has been installed:

You should see the Helpers dialog box appear. Click the Add button, type pod in the Helper For: box, then click Choose Helper....

Navigate the file selection dialog until you find the MacPerl folder you previously installed. Select Shuck and click Open.

The Add Helper dialog should now show Shuck as the helper for pod files. Click OK. Save your changes and quit Internet Config.

Viewing the online help (pod) files

Once the pod helper is set up, you can view the online help. Once more, select MacPerl Overview from the MacPerl Help menu. (If you still see the Failed to Launch alert, quit and relaunch MacPerl).

We encourage you to peruse the online help information. The pod files contain a wealth of useful information about the Perl language. In particular, you should be sure to refer to the Macintosh-specific help topics.

A New Menu

When Internet Config has been installed, you should see an additional menu between the Edit and Script menus. This menu represents the editor helper chosen in Internet Config, and allows you to edit MacPerl scripts using an alternative to the default MacPerl editor. You may want to launch Internet Config again and set the editor helper to your preferred text editor, such as Alpha or BBEdit.

Running A Script

Next let's create a very simple script, save it, and run it. (It's not necessary to save a script before running it, but this is a good habit to get into.) We'll do this both to get a feel for how MacPerl works and to observe the resulting changes in the menus.

Create a new document (using the File menu). You'll see a new Untitled window and many of the greyed-out items in the File, Edit, and Script menus will become highlighted.

Note that the Script menu items now refer specifically to Untitled, rather than the generic Front Window.

You'll also see a new menu appear - the Window menu. The Window menu keeps track of all MacPerl windows. The check mark is next to the name of the frontmost window, in this case, Untitled. The MacPerl window is the window which shows output from your scripts; it is in italic font because we have no output at the moment.

Creating A Script

At the cursor in your Untitled window, type

   print 'hello';

If you don't like the default font or size, use the Format... item in the Edit menu to choose something you prefer. We strongly suggest, however, that you use a monospace (fixed-width) font such as Courier or Monaco.

Next, save the file as myscript (or any name you prefer). Note that the Script and Window menu items change again to reflect the new name. Select Run "myscript" from the Script menu. A new window, entitled MacPerl, will appear, containing the text:

   hello

Note that the MacPerl item in the Window menu is no longer in italics.

Close the MacPerl window and edit the script in the myscript window, deleting one of the quote marks, ', to produce:

   print 'hello;

Run myscript again. This time, the MacPerl window will contain an error message:

   # Can't find string terminator "'" anywhere before EOF.
   File 'HD:MacPerl f:myscript'; Line 1

The message tells you that MacPerl expected to find a closing quote mark, ('), but that the interpreter reached EOF (End Of File) without encountering the closing quote. If you had selected Syntax Check "Untitled", you would have received the same error message. Try it!

Select the line that says:

   File 'HD:MacPerl f:myscript'; Line 1

then pull down the Edit menu. The Jump To... item is now enabled and has changed to refer directly to the specific file name and line number in the error message.

Select Jump to "myscript". MacPerl will jump to, and highlight, the line in your script window where the error was found.

Because you saved myscript before deleting the quote mark, you should be able to revert to the previously saved version, using the Revert item under the Edit menu. Try it.

Check The Preferences

Before we leave these notes, you might want to take a look at the MacPerl preferences. The default preferences should be fine for now, but it's nice to know what they do.

The Libraries preference tells MacPerl where to look for libraries of additional code. Each path is a sequence of folders, starting with the disk volume, that leads to the location of the library files.

The Libraries already contains one path - the path to the libs folder in the MacPerl f folder you just installed. You'll add a few more paths to the libraries if you start installing and using Modules. For now, just familiarize yourself with this preference dialog so you can find it when you need it.

The Environment preference sets various environment variables, variables which are available to all parts of your Perl scripts and which tell Perl certain things about the environment under which it is running. The USER variable is taken from the owner name in the File Sharing control panel. The TMPDIR variable references a typical Mac OS location for temporary files.

The Scripts preference tells MacPerl how you want to treat scripts. The radio buttons customize how scripts are treated when you double-click them under the Finder. Specifically, a double-click can cause the script to open in the MacPerl editor or be run by the Perl interpreter.

The check box determines whether MacPerl will check for #! as the first two characters of the first line in each script. The #! line (also known as the shebang line) provides special instructions to the Perl interpreter when the script is run. An example of a #! line might be:

   #!perl -w

The word perl is required. The option, -w, tells Perl to turn on extra warnings. The warnings will tell you about non-fatal errors which could cause execution problems.

We recommend that you click the box to check for the #! line.

The Input preference tells Perl whether or not you want to enable inline input. This Preference is only meaningful under Japanese systems; it allows characters to be composed directly in the MacPerl TextEdit window instead of in a separate floating window.

The Input preference has been confirmed to work well on a Macintosh running the Japanese Language Kit, using the Kotoeri Input-System and the Osaka font. It should also work with other settings.

The Others preference handles miscellaneous things. At present, it only allows you to launch the Internet Config application, where you can set helper applications for viewing files such as the pod documentation.

Notice: This document is copyright 1997 by Prime Time Freeware (www.ptf.com, info@ptf.com); all rights are reserved. It is adapted from the chapter of the same name in "MacPerl: Power and Ease" (Vicki Brown and Chris Nandor, PTF, 1998, ISBN 1-881957-32-2). Please do not distribute this document in any modified form.