Building Mozilla on the Macintosh PPC platform

Daniel Nunes, leaf@netscape.com

1. Introduction

2. Building Mozilla

• 2.1 Get the Code
• 2.2 Requirements
• 2.3 Set up the Build Environment
• 2.4 Build the Lizard

3. Common Problems

4. Credits

1. Introduction

What this document is: A guide to building the Mozilla application. This includes:

1. A listing of the development tools you will need to build Mozilla.
2. A list of environment variables you will need to set before building.

If you're looking for documentation on developing features or fixing bugs, the Mozilla Technical Documents or Library are probably what you're looking for.

2. Building Mozilla

Each of the following subsections describes, or gives references to descriptions of, the steps necessary to build Mozilla.

2.1 Get the Code

There are two principal ways of getting the code, ftp and CVS. CVS will provide the most current code for building, but is slower than ftp (takes longer to download).

2.2 Requirements

The following need to be installed:
• CodeWarrior (CW) 2 - obtainable from Metrowerks. See Common Sticking Points if you have a different version.
• PowerPlant 1.8 - obtainable from the CodeWarrior CD.
• MSL - the Metrowerks Standard Library, obtainable from the CodeWarrior CD
• WASTE 1.3
• CWASTE 1.6.2
• Menu Sharing Toolkit (from UserLand)
• Mercutio 1.5 SDK (only download the SDK, not the entire package, else the access paths will be wrong)
• Internet Config 1.4 SDK
• AEGizmos 1.4.2
• MacPerl 5 MPW Tool
• MacPerl 5 Application
• MakeStub - MPW (installed with CodeWarrior Heaven option). If you choose not to install MPW, it is located on the MacOS Tools CD in "CW Pro 2 Tools:CodeWarrior MPW:MPW:Tools"
• RunTSScript - in Mozilla source distribution (mozilla:build:mac:RunTSScript), needs to be installed by hand
• ToolServer - or in the CW distribution (CW Pro 2 Tools:Apple Development Tools:ToolServer 3.4.1.sit). We recommend pulling it off the CD because it comes with configuration files for CodeWarrior which you would have to create manually were you to pull it off the net.
• New Alias MPW Tool An MPW tool that creates Finder aliases for files.
• StreamEdit MPW Tool - MPW (installed with CodeWarrior Heaven option). If you choose not to install MPW, it is located on the MacOS Tools CD in "CW Pro 2 Tools:CodeWarrior MPW:MPW:Tools"
• ToolFrontEnd
• patch 2.1

Hardware/OS

• To build Navigator, you need a fast PPC Mac. The faster the better. You can't build with a 68K machine because we have too many resources, and the build process will crash when trying to generate resources out of our cross-platform strings. See the discussion below for a way around this.
• You will need about 96 MB of physical RAM to "fast link" the app. You can still fast link if you give your machine 96 MB of virtual memory, but then the VM hit is large enough to counteract any improvement. One of our beta testers had a machine with only 64MB of physical RAM (VM was off) and it ran out of memory trying to link. Turning VM on got it to link, but build time increased greatly.
• Reports from the net indicate that the optimized version (MozillaPPC) take much less RAM to build than the 96MB we suggest. If you are running out of memory, try building that instead of the debug version (the debug symbols require a lot of RAM come link time).
• You should be ok with a 400MB disk partition, even when fully built. This does not include tools like the IDE, just source.
• On an HFS+ volume, a full build takes about 110MB. HFS+ is good, but utilities are sparse.

2.3 Setup the Build Environment

1. Install CodeWarrior from the CD. While it is large, installing the "CodeWarrior Heaven" option will guarantee that you have everything you need. This will give you PowerPlant, MSL, and MPW. If you choose to install less, proceed at your own risk.
2. In the Finder, increase the memory partition of the IDE to 15MB (you can get by with 12, if need be).
3. Download ToolFrontEnd. After expanding it, in "ToolFrontEnd Folder:Drop-Ins" there are three items:
   • #include
   • ToolFrontEnd
   • ToolFrontEnd Panel

   Create a folder named "Include Scanners". Place the file "#include" into the Include Scanners folder. Move the Include Scanners folder to the CodeWarrior Plugins folder. Create a folder named "ToolFrontEnd". Place the files "ToolFrontEnd" and "ToolFrontEnd Panel" into the ToolFrontEnd folder. Place this folder in the CodeWarrior Plugins folder.

4. Open "ToolFrontEnd Panel" with ResEdit. Change the file type from 'Panl' to 'PanL'. Save.
5. 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:
   1. Open ToolServer's Tools folder. There is one file called "RMetrowerks".
   2. Move RMetrowerks to Tools folder of MPW. MPW folder must be at "Metrowerks:Codewarrior MPW:MPW" if you installed Codewarrior Heaven.
   3. Remove ToolServer's Tools folder.
   4. Now create an alias of Tools folder in "CodeWarrior MPW" and move it to your ToolServer folder. Rename the alias (probably called "Tools alias") to "Tools"
   5. 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.
6. After installing the MacPerl MPW Tool distribution (run the InstallerVISE application), in the "MacPerl ƒ" folder, there will be an MPW tool named "perl". Install this in MPW's tools folder.
7. Install the MacPerl Application (run the InstallerVISE application). 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 going under the Edit Menu to Preferences. Click on the "Script" button and hit the radio button "Run Scripts opened from Finder"
8. Install the "patch", "MakeStub", "NewAlias" and "StreamEdit" Tools in the tools folder. Note that "MakeStub" and "StreamEdit" are automatically installed by the "CodeWarrior Heaven" install option.
9. Install RunTSScript (found in the Mozilla source distribution) in the compilers folder in your build environment ("Metrowerks:Metrowerks Codewarrior:Codewarrior Plugins:Compilers")
10. Next, after downloading all the 3rd party software components, drag WASTE, CWASTE, Menu Sharing, Mercutio, Internet Config, and the AEGizmo folders (just as they are) into the "MacOS Support" folder in your build environment.
11. Start ToolServer from within CodeWarrior (or use MPW if you are brave enough). We're about to patch some files. Make sure the ToolServer menu is in the CodeWarrior menu bar by turning on the preference under the "Extras" panel in the IDE Preferences (not the project preferences!). The menu bar should look like this:

    

    Choose "Start ToolServer" from the ToolServer menu (this is the icon menu between "Window" and "Help" in the menubar above). You will now see a window with no close box. This is your ToolServer Worksheet where you will type (or cut & paste) the commands for the following steps.

    In case you have never used MPW/ToolServer before, the following is very important. Pressing "return" does not execute commands like you might think. It just inserts a newline into the worksheet like a normal text editor. To actually get ToolServer to execute the command, you must press "Enter" (lower right of numeric keypad). This executes the line that the cursor is on, and only that line. If you want to execute multiple lines at once, select them all and hit Enter.

12. Set the shell variables {IDE} and {Source} to the correct paths for your build environment. {IDE} is where your CodeWarrior IDE is located. {Source} is the folder containing the toplevel "ns" folder of the Mozilla source. Mine look like this (don't forget to keep the quotes if your path includes spaces), yours will almost certainly be different (to punctuate this, the things you need to change are in red).

    Set IDE "Develop:Source331 Build Environment:CW Pro 2:Metrowerks CodeWarrior:"
    Set Source "Source:FreeSource:"

13. If you are using CWPro2, execute the following lines to patch LDropFlag to draw correcly over non-white backgrounds.

    directory "{IDE}MacOS Support:PowerPlant:_In Progress:_Table Classes:"
    patch LDropFlag.cp "{Source}mozilla:lib:mac:patches:LDropFlag.patch"
    duplicate -y "{Source}mozilla:lib:mac:patches:DropFlag Icons.rsrc" "{IDE}MacOS Support:PowerPlant:PowerPlant Resources:"

14. Execute the following lines to patch menusharing.c to allow it to compile with the new Universal Headers. It references an obsolete header file (GestaltEqu.h).

    directory "{IDE}MacOS Support:Menu Sharing Toolkit 4.1:"
    patch menusharing.c "{Source}mozilla:lib:mac:patches:menusharing.patch"

15. If you are using CWPro2 straight off the CD, you need to patch AppleEvents.r to fix a problem with the Universal Headers (the definition of the 'aedt' resource was omitted). You do not have to do this if you have applied the netborne patch to Pro2e because it has been fixed.

    directory "{IDE}MacOS Support:Headers:Rez Headers:"
    patch AppleEvents.r "{Source}mozilla:lib:mac:patches:AppleEvents.r.patch"

16. You need to patch stat.mac.h to fix a problem in MSL where lines were omitted.

    directory "{IDE}Metrowerks Standard Library:MSL C:MSL Mac:Public Includes"
    patch stat.mac.h "{Source}mozilla:lib:mac:patches:stat.mac.h.patch"

17. Congratulations! Now you are ready to build. Once these steps are done, you don't have to repeat these setups the next time!

2.4 Run the build

In the folder mozilla:build:mac:, there are several Perl scripts with names of the form BuildMozillaXXX.pl, where XXX is "Optimized", "Debug", "Tinderbox", et al. Each script builds the corresponding version of Mozilla. If you configured the MacPerl application to execute scripts that are opened from the finder, all you have to do is double click on the appropriate one; otherwise, launch MacPerl, and run the appropriate script from the "Run Script..." menu item.

These `configured build' scripts are simple, and you might want to make your own to force your build to StopForErrors(), or alternatively DontStopForErrors(), et al. You can set up certain build-script variables and (soon) compile-time flags. Compare the supplied scripts to figure out what you might want. Note that CodeWarriorLib, Moz.pm, and BuildList.pm, are AppleScript libraries and Perl modules meant to be used by a `configured build'. Use your favorite POD viewer (Shuck comes with MacPerl) to view the documentation in the Perl scripts.

If there were any errors in any of the projects along the way, the script will stop at that point and the IDE will tell you the errors. You can fix them and make sure they current project builds, but to continue the automation, you have to start from the beginning by double-clicking the script again. This isn't quite as bad as it sounds because the previous projects are already built (unless you changed some major header file). Please note that stopping the script once it has started is difficult. We are working to address this issue.

After the build is complete, you can find aliases to the built libraries and the final Mozilla application. Debug builds are built to Mozilla:dist:client_debug, while optimized builds are built to Mozilla:dist:client.

Don't worry too much about the numerous warnings generated during the build. We try our best to get the XP teams to use real compilers, but alas, they continue to write warning-laden code. There is also some generated code (Java is one example) that has a lot of warnings that we can't help either. If you write any new code, please help us in our quest to get zero warnings.

3. Common Sticking Points

• I have CodeWarrior3, how do i build with it?
  Currently, the answer is, "You don't." Eventually, the distribution will be modified to allow building using CodeWarrior3, but for now CodeWarrior2 is the only IDE that is supported.

4. Credits

The majority of this document is taken from the build document included in the Mozilla source distribution at README:mozilla:macbuild.htm written by Mike Pinkerton, pinkerton@netscape.com.