Building Mac Mozilla

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.

How it works now

The build system is fully automated. You have to set up a build environment by assembling pieces from here or there, but after that, you can check out and build all the projects with a single perl script. The build system is still rapidly evolving, and is not idiot-proof, but should be usable.

Recent changes

To find recently-added information quickly, click on the links below, and look for this symbol:

• 99/07/26. XPIDL compiler is now part of the build.

Future changes

Read the newsgroup netscape.public.mozilla.mac daily. It's good for you, and tastes good, too.

System Requirements

To build and run Mozilla, you'll need a beefy Mac with at least 1Gb of disk space, and 64Mb or more of memory. For serious development, we'd recommend a 300MHz 604 or G3 and 128Mb RAM.

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

Note that there are some bugs currently that cause things to malfunction if you have non-ASCII characters or slashes '/' in your disk or folder names, for any of the folders in the hierarchy up to where the application is running from.

Tools and resources

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

CodeWarrior Pro 4.	Start with a clean installation of Metrowerks CodeWarrior Pro 4.
Codewarrior Pro 4 updates	The upgrades have been posted by MetroWerks on the web, and are free. Instructions.
CodeWarrior Plugin SDK	Because the xpidl compiler is now compiled as part of the build process, you need the CodeWarrior Plugin SDK. Install this in the Mac OS Support folder.
Universal Headers 3.2	Mozilla requires Universal Headers 3.2 to build. If you haven't already obtained these, download and install in the appropriate folders in the Mac OS Support folder.
ToolServer	From the CodeWarrior Pro CD. Uncompress the StuffIt Archive for ToolServer. The goal is to let ToolServer and MPW share the same Tools directory so you don't need to have multiple versions of tools. Do the following: Open ToolServer's Tools folder. There should be one file called "RMetrowerks". Move RMetrowerks to the Tools folder of MPW. The MPW folder should be at "Metrowerks:Codewarrior MPW:MPW" if you installed Codewarrior correctly. Remove ToolServer's Tools folder. Now create an alias of Tools folder in "CodeWarrior MPW" and move it to your ToolServer folder. Rename the alias (probably called "Tools alias") as "Tools". IMPORTANT: Make sure you only have one instance of ToolServer on your machine. If the build script finds the wrong one, the correct tools will not be found and strange things will happen. Sometimes, problems can occur when CodeWarrior attempts to start up ToolServer. If you 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.
WASTE 1.3	Decompress and then drag the entire folder to the MacOS Support folder in your CodeWarrior folder.
Menu Sharing Toolkit	Decompress and then drag the entire folder to the MacOS Support folder in your CodeWarrior folder.
Internet Config 1.4 SDK	Decompress and then drag the entire folder to the MacOS Support folder in your CodeWarrior folder.
MacPerl5 5.20r4 (Application)	Download, decompress, and install. You can install this anywhere, but it is recommended that you install it inside of your CodeWarrior folder for easy reference. After installation, you will need 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"
Mac::AppleEvents::Simple	Download, decompress, and install in your MacPerl folder in :lib:Mac:AppleEvents:. How do I decode these tar/gzip files?
Mac::Apps::Launch	Download, decompress, and install in your MacPerl folder in :lib:Mac:Apps:. How do I decode these tar/gzip files?
XPIDL Plugin	Note that the XPIDL plugin will very soon be built as part of the build proces. After that time, there will be no need to download it. Version 1.0d5 now required for the build. Unstuff the archive, and drag the various components into your CodeWarrior plugins folder. The destinations are clearly marked. Documentation is here.

Obtaining the source code and building it

Using the MacCVS Pro client, create a new CVS 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. Make sure that you have at least 500MB free on that volume (right now the source only needs about 300MB, but it's a good idea to leave some free space for growth).
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 JavaScript (.js), XUL (.xul) and HTML (.html) to map them to your favorite editor.

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 Opt Clbr", and "Mac Opt Depend". Here is what those mean: 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 4 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 your CVS session file. This file will be used to check out the rest of the tree.

   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: apprunner, which is what will become the final browser, and viwer, which is a small app that is used for testing the layout engine.

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

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.

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

NGLayoutBuildList.pm	Contains the list of directories to check out, manifest files to be processed for inclusion in :mozilla:dist:, and projects to built. It builds both debug and optimized versions. Has 3 main functions: Checkout, BuildDist, and BuildProjects. When run for the first time, it will prompt you for the location of the CVS session file, and store the location in nglayout.cvsloc above your source tree.
PullNGLayout.pl	Pulls the source tree required to build NGLayout. To use the script, double-click on it and it will start executing. An open-file dialog box will come up. Direct it to the MacCVS Session file that you used to check out the script. Open the session, and the perl script will then send a series of checkout commands to MacCVS and pull the required sources.
BuildNGLayoutDebug.pl	Configures various build options and starts a build of NGLayout. Mac build scripts have an annoying problem: there is no way to specify command-line options to MacPerl. This means that you can't specify different make options to the build system without editing the scripts. To customize your builds (build_all, pull_layout, etc.), make a copy of the build script (BuildNGLayoutDebug.pl) and name it whatever you like. Then edit the %pull and %build variables inside the script. To build optimized binary, set $DEBUG = 0.

Hack alert: To create NGLayout-specific #defines that span all the projects, the build scripts use a hack. All Mac projects we care about include mozilla/config/mac/MacConfigInclude.h. By default, an alias to this file is exported to :mozilla:dist:. The NGLayout build script replaces this alias with a new one, pointing to NGLayoutConfigInclude.h, but the alias is still named MacConfigInclude.h.

Something in this document is wrong

Please inform the MacFE project owners of the error, and (ideally) recommend a solution. Answers to additional problems not yet in the FAQ are also welcome.

Where else can I go for answers?

Point your newsreader at the Mozilla newsgroups or subscribe to the mailing lists: http://www.mozilla.org/community.html.

Also, check out So you want to add something (and not break the build) ..., a guide to adding files and directories without breaking any of the three platforms.

Can I build with older versions of CodeWarrior?

Currently, the answer is, "No." We make use of several classes in PowerPlant which recently appeared in Pro4. Time to upgrade, I'm afraid. Don't even try opening the projects with Pro2 because you will get data loss and have to throw the project away (it won't even prompt you!).

I can't build the stubs target of NSStdLib.mcp

It sounds as though your ToolServer environment is not set up correctly. Make sure you follow the directions to the letter. You could also be seeing this if you have multiple versions of ToolServer on your computer and the Finder lauches the wrong one. This is very common, as the Carbon Dater app from Apple DTS contains a copy of ToolServer. Either remove all the other versions of ToolServer or make sure you launch the appropriate version before you start building.

Other thoughts: if ToolServer is not on your boot disk, you may have to launch it by hand before starting your build. The symptom in this case will be a "freeze" in which CodeWarrior is waiting for the Finder to finish launching ToolServer.

MacPerl is giving me grief.

If you're seeing AppleEvents errors, you probably need to give MacPerl more RAM to play with. If you're still using the default RAM size, increase it by 1MB.

If MacPerl appears to be freezing, patience is the first approach - especially if you're on a slow Mac.

If you're sure that MacPerl is frozen, maybe the build script can't find or launch CodeWarrior. The CodeWarriorLib.pm tries its best to find CodeWarrior without bothering you, but sometimes this doesn't work. Try opening the CodeWarrior IDE before you run whatever Perl script you're trying to run.

Also, check that the addition perl modules you downloaded in the install process have Macintosh line breaks. MacPerl dislikes other linebreaks.

How can I stop a build in progress?

The most reliable way is to quit the CW IDE. Just switch to CodeWarrior and press command-Q. CodeWarrior may ask you to confirm the action, and it may complete the current job before quitting. MacPerl should error out; sometimes, MacPerl will also relaunch CodeWarrior.

How much RAM does CodeWarrior need

The IDE in CodeWarrior Pro 4 uses temprorary system memory as needed. An ideal partition size for normal builds is 18-24Mb.

Why won't JavaScript build?

#pragma optimization_level 2

near the top of the file..

• Version 1.3. Monday July 26 1999. Lots of cleanup, and updaing the instructions about building the XPIDL compiler.
• Version 1.2. Tuesday, January 19, 1999. Fixed some small bugs. Added the "rebuild" tips. Seems that I, mcmullen@netscape.com am now the pagemaster for this page.
• Version 1.1. 5 December 1998. Edits and new FAQ section. Added CVS session settings. Updated build system architecture. Michael Blakeley, mike@blakeley.com.
• Version 1.0. Date unknown. Aleks Totic atotic@netscape.com