Back to the main page

How to build Classilla

This is mostly based on this old Mozilla document with my own notes. These build instructions are intimidating, but they do work, and once you have it set up you obviously won't need to do it again.

Prerequisites

Hardware/OS

The build environment is currently only supported on OS 9.0.4 and higher (9.1 or 9.2 recommended). It will probably build on OS 8.6 but this is considered serendipitous. I haven't tested trying to build on OS X and it would probably require some radical changes anyway.

You should have ample RAM and CPU: a G4 and at least 256MB is recommended. Classilla's development machine was a FW400 MDD Power Mac with dual Sonnet 1.8GHz G4 7447A processors and 2GB of RAM (1.5GB available to OS 9) with virtual memory off running Mac OS 9.2.2. A simple relinking took about 15 minutes; a complete build from utter scratch needed around 80 minutes. Do the math for your own box.

Software

Classilla is built with Metrowerks CodeWarrior Pro 7.1, with a portion using the Macintosh Programmer's Workshop (MPW). It will probably build with later versions of CW Pro, but almost certainly not with earlier ones without converting the MCPs (and possibly not even then). The reason CW Pro 7.1 was chosen is it is fairly easy to find/purchase used.

You should not have multiple copies of MPW on your build system; only use the one that comes with CodeWarrior. If you install multiple MPWs, you will have multiple ToolServers which can cause your build to fail inexplicably.

To properly install the CodeWarrior environment:

I also suggest installing a copy of Make SMI or some similiar drag-and-compress tool for running off complete builds, as it makes packaging for distribution much easier.

Build automation is operated with a complex MacPerl script which functions essentially as the make system. Again, this is all largely one-time steps. All files are also available from the Floodgap Gopher server.

The old Mozilla documentation makes reference to static builds, but we don't support those.

How to compile

If you did all this right, go into mozilla:build:mac:build_scripts and double-click BuildMozilla.pl. Perl will start up and start CodeWarrior in the background, and then do the following:

Congratulations, it built

Yay, you did it (probably)! Test your build by going to mozilla:dist:viewer and double-clicking Classilla. If it starts, congratulations. You might want to try running it in the CodeWarrior debugger by opening the _apprunner.mcp project, choosing the apprunner Target and selecting Debug from there if you are not sure that it will be stable on your system.

When you do future builds with a partially built system, you don't need to wait the full 90+ minutes to do the build; only the parts that need to be updated will be done. You can also build shared libraries directly from their own individual CodeWarrior projects without invoking the entire build process, which is much quicker, and they will be incorporated into your test Classilla simply by quitting and restarting the browser.

Old Mozilla hands will wonder where the part that converted the exported XML project files into MCPs went. It's still there, but the MCPs now come pre-converted since everything is only being built on Mac CodeWarrior.

Running off a standalone build

To make a Classilla that can run on a different computer, it is not sufficient to merely copy the Classilla executable as the shlbs must come along with it. To make this process easier, Classilla includes ClassillaGenerateDist.pl that finds all the dependencies, copies them and groups them into a folder that you can immediately copy away. The only problem is that this can mess up your alias structure if you're not careful. I recommend:

9.0.4 also adds ClassillaPackageDist.pl which tries to make a CFM application package that is compatible with OS 9. This package seems to have trouble running on OS X, however, which is why it is still not the default build and should be considered experimental. It also won't work on OS 8.6, but should still open and be executable with the alias inside.

Troubleshooting

Debug builds don't work.

Yup, they definitely don't. Don't try to run BuildMozillaDebug.pl unless you want to fix it.

Carbon builds don't work.

Yup, they definitely don't. The code is still there, so it should be possible to convert to Carbon, but there may be some non-Carbon functions in use.

The build script can't find CodeWarrior.

Trash CodeWarrior IDE Path.txt and see if the script can re-detect it.

I want the build to start over but it keeps starting in the middle.

There is a build progress file dropped in the root source directory enclosing mozilla. Delete that.

During the manifest stage, I see several spurious errors.

This is normal for the Mac OS 9 build. They are harmless.

MacPerl freezes when starting CodeWarrior for the first time.

Switch to CodeWarrior and keep it in the foreground. MacPerl's event handling gets a little daft if it's foregrounded. It's also a lot faster if you keep CodeWarrior front, at least until you get to Stubs (see below).

CodeWarrior freezes while building stubs.

Make sure RunTSScript got installed correctly, but even if it is, CodeWarrior sometimes can't start ToolServer if it's the front process. Switch to the Finder and it should start up or go clicking around the screen to prime the Apple Events chain. You might need to do this again even after ToolServer starts, because to build the stubs ToolServer has to run twice. A tool like LiteSwitch is perfect for this, btw; just go switching into random other apps to flush Events and unstick the process.

Alternatively, this sometimes happens if you have ToolServer running before the script expects to start it up. Stop the script, stop ToolServer, and restart the build.

In general, I find that the stubs build most reliably if you start the build script and then don't touch anything until stubs are built. Then you can go do something else while it continues.

When you get stubs built properly for the first time, you might want to comment BuildStubs() out of the build .pm so that you don't have to build it again; they are unlikely to ever change and just represent the most likely way the build process can go wrong.

The runtime will not build (compiler or linker errors).

This usually means the stubs are defective. Look in mozilla:dist:client_stubs and check the size of NSStdLibStubs (should be around 24K) and InterfacesStubs (should be around 300K). An abnormally small NSStdLibStubs (8K or less) usually indicates a bad stub and means ToolServer probably did not run. Use ToolServer to try to dump the stub with DumpPEF if you're not sure. (Ignore InterfacesXStubs, this is a holdover from Fizzilla and irrelevant to the standard configuration.) Make sure that you installed RunTSScript, PowerPlant and any other libraries correctly as well.

Also, some people have reported problems with 3.4.1 Universal Interfaces' ContextualMenu stub library. If your NSStdLibStubs and InterfacesStubs appear good and look valid to DumpPEF, replace it with the one from 3.3.2 and see if that helps. You may need to completely rebuild the stub libraries for this to take.

CodeWarrior can't find a lot of .h files but they are there.

Usually means (a) bad alias(es). Run ClassillaFixAliases.pl and make sure everything points where it should. This typically occurs the second time around.

CodeWarrior freezes up while building large shlbs.

It's probably not frozen actually. For things like the layout shared library, the optimization step may take as long as several minutes on slower or more memory-impaired systems. During this process your computer may appear to lock up. Just be patient.

Btw, this is not improved by giving CodeWarrior more RAM in Get Info. In fact, you may make this worse by taking away temporary memory from the system, which is what CodeWarrior grabs during the compile process. However, you may get more oomph out of this by putting in more physical RAM and turning off Virtual Memory.

There sure are a lot of warnings.

There sure are. (The record is layout: from a fresh build you may see nearly 3000 warnings, and even from a simple relinking you get a minimum 2k.)