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

• 99/02/04
• 99/02/03
• 99/01/29
• 99/01/28
• 99/01/20
• 99/01/19

Future changes

The perl scripts may be going away soon, in favor of a master "Cluster" project. It will be easier, faster, and better in oh, so many ways.

How do I know these things? I read the newsgroup netscape.public.mozilla.mac daily. It's good for you, and tastes good, too.

Tools and resources

To build MacMoz, you'll need the MetroWerks CodeWarrior Pro 4 development environment. Choose the Full MacOS Install option when you install. This option requires about 250MB of free disk space.

Next, you'll need to install some additonal tools.

MacOS 8.5.	Without this, the application will not run, because it requires Appearance 1.1 and the FontManager library from this OS version.
Universal Headers 3.2	From Apple Computer, Inc. The "CodeWarrior users ReadMe" that comes with the apple download says that if you have CW PR4, you don't have to install anything. It lies! You have to. Uncompress and install these files in the CodeWarrior folder, in ':MacOS Support:Headers:Universal Headers:' ':MacOS Support:Libraries:MacOS Common:' ':MacOS Support:Libraries:MacOS PPC:' as appropriate.
Obsolete GA classes	From the CodeWarrior Pro Reference CD Uncompress and install these classes in the CodeWarrior folder, in ':MacOS Support:PowerPlant:_Will Be Obsolete:'
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.
WASTE 1.3	Decompress and then drag the entire folder to the MacOS Support folder in your CodeWarrior folder.
CWASTE 1.6.2	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.
AEGizmos 1.4.2	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"
MacPerl5 5.20r4 (MPW Tool)	Run the installer application. In the MacPerl folder, there will be an MPW tool named "perl". Install this in the MPW tools folder.
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?
GNU patch 2.1	Install the MPW patch tool into your MPW Tools folder.

Note: if you are thinking of integrating NGLayout into another product, you will not need all the 3rd party libraries Mozilla requires.

Using the MacCVS 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!

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

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

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

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.

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.

Building Mac Mozilla the first time

Warning: You will be downloading tens of megabytes of source code. If you are using a 33.6 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.

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. Note: by default it may pull the tree too. Open the file (it's just text) modify it, and set the "pull all" flag to 0 if it is 1. There is no reason why you cannot make minor modifications like this to the scripts, to suit your own nefarious purposes.

Updating and Building Mac Mozilla on subsequent occasions

The following steps are highly recommended:

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. Delete the files in :mozilla:dist:. While this may not always be necessary, it occasionally is, especially when a header has become obsolete.
3. 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.
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.h tml.

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 MemAllocatorStubs

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.

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 appears to use temprorary system memory as needed. So while you need to have about 35MB RAM free to compile the largest Mozilla projects, it needn't be contiguous. CodeWarrior itself starts with about 10MB, and that seems to be sufficient.

In theory, running virtual memory will allow CodeWarrior to run with only 6MB RAM. However, virtual memory is known to slow down application launching, and will certainly slow down your build process in general, as well. Since building MozMac is slow enough already, and RAM is cheap, we do not recommend VM.

If PowerPlant.mcp is failing to compile, you may have a memory shortage. Try quitting other applications, so the system can give that memory to CodeWarrior.

Why won't JavaScript build?

If JavaScriptPPC.mcp (mozilla/js/macbuild) is failing to compile, you may be building the wrong target. Make sure you're building the JavaScriptNoJSJ or JavaScriptNoJSJDebug target. This shouldn't happen if you're using the build scripts in mozilla/build/mac.

Also, a bug in CodeWarrior seems to keep jsinterp.c from compiling properly in non-debug mode. If you're seeing this problem, try compiling jsinterp.c by itself: select the file in the JavaScriptPPC.mcp project window, and press command-K to compile it.

• 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