327

Chapter 23:

• What You Need
• Setting It Up
• Building MacPerl
• Building Extensions

Building MacPerl
And Extensions

I tell this tale, which is strictly true,
Just by way of convincing you,
How very little, since things were made,
Things have altered in the building trade.

- Rudyard Kipling, A Truthful Song

MacPerl comes in source codeform, so you can read the source code and, if you
so desire, build the application and related files for yourself.

Perl's source code distribution is done for several reasons; primary among
these are Perl's licensing terms and Perl's cultural terms, which encourage,
in all cases, the distribution of source with any Perl binary. You might want
to build the software yourself for any of several reasons:

• You come from a culture that does not trust precompiled software (un-
  likely if you are using Mac OS).

• You want to make changes to the source to suit your own needs.

• You want to make patches to submit to the main MacPerl distribution.

• You just want to see if you can do it.

Any of these reasons (or no reason at all) is sufficient; unlike typical Macin-
tosh "freeware", MacPerl is freely redistributable in both source code and
binary form. So, enjoy!

The MacPerl source code is not, for the most part, written in Perl; MacPerl
itself, for instance, is written in C. So, whereas we use MacPerl to compile

and run our Perl programs, we will need a C compiler to build MacPerl and
any other C files.

If you do not have experience with C, you might not want to attempt this.
Furthermore, unlike MacPerl itself, some of the libraries that are required
to compile the MacPerl program are not free; in fact, they may seem quite
expensive, depending on your resources and budget.

If you want to port extensions to MacPerl, you will need to set up the build
process as described below; it is not necessary to actually build MacPerl in
order to build extensions to it, but since you have to set up everything any-
way, it couldn't hurt to try. Probably.

What You Need

The most important ingredient other than the source itself is Metrowerks
CodeWarrior,¹a popular programming development environment for Mac
OS. The most recent version of MacPerl is geared toward CodeWarrior Pro
2, but it also uses some "obsolete" libraries and headers that are no longer
bundled with CodeWarrior Pro 2. These must be gathered from older ver-
sions of CodeWarrior (e.g., CodeWarrior Gold 11).

The build process itself is done in MPW, which is discussed in Chapter 22,
MPW Perl. You can use your own version of MPW if you like, but you will
need to get the CodeWarrior MPW files installed. A special tool called
dmakeis used by MPW to do some of the building; it is available, along
with other useful files, on our CD-ROM.

Setting It Up

These instructions are geared to the MacPerl 5.1.9r4 sources and assume that
you have copies of CodeWarrior Pro 2 (CWPro2) and CodeWarrior Gold 11
(CW11). (The current reliance on the old libraries and headers is likely to
be removed eventually; be careful if you're using a release later than Mac-
Perl 5.1.9r4.) The instructions also assume that MPW has not already been
installed.

1. Install the following from the CWPro2 CD-ROM:

1_{See www.metrowerks.com. There is a free CodeWarrior Lite version of the program,}
but it is insufficient for our purposes.

• CodeWarrior MPW
• Metrowerks C/C++ for Mac OS Headers & Libs (for PPC and 68K)
• Metrowerks Standard Library (MSL C/C++)

You are, of course, free to install all of CodeWarrior, and this is actu-
ally recommended, but only the above are required.

2. Install the MacPerl application (if it is not installed already) and
   install the MacPerl sources.

3. Rename the Metrowerks MPWdirectory to MPW(MacPerl's makefiles
   require this). All of the directories mentioned below, except where
   noted, are specified relative to this directory.

4. Launch and configure MPW. Run the MPW script CW_Max_Dup_Up-
   date, which will copy relevant Metrowerks libraries to the MPW
   directories.

5. Install the MacPerl MPW tool (see Chapter 22, MPW Perl).

6. Install dmake. Take the files dmakeand startup.mkand put them in the
   :MPW:Tools:folder. Put BuildProgramand BuildCommandsin the :MPW:
   Scripts:folder (back up the existing versions, for safety's sake).

7. Find the obsolete libraries. On the CW11 CD-ROM, these are stored in
   a directory called (Obsolete ANSI Libraries). Run copy_mw_libs.pl
   (provided on the disc) to copy the libraries. It will prompt for the libs
   directory and the directory with the MPW Shell application.

If you have the CW11 CD-ROM mounted, you have the option of copy-
ing directly from the CD-ROM. In this case, the script will also copy
the files from step 8 below.

This script makes new folders for the obsolete libraries:

:MPW:Libraries:OldMWPPCLibraries:
:MPW:Libraries:OldMW68KLibraries:
:MPW:Interfaces:OldMWCIncludes:

(for PPC libraries)
(for 68K libraries)
(for header files)

The script then copies all the files from all the subfolders in the
obsolete libraries folder into these folders.

8. Find the old runtime libraries. On the CW11 CD-ROM, they are stored
   in Metrowerks CodeWarrior:MacOS Support:Libraries:Runtime:(this
   step is performed automatically if the copy_mw_libs.plscript above is
   set to copy directly from the CW11 CD-ROM). Copy the following files
   to :MPW:Libraries:OldMW68KLibraries:

CPlusPlus.Lib
MWCFM68KRuntime.Lib

MPWRuntime.68K.Lib
ShLibRuntimeCFM68K.Lib

Copy the following files to :MPW:Libraries:OldMWPPCLibraries:

MWCRuntime.Lib
MWMPWCRuntime.Lib

ShLibRuntime.Lib

9. Here is something that might take some hunting. Find NuToolLibs.o,
   version 3.4d8, created December 13, 1994. The file might be on some old
   MPW archive somewhere, but it is not on any recent CodeWarrior or
   MPW distribution. It is currently necessary for building, however. Once
   you find it, put it in :MPW:Libraries:CFM68KLibraries:(create the
   directory if it is not there).

10. In the MacPerl source distribution, the XLfolder contains unresolved
    aliases. This needs to be fixed. Get the XLfolder from the CD-ROM and
    copy those files into the folder in the source distribution.

11. In the MacPerl source distribution, the file Makefile.mkin the macperl
    folder needs some changes; it does not include all the needed directo-
    ries. Copy the file Makefile.mkfrom the CD-ROM into the macperl
    folder in the source distribution.

12. Find InterfaceLibversion 1.1.2 (it is on the CW11 CD). The newer ver-
    sion, 1.1.3, has some problems with CFM-68K. Go to :MPW:Interfaces&
    Libraries:Libraries:and replace version 1.1.3 of InterfaceLibin the
    MWPPCLibrariesand MW68KLibrariesfolders with version 1.1.2.

13. Restart MPW.

Building MacPerl

If you followed all those directions precisely, there is a reasonable chance
that the build process will go off without a hitch.

The general procedure for building is this: set the directory in MPW to your
MacPerl_Srcdirectory and execute the command:

BuildProgram build_perl

If all is well, this will run to its completion and you are finished. If so, con-
gratulations! On the other hand, all might not go well, so here are some
hints. Ignore compiler warnings. If compilation is prematurely terminated
because of an error, remember that the error messages mean what they say
(most of the time). Sometimes a library or header cannot be found; if so, find
the file and put it where MPW is looking for it.

A good way to find a missing file is to use the Find Filefeature of Mac OS.
Simply type in the name of the missing file; if files of different versions
come up in your search, you will need to determine if the file wanted is old
or new, and then determine which file you have is old and which is new.

Remember that the old files are in the Old*directories where we put the
obsolete libraries and headers. New files are in the Interfaces&Libraries:
subdirectories. The error message should report what directory it is looking
in for the needed file.

If all else fails and you can't find your way home, ask the MacPerl mailing
list. Also, our CD-ROM contains a large text file with the complete text of
a MPW MacPerl build session, which may or may not help at all.

Installation

Some people prefer to use their MacPerl source directory as their main Mac-
Perl directory. If you don't want to do this, you will probably have to copy
all the newly built files by hand. This is not a difficult chore for someone
who knows the MacPerl distribution well enough to build it. The applica-
tions are in :macperl:, along with some of the directories. The MPW perl
tool and the lib and pod directories are in :perl:.

Building Extensions

As noted in earlier chapters, most CPAN-derived extensions do not work
without modification under MacPerl. Extensions are usually written in C
and XS and need to be ported and compiled as Mac OS shared libraries.

These shared libraries can only be used by the PowerPC and CFM68K ver-
sions of MacPerl. Non-CFM68K versions of MacPerl cannot load modules
dynamically; for that, a module must be linked in statically during the
build process. You can do this by adjusting the MacPerl makefiles to include
those extra modules in the static build, but there is rarely a reason to do it,
as most 68K Macs can handle the CFM68K version of MacPerl.

Some extensions need to be ported; that is, parts of the code need to be modi-
fied to work with MacPerl. Many extensions need no porting at all, compil-
ing straight out of the box. For this runthrough, we'll write our own exten-
sion, a module called XPlusX.²It exports a function called x_plus_x(),
which takes one numerical argument, adds it to itself, and prints the result-
ing value, rounded off to the nearest integer.

Here is the XS file, called XPlusX.xs:

#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"

MODULE = XPlusXPACKAGE = XPlusX

void
x_plus_x(num)
double num
CODE:
printf("%.0f\n", num + num);

Now, the module, XPlusX.pm:

package XPlusX;
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
@EXPORT = qw(x_plus_x);
$VERSION = '0.01';
bootstrap XPlusX $VERSION;
1;

2_{As you might imagine, we are not going to explain anything about XS itself, or writing}
modules. Please see perlmodlib, perlxs, perlxstut, ExtUtils::MakeMaker, h2xs,
and Advanced Perl Programming.

And Makefile.PL:

use ExtUtils::MakeMaker;
WriteMakefile(
'NAME'=> 'XPlusX',
'VERSION_FROM' => 'XPlusX.pm',
'XSPROTOARG'=> '-noprototypes'
);

We put all three of these files in the folder :MacPerl_src:perl:ext:XPlusX
(creating the XPlusXfolder). Then, the process is very similar to that used
on Unix systems. But, instead of the Unix mantra:

perl Makefile.PL
make
make test
make install

We use:

perl Makefile.PL
BuildProgram all
BuildProgram install

Run each of those commands in succession. This will install the following
files under :MacPerl_src:

:perl:lib:XPlusX.pm
:perl:lib:MacCFM68K:auto:XPlusX:XPlusX
:perl:lib:MacPPC:auto:XPlusX:XPlusX

If your source tree differs from the regular MacPerl tree, you will need to
install these files in the appropriate place (e.g., the site_perldirectory):

perl -x ":::PerlInstall" "-l" "{MACPERL}site_perl"

Now we can run the module and see what happens. Once the files are
installed, you can run any test scripts that are provided.³We have not
included test files with this module, however, so try this from MPW:

3_{Test files often fail because, possibly unlike the module they are written to test, they}
assume the presence of particular Unix filesystems.

perl -MXPlusX -we x_plus_x(2.4)

Or, try this from the application:

#!perl -w
use XPlusX;
x_plus_x(2.4);

Either of these should print 5. For fun, try other numbers, such as:

'2.24' . 9 x 13
'2.24' . 9 x 14