Building Mac Mozilla

Table of Contents

• Building Mac Mozilla
• System Requirements
• Tools and resources
• Obtaining the source code and building it
• Running Perl scripts
• Building Mac Mozilla the first time
• Help! My build failed! Why?
• OK, so my build finished. What now?
• Debugging tips
• Updating and Building Mac Mozilla on subsequent occasions
• More about the build system

This page aims to be the complete source of information for people building Mozilla on the Macintosh. Please report deficiencies to sfraser@netscape.com. 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

If you are a programmer on another platform, and you need information to make your changes Macintosh-friendly, there is a page just for you here.

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.

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.

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. 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	mozilla/build/mac
Default Revision	(LEAVE BLANK)
Remote Host Information
Server Hostname	cvs-mirror.mozilla.org
CVS User Name	anonymous
CVS Password	anonymous
CVS Root	/cvsroot
Network Time Out	10 Minutes
Encoding and File Mappings
Add	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).

Running Perl scripts

Some folks use BBEdit and BBEdit perl extensions as their build environment. This allows you to edit the build scripts inside BBEdit, and use the extensions to run it inside MacPerl. You can also use Alpha and its Perl mode to do the same thing.

You can even try to run the build scripts from MPW, but some have reported that MPW perl tool often crashes.

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.

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.

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.

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. 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: folder, and you should see several build scripts waiting for you.

   You should also see the RunTSScript MPW compiler. You'll need to place a copy of this in your CodeWarrior Pro 5 folder, in Metrowerks CodeWarrior:CodeWarrior Plugins:Compilers:. Quit and restart the IDE after doing this.

3. Run PullNGlayout.pl to download to rest of the source. Just drag that file onto MacPerl, or run it in MacPerl whatever other way you prefer.

   The first time you run PullNGlayout.pl, it will prompt you for the location of the CodeWarrior application (if not already running), and your CVS session file. This file will be used to check out the rest of the tree.

   When the checkout is done, run BuildNGLayoutDebug.pl from MacPerl. This script 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 vier, which is a small app that is used for testing the layout engine.

Help! My build failed! Why?

Common reasons for build failure:

1. 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.

2. When I run PullNGLayout.pl, 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.

3. 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. (See below for details on how to make that second rebuild faster.)

4. 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.
   • 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.

5. Linking NSRuntime.mcp fails with various link errors

   This is probably because building NSStdLib stubs failed. Check for the file 'NSStdLibStubs' in mozilla:dist:client_stubs. If it is missing, check that the Stubs target of NSStdLib.mcp builds ok (see above).

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 fails to compile, with an out of memory error.

   Building JavaScript.mcp in optimized mode (especially the file jsinterp.c) 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). Or you can cheat, and add #pragma optimization_level 2 at the top of jsinterp.c.

OK, so my build finished. What now?

Congratulations!

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. For some reason (unknown at this point), code on the stack that comes from shared libs in the Components folder does not display the fragment name, so it can be hard to find the right .xSYM file for that code. One thing you can do, if you run with VM off, is to drop into MacsBug, and type 'wh 0AEE2324' (where that's an address that shows up on the stack in the debugger), and MacsBug will tell you which code fragment that comes from. If VM is on, you'll have to play a guessing game, or consult the stack crawl from MacsBug, or use LXR to search for relevant code.

Updating and Building Mac Mozilla on subsequent occasions

Subsequent builds are a little easier.

1. Before pulling the source code, always make sure the Macintosh build on tinderbox is green. Redness on tinderbox indicates a pull that will not build. If the Macintosh build is showing red, you might as well go to a movie and try later.

2. Check out :mozilla:build:mac: again. This is because the scripts you use to pull and build the tree themselves reside in the tree. Therefore, if somebody has checked in changes to these scripts, you need to ensure that you are pulling and building with the latest version of the scripts.

3. Run PullNGlayout.pl to update your local tree with changes from the Mozilla repository.

4. Run BuildNGLayoutDebug.pl from MacPerl. This script will build all the projects and create a Macintosh application directory in :mozilla:dist:viewer_debug: within your source tree.

Often, you'll want to do incremental builds to just rebuild one or a few projects after making a change to the source, or fixing a problem that halted your build. In particular, you might want to avoid the steps that install headers and resources using MANIFEST files, as this is particularly time-consuming.

You can adjust what gets done when you run the 'BuildNGLayoutDebug.pl' script by opening it (e.g. in BBEdit), and editing some settings. Look for the line

  $build{all}    = 1;  # Turn off to do individual builds, or to do "most"

and the list of build{foo}s beneath it. If $build{all} == 1, then everything will get built. To build just a few things, set $build{all} = 0, $build{most} = 0, and turn on individual parts of the build (e.g. $build{nglayout} = 1). The parts you'll most want to avoid doing if not necessary are:

  $build{dist}      = 0;    # this copies headers to mozilla:dist using MANIFESTS.
  $build{resources} = 0;    # this copies resources to mozilla:dist:viewer<_debug>:
  $build{xpidl}     = 0;    # this builds the xpidl compiler
  $build{idl}       = 0;    # this builds all the IDL projects, regenerating many .h files

The list of things in the $build{} array is in the order in which they are built, so you'll normally want to set elements to 1 from some starting point down (e.g. everything after nglayout). Messing with the build system like this does require some understanding of what the dependencies are, so only do it if you are familiar enough with how things work.

More about the build system

The build system uses MacPerl to drive various Mac applications with AppleScript and AppleEvents. It consists of 3 perl scripts:

Once you have checked out, you run BuildNGLayout<Debug>.pl, and the build progresses like this:

1. dist stage.

   First, header files from various directories in the tree are copied to (actually, aliases are made in) mozilla:dist. This is done mainly to simplify project access paths. Each directory that contains public header files contains a file called MANIFEST, and NGLayoutBuildList.pm runs through this list of MANIFEST files, making aliases to the header files listed therein.

2. resources stage.

   This stage copies (again, aliases) resource files from their locations in the tree to various folders in mozilla:dist:viewer<_debug>, where the final application will go. Because Mozilla is a cross-platform effort and uses a UI described in XUL and CSS, these resources consist of XUL, CSS, GIF and other files. The resource installation process uses a series of MANIFEST files in much the same way as the dist phase.

3. xpidl stage.

   This phase builds the xpidl compiler (which is used during the next, idl, phase). It builds one project that makes the following tools in you CodeWarrior Plugins folder: Compilers:xpidl, Linkers:xpt Linker, Preference Panels:xpidl Settings.

4. idl stage.

   This phase builds a series of IDL projects. These projects use the xpidl compiler to convert IDL (Interface Description Language) files into C++ .h files, and .xpt files (which contain information on the interfaces that JavaScript can use to call C++ functions). The header files that are generated are again aliased into directories in mozilla:dist.

5. stubs stage.

   This phase builds the one stub library that we need, NSStdLibStubs, using the RunTSScript tool to tell ToolServer to build a stubs library from a .exp file.

From here on, the stages build normal CodeWarrior projects that generate shared libraries. Note that after building a project, the Perl script makes an alias to the shared library (and, optionally, its .xSYM file) in one fo the folders in mozilla:dist:viewer<_debug>. The various groupings are:

runtime

Low-level support libraries (which include some MSL code)

common

A miscellaneous set of Mozilla utility libs (e.g. xpcom, JavaScript, zlib)

imglib

Libraries for image decoding

necko

The networking and protocol libraries

browserutils

Various feature libraries (e.g. profile management)

intl

Libraries for international features (e.g. charset detection and conversion)

nglayout

The core layout libraries (e.g. DOM, HTML parser, layout)

editor

Editor libraries

viewer

The viewer testbed application

xpapp

Various browser-level feature libraries (e.g. find, search, history, related links)

extensions

Mozilla extensions (e.g. irc chat)

mailnews

Mailnews libraries

apprunner

The project that builds the Mozilla executable

More information

For more information about the Mac build system, or how to contribute to the Mac Mozilla project, please post on the netscape.public.mozilla.mac newsgroup.