You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

Building Mac Mozilla

Note: These instructions are for building the now-obsolete CFM build with CodeWarrior. The build instructions for the current Mach-O build are here.

Table of Contents

This page aims to be the complete source of information for people building Mozilla on the Macintosh. Please report deficiencies to Please do not email me with questions about how to do stuff, or suggestions for improving the build process, or anything else that does not concern information on this page itself. Such questions should be posted to the newsgroup netscape.public.mozilla.mac

For developers who need to add files and projects to the Mac build system or change your build options, see the Mac build system page.

System Requirements

To build and run Mozilla, you'll need a beefy Mac with at least 1Gb of disk space, and 128Mb or more of memory. For serious development, we'd recommend a 300MHz 604 or G3 and 256Mb RAM. In particular, linking the layout.mcp project requires 80Mb free RAM, and in an optimized build, you will need around 100Mb of free RAM to build JavaScript.mcp, and Editor.mcp.

To run Mozilla, you must have MacOS 8.5 or later installed.

Tools and resources

Here is the list of software you have to have installed to build Mozilla on the Mac:


Note: For those internal to Netscape, there is a pre-prepared development environment on a local AppleShare server. Please contact a Mac guru for details.

CodeWarrior Pro 7.

Start with a clean installation of Metrowerks CodeWarrior Pro 7.

After finishing your CodeWarrior installation, change the memory allocation to the IDE to around 24Mb (Get Info in the Finder).

Additionally, you'll find that debugging is substantially improved on Mac OS X if you update to Pro7.2.

Universal Headers 3.4.1

Replace the 3.4 headers that ship with Pro7 with the 3.4.1 headers from Apple.

CodeWarrior Plugin SDK
(Install this from the Pro 7 Reference disk)

We build a CW plugin, the xpidl compiler, as part of the build process, so you need the CodeWarrior Plugin SDK. Install the "(CodeWarrior Plugin SDK)" folder as a sibling of the Metrowerks CodeWarrior folder.

Note that the first time you build Mozilla, you will probably get an error when building the first IDL project (xpcomIDL.mcp). If this happens, quit and restart the CodeWarrior IDE so that it picks up the xpidl project that was just built. Then restart the build.

Menu Sharing Toolkit 1.4
(alternative download site)

Menu Sharing allows other applications to add a menu to Mozilla's menu bar. Download, unstuff, and put the "Menu Sharing Toolkit 4.1" folder in CodeWarrior's "Mac OS Support" folder.

(Install MPW from the Pro 7 Reference disk or
download from Apple)

Sometimes, problems can occur when CodeWarrior attempts to start up ToolServer. If your build appears to halt when building the stubs target of NSStdLib.mcp, this could be the problem. Often, simply clicking on the desktop to deactivate the IDE causes ToolServer to fire up properly. If this still does not work, try moving ToolServer to your startup volume. If problems persist, check that you only have one copy of ToolServer installed on your machine.

MacPerl distribution

Download, decompress, and install. You can install this anywhere, but it is recommended that you install it next to your CodeWarrior folder for easy reference.

After installation, set the memory partition size of the MacPerl application to around 18Mb (by doing a Get Info in the Finder).

Important: Now make a folder called 'site_perl' in the same directory as the MacPerl application. Go to the 'Libraries' panel of the MacPerl preferences, and add this 'site_perl' folder as a library path, so that it gets searched before the others:

You may also want to set a preference to enable double-click launch of the perl scripts. This preference is set by selecting "Preferences..." from the Edit Menu. Click on the "Script" button and hit the radio button "Run Scripts opened from Finder".

cpan-mac distribution

This is a set of tools by Chris Nandor, and makes installation of new modules easier. Download, and decompress. If you have more than one copy of MacPerl installed, run the copy of MacPerl that you want to install on.

Important: Make sure you've added the site_perl folder to the search paths in the MacPerl prefs before installing the cpan module.

Now run 'INSTALL.plx' in the cpan-mac distribution that you just downloaded. It will install lots of files into the 'site_perl' folder. When it asks you if you want to install the droplets, click 'Yes'. You'll use one of these droplets to install the next two pieces.

Perl AppleEvents module

This is a Perl module that makes AppleEvent scripting easier. Download the file, but do not decompress it. To install, drag the downloaded file, 'Mac-AppleEvents-Simple-0.81.tgz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. When asked if you want to 'Convert all text and MacBinary files?', click 'Yes' (do so for the following modules too). This will install files into the site_perl directory.

Perl Launch module

This is a Perl module for launching applications. Download the file, but do not decompress it. To install, drag the downloaded file, 'Mac-Apps-Launch-1.70.tar.gz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.

Compress:Zlib module

This Perl module is used for creating jar files on Mac. Download the file, but do not decompress it. To install, drag the downloaded file, 'Comprss-Zlib-1.12-bin-1-Mac.tgz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.

Archive::Zip module

This Perl module is used for creating jar files on Mac. Download the file, but do not decompress it. To install, drag the downloaded file, 'Archive-Zip-0.11.tar.gz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.

If you want to do a static build, you'll also need to install these modules. Note that, for some reason, installing these modules takes lots of memory in MacPerl. You should allocate 24Mb of memory to MacPerl, and quit and restart it after installing each module.


This Perl module provides regular expressions for XML tokens, and is a requirement of XML::DOM. Download the file, but do not decompress it. To install, drag the downloaded file, 'XML-RegExp-0.03.tar.gz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.


This Perl module provides XML parsing functionality (using Expat), and is used by XML::DOM to parse XML-format CodeWarrior project files. Download the file, but do not decompress it. To install, drag the downloaded file, 'XML-Parser-2.30-bin-Mac.tar.gz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.


This Perl module allows for DOM manipulations of XML-format CodeWarrior projects. Download the file, but do not decompress it. To install, drag the downloaded file, 'XML-DOM-1.31.tar.gz', onto the 'installme.plx' droplet that was installed with the cpan-mac module. This will install files into the site_perl directory.

Obtaining the source code and building it

Using the MacCVS Pro client, create a new CVS session file, or download a ready-made session file here (all you need to set in this file is to enter 'anonymous' as the cvs password). If you are making a new session file, set your preferences from Edit -> Session Settings:

Checkout and Update Options

Local Tree Directory

Wherever you'd like the source code to be kept. A built tree currently uses about 508Mb of disk space. Ensure that the tree is on an HFS+ volume, otherwise the amount of space used will be much more.

Merge Policy

Auto Merge Text Files and Update Binary Files

Default Module


Default Revision


Remote Host Information

Server Hostname

CVS User Name


CVS Password


CVS Root


Network Time Out

10 Minutes

Encoding and File Mappings


You may want to map the .pl extension to MacPerl, so that you can double-click on the build scripts from the Finder. Click Add and enter

Suffix .pl, Type TEXT, Creator McPL

Be sure to use Macintosh linefeeds!

You may also wish to add mappings for MacPerl modules (.pm), JavaScript (.js), XUL (.xul), CSS (.css), DTD files (.dtd) and HTML (.html) to map them to your favorite editor (e.g. use R*ch for BBEdit).

About Tinderbox

Tinderbox is your one-stop shop for build process information. Be aware that the tree (the source code repository) is changing hourly, and you'll find people checking in code day and night. You want to pull your source when the tree is good and building (when it shows green). The columns to look at are "Mac Debug Clbr", "Mac Opt Clbr", and "Mac Opt Depend". Here is what those mean:


Mac Debug Clbr
The Macintosh Debug, Clobber build. This builds the debug targets of all projects, and is 'clobber', which means that it pulls a fresh source tree for each build. This makes it slow.
Mac Opt Clbr
The Macintosh Optimized, Clobber build. This builds the non-debug targets of all projects, and is 'clobber', which means that it pulls a fresh source tree for each build. This makes it slow.
Mac Opt Dep
The Macintosh Optimized, Depend build. This just pulls updates into an existing tree and rebuilds, which can be much faster.

Building Mac Mozilla the first time

Warning: You will be downloading tens of megabytes of source code. If you are using a modem connection, be prepared for hours and hours of download time. Be aware that a built tree takes about a gigabyte of hard disk space.

Before pulling the source code, always make sure the Macintosh build column on tinderbox is green. Redness on tinderbox presages a pull that will not build. If the Macintosh build is showing red, you might as well go to a movie and try later. You should add this tinderbox link to your bookmarks, even to your personal toolbar.

Now, to start the build process, there are some things you have to do only the first time:


  1. Check out the module mozilla/build/mac/build_scripts. If you've followed the instructions above, you can just select the menu
    Action | Check Out Default Module.


  2. Once CVS is done checking out the build directory, go to your local tree directory and open it. Drill down to the :mozilla:build:mac:build_scripts folder, and you should see several build scripts waiting for you, namely and


  3. Run either (for an optimized build) or (for a debug build) to start the build process. Just drag that file onto MacPerl, or run it in MacPerl whatever other way you prefer. Note that a debub build will probably finish more reliably, due to the overly high memory requirements of CodeWarrior during an optimized build.

    The first time you run the build script, it will prompt you for the location of the CodeWarrior application (if not already running), and your MacCVS Pro session file, which you set up above. This file will be used to check out the rest of the tree. These two pieces of information are stored, and you won't be asked for them again.

    Because various minor errors occur when checking out the tree (for example, there are some files with names that are too long for the Mac filesystem), MacPerl will probably report that the checkout failed. This error is benign; you can ignore it.

    Once the checkout is complete, the script will continue and start the build process. It will build all the projects and create a Macintosh application directory in :mozilla:dist:viewer_debug: within your source tree. In that folder, you'll find a couple of applications: Mozilla, which is what will become the final browser, and viewer, which is a small app that is used for testing the layout engine.

    For more details on how to control the build, see the Mac build system page.

Help! My build failed! Why?

Common reasons for build failure:

  1. MacPerl fails to run any of the scripts

    This is probably because the perl scripts were checked out with Unix linebreaks. Go into the MacCVS Pro session settings, and make sure that .pl and .pm files are using Macintosh linebreaks. Then trash mozilla/build/mac, and pull the scripts again.

  2. I get errors from MacPerl when I try to run the scripts!

    This is probably because there is something wrong with your installation of MacPerl, or the additions that are required. Ensure that you followed the installation instructions above, especially the part about adding "site_perl" to your MacPerl folder path preferences.

  3. When the scripts pull a tree, MacPerl tells me that the checkout failed!

    This is actually normal, or at least fairly common. There are files in the tree with names that are too long for the Mac filesystem (luckily, none that Mac needs!), and these and other minor CVS errors can confuse the checkout process.

    If you have changes in your tree, and you get CVS conflicts when updating, then you'll certainly see checkout errors. In that case, look at the messages window in MacCVS for conflict warnings, and deal with the conflicts.

  4. This is my first time building, and my build fails at XPCOMIDL.mcp with a message about xpidl not being found

    We build the xpidl plugins as part of the build, but the IDE does not pick these up without quitting and restarting. We tried to script this quit and restart, but it made MacPerl unhappy. So the first time you build, you'll have to quit and restart the IDE by hand, then restart the build.

  5. When the build gets to NSStdLib.mcp, it stalls.

    What's happening here is that we're building the Stubs target of NSStdLib.mcp, which uses the RunTSScript CodeWarrior plugin to fire up ToolServer, which builds a stubs library (using the MakeStub tool) from the .exp file of that project. (Got it?) So a number of things can go wrong here:

    • You didn't copy the 'RunTSScript' CW tool from mozilla:build:mac to your CodeWarrior Plugins folder.
    • ToolServer is not happy. Make sure that you can run it standalone (or via CodeWarrior's ToolServer menu), and that you don't have multiple copies on your machine. Also ensure that you are running the right version for your OS (you should have ToolServer 3.5 for Mac OS 9).
    • You're suffering from some weirdness with events, that causes things to stall until you switch the IDE to the background. Often just clicking around will get things moving again.


  6. The build halts because some code does not compile! How the heck can this ever work?

    You probably updated your tree at a bad time. Don't forget to check Tinderbox before you update!

  7. layout.mcp fails to link, with some random error.

    You probably don't have enough free memory available. Quit other programs, and try again.

  8. JavaScript.mcp or Editor.mcp fails to compile, with an out of memory error.

    Building some of the files in these projects in optimized mode takes huge amounts of memory; we seem to hit some pathological case in the CW optimizer. You can either try to free up enough memory (on a 128Mb machine, restart the machine, load CodeWarrior and nothing else, and you should be able to just about build the project). Allocating more RAM to CodeWarrior will not help (it uses temporary memory). Alternatively, you can modify your build prefs to use a lower optimization level in the optimized build.

OK, so my build finished. What now?


Now, to run the Mozilla browser, look in mozilla:dist:viewer_debug (or just :viewer if you built optimized). You should find the app, 'MozillaDebug', and a .xSYM file. To run, or start debugging, run this app or load the .xSYM file in CodeWarrior.

You'll also notice that this app is only around 200K in size. That's because most of the code lives in shared libraries, which go into the Essential Files folder (these are libs that are loaded automatically by CFM), and the Components folder (these libs are XPCOM modules, and are loaded by the app at runtime). So when you are debugging, you'll have to grovel around in these folders for the appropriate .xSYM files.

Debugging tips

So you've hit an assertion, or found a crash. How to debug it? It's often easiest to run Mozilla without the debugger first, so you drop into MacsBug on an assertion or crash. You can then get a stack, and log this to a file (log my_crash,sc,log).

If you're in the Metrowerks debugger and halt for some reason, it can be a little harder to find out where you are. The debugger should show fragment names in the stack pain (try using the older, stand alone debugger MWDebug 1.7.4, which is a little better at debugging across shared libraries). Locate the .xSYM file that corresponds to the fragment name, and load it.

Another problem that we often run into is that the MW debugger can't show the contents of interface pointers (nsIFoo), which has been submitted as a bug to Metrowerks. To work around this, you'll have to step into some code that uses the concrete class behind the interface; it may be necessary to add a dummy call to the code to be able to do this.

Setting environment variables

Classic Mac OS has no concept of environment variables, but there are several developer features in Mozilla that relies on environment variables, so we have a couple of ways to set these up for Mozilla.

Startup file

If you do a Mozilla bulid, you'll have a file called 'NSPR Logging' in the same directory as the application. It contains some lines like:


If you start Mozilla by dragging this file onto it, Mozilla will pick up those environment variables. You can edit this file, or make another file; just edit the 'ENV' lines. This technique is useful if you want Mozilla to use those environment variables only for some runs where you need them.


If you make a file called 'ENVIRONMENT' (case does not matter) and put it in the same folder as Mozilla, Mozilla will look in this file when it runs, and pick up environment variables within it. The file contents should look like:


More information

For more information about the Mac build system, see the Mac build system page. If you are interested in contributing, and need information, please post on the netscape.public.mozilla.mac newsgroup.

Simon Fraser