# How to build Classilla This is mostly based on [this old Mozilla document](http://www-archive.mozilla.org/build/mac_cfm.html) 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: - Run the CodeWarrior installer(s) and select a stock full Mac C/C++ installation (Mach-O is not required; you can install that and/or Win32 if you want). Make sure that PowerPlant, the CodeWarrior Plugin SDK and CodeWarrior MPW are installed. - Download the Classilla source from either [SourceForge](https://sourceforge.net/projects/classilla/files) or [the Floodgap Gopher server](gopher://gopher.floodgap.com/1/gopher/clients/mac/classilla/source). - Unpack the Classilla source. *This is in the ballpark of 30,000 files. It is strongly recommended you do this on a separate, HFS+-formatted partition or disk other than your boot volume.* - In `mozilla:build:mac`, find `RunTSScript` and make sure it is a CodeWarrior plugin with Get Info (if not, drop it on StuffIt Expander and rename the resulting AppleDouble file back to RunTSScript). Put it in `CodeWarrior Plugins:Compilers`. Current versions of the Classilla source have this already converted for you. - Enable the ToolServer menu (it looks like the Amiga window gadget) in the CodeWarrior IDE preferences. Make sure it can start ToolServer. Make sure all the ToolServer tools show up (in particular MakeStubs and DumpPEF). If not, chase down all the Tools folders, remove extraneous ones, and alias them to point to a central folder. This is critical for stubs. - The following libraries are needed if you don't already have them. They go in the `MacOS Support` folder as part of CodeWarrior. If you can't find them, they are available from [the Floodgap Gopher server](gopher://gopher.floodgap.com:70/1/gopher/clients/mac/classilla/source/tools). - Menu Sharing Toolkit. This is part of MacBird. Unpack MacBird's source code, then copy the MST portion into `MacOS Support:Menu Sharing Toolkit:` - ICProgKit. Unpack into `MacOS Support:ICProgKit1.4:` Later versions may work. - AEGizmos 1.4.2. Unpack into `MacOS Support:AEGizmos 1.4.2:` This used to be required, and may still be required for building direct from Mozilla code, so you may still want to install it. Later versions may work. - Universal Interfaces. 3.4.1 should already be under `MacOS Support:Universal:` but read on for why you may need 3.3.2. - WASTE should already be under `MacOS Support:(Third Party Support):WASTE 2.0 Distribution:` - Although I offer them for other purposes, you do not need to install GUSI, `zlib` or `libpng` separately; Classilla already comes with its own copy of what it requires. Do not link Classilla against any other version of these libraries that you might have on your system (the project files by default will prevent this). 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](gopher://gopher.floodgap.com/1/gopher/clients/mac/classilla/source). - Install MacPerl 5.2.0r4; I haven't tried 5.6.1 but I don't see any reason why it wouldn't work. There is no 5.8 or 5.10 for classic MacOS. You can install it anywhere convenient. - If you use 5.2.0r4 you will also need `cpan-mac` 0.50 or higher. This is allegedly not required for MacPerl 5.6.1, but YMMV. - Configure your Perl (follow the steps in this order): - Set the memory partition for MacPerl to at least 18MB in the Finder (under Get Info). Restart MacPerl if needed. I have mine set to 32MB just in case. - Create a folder called `site_perl` in the same folder as MacPerl. - In MacPerl's preferences, add that folder `site_perl` as a search path. - In MacPerl's preferences, also select "Run scripts from the Finder" instead of "Edit" them. It's a lot more convenient and you should probably do your editing in BBEdit anyway. - If you need to install CPAN, download and decompress it, and double-click `INSTALL.plx`. It will install to `site_perl` automatically. When it asks if you want to install the droplets, answer "Yes" (you'll need them for the next step). - Next, install the following modules. *Do not attempt to unpack them.* Drop them onto the CPAN installer `installme.plx` droplet instead and they will be properly CRLF-ed and installed into the library directory. If it asks to convert all text and MacBinary files, answer "Yes." The parenthesized version is the one in use on the build system. - `Compress::Zlib` built for MacPerl (1.04) - `Archive::Zip` built for MacPerl (0.11) - `Mac::AppleEvents::Simple` (0.10) - `Mac::Apps::Launch` (1.30) - Find the `site_perl` folder you created above. From the Classilla source, look in `mozilla:build:mac:build_scripts` and manually copy the `Moz` folder there into `site_perl` (you could also put it in `lib` but this is non-standard and not recommended). This installs the Mozilla-specific Perl modules needed to talk to CodeWarrior and automate the build. - Find the `Mozilla build prefs` folder (this should be in the root, _not_ under `mozilla`). Drag this folder into your `System Folder:Preferences` folder. This is preconfigured for the options still supported in the Classilla build system. - Run `ClassillaFixAliases.pl` in the root folder. Ignore files it can't find for now. Resolve any ambiguous duplicates. This ensures that the current header files are in sync with their aliases. 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: - Manifest stage, where it determines what will be copied where. - Builds the `xpidl` tools to compile IDLs and headers. These are automatically installed for you under CodeWarrior. *The very first time you try to do a build, it will die after this point because CodeWarrior won't register the tool without a restart. Quit CodeWarrior and MacPerl, then restart the build script. You should never see this again.* If you can't get past this point, your CodeWarrior is not set up right and you should go through the directions above again to figure out why. - Compiles the IDLs and headers. If you can't get past this point, there is something wrong with the `xpidl` project file, or you didn't install the Plugin SDK. - Compiles the OS stub library. This is a critical and somewhat iffy step. If you have multiple ToolServers, or your ToolServer cannot see all the tools it needs, you may fail at this point (or possibly slightly later when CodeWarrior tries to link against the defective stub). If ToolServer doesn't even start, you probably blew it installing RunTSScript, or failed to convert it into a proper plugin that CodeWarrior will recognize. You might also have forgotten PowerPlant or have incomplete libraries. - Compiles the runtime. If this fails, it may also be the stubs. - Compiles the crossplatform code. This is the longest part of the build process. If the first few shlbs come off like winners, you are likely to complete the build successfully. - Compiles the actual application (`apprunner`). - Links in and jars chrome resources. If this bugs out, make sure you installed all the proper Perl extensions (particularly `Archive::Zip` or the build script will be unable to make the jar files). ## 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: * When preparing to run off a standalone build, run `ClassillaFixAliases.pl` and make sure that all aliases are valid and pointing to valid files. Fix any ambiguities and make sure aliases that were not found are corrected before proceeding. * Run `ClassillaGenerateDist.pl`. In the `mozilla:dist:` folder will be a `_RTM Package` (formerly `Classilla` -- the underscore is a space) folder containing a completely standalone set of files. You can rename and drop this folder on Make SMI or DropStuff to create an archive, or copy it to another system. The folder contains the Classilla readme and Classilla itself in an enclosing folder (the readme comes from the `Classilla Dist Resources` folder; you can put other things in there too you want rolled in). * When this is done, *delete the Classilla standalone distribution folder*, empty the Trash and re-run `ClassillaFixAliases.pl` to make sure the aliases are still correct and have not been tainted to mistakenly point into the Classilla standalone directory which you just deleted. Some aliases might not be resolvable. Don't worry about that. 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.)