MacFE Build Instructions

This is a general document on how to build, what works, what doesn't, and things to watch out for when working on the Mac client. Please read the entire document before you start tinkering...heck, you may just learn something!

Abbreviations you will probably see in this document:

Building

New 5.0 Features

Unfinished Features

Pitfalls

History and Future

Building

What are the minimum machine requirements?

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.

The moral of the story: get lots of physical RAM and don't use VM.

How big of a partition do I need for the source?

You should be ok with a 400MB disk partition, even when fully built. This does not include tools like the IDE, just source.

Why do I need CWPro2 or better?

We use CodeWarrior as our development environment at Netscape for the MacFE. All of the projects and tools are geared towards the CodeWarrior IDE. In addition, we make heavy use of PowerPlant and MSL which you can only get from Metrowerks.

While we say you need at least CWPro2, you may be able to get by with Pro1, but probably not for very long. We haven't tested it, so we don't recommend it. Get the upgrade. CodeWarrior kicks serious butt!

How do I setup my development environment?

Here's a list of 3rd party software that we compile into the application and where to get it: Here's a list of other build tools that you need to install in order to build and where to get them: Once you have all the pieces, here are the steps required to put everything together:
  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:
    4. 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.

    Open "ToolFrontEnd Panel" with ResEdit. Change the file type from 'Panl' to 'PanL'. Save.

  4. Uncompress the StuffIt Archive for ToolServer. Place the ToolServer folder in the same folder as your CodeWarrior environment (its actual placement is not important). Create an alias from the Tools folder that lives in the CodeWarrior MPW distribution and place it in the ToolServer folder. Now ToolServer and MPW will share the same tool set and you only have to maintain one tool repository.
  5. After installing the MacPerl distribution (run the InstallerVISE application), in the "MacPerl €" folder, there will be an MPW tool named "perl". Install this in the same location as the rest of the MPW tools for ToolServer.
  6. Install the "patch" and "MakeStub" MPW Tools in the same location. Note that "MakeStub" is automatically installed by the "CodeWarrior Heaven" install option.
  7. Install RunTSScript (found in the Mozilla source distribution) in the compilers folder in your build environment
  8. 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.
  9. 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:

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

  10. 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:
    11. Set IDE "Develop:Source331 Build Environment:CW Pro 2:Metrowerks CodeWarrior:"
Set Source "Source:FreeSource:"
  11. If you are using CWPro2, execute the following lines to patch LDropFlag to draw correcly over non-white backgrounds. You do not have to do this if you are using Pro3 because it has been fixed.
    12. directory "{IDE}MacOS Support:PowerPlant:_In Progress:_Table Classes:"
patch LDropFlag.cp "{Source}ns:lib:mac:patches:LDropFlag.patch"
duplicate -y "{Source}ns:lib:mac:patches:DropFlag Icons.rsrc" "{IDE}MacOS Support:PowerPlant:PowerPlant Resources:"
  12. 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).
    13. directory "{IDE}MacOS Support:Menu Sharing Toolkit 4.1:"
patch menusharing.c "{Source}ns:lib:mac:patches:menusharing.patch"
  13. 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 Pro2 or are using Pro3 because it has been fixed.
    14. directory "{IDE}MacOS Support:Headers:Rez Headers:"
patch AppleEvents.r "{Source}ns:lib:mac:patches:AppleEvents.r.patch"
  14. You need to patch stat.mac.h to fix a problem in MSL where lines were omitted (both CWPro2 and Pro3 share this problem)
    15. directory "{IDE}Metrowerks Standard Library:MSL C:MSL Mac:Public Includes"
patch stat.mac.h "{Source}ns:lib:mac:patches:stat.mac.h.patch"
  15. If you are using CWPro3, you have to unstuff and copy the old Grayscale Appearance classes into the PowerPlant hierarchy. As of Pro3, they are now obsolete and are located with the rest of the obsolete PowerPlant files. We'll fix this shortly.

Ok, so how do I build?

There is an AppleScript called BuildList located in ns:cmd:macfe:projects. This droplet takes, as input, a text file which lists the projects in the order which they are to be built. This allows us to build different versions of the product just by dropping a different "script" on BuildList (such as Debug, Optimized, Navigator stand-alone, or navigator + composer).

These scripts are located in ns:cmd:macfe:projects:client and have names like BuildMozPPCDebugList.txt. This script will build a debug version of Mozilla (navigator + composer) for PPC. Get it? Good. All you have to do is drag this script to the BuildList droplet and watch it crunch away. Now go out to dinner. By the time you get back, you should have an executable in ns:cmd:macfe:projects:client called, for this particular script, MozillaPPCDebug. You will see the following build lists in the client folder, but as of 3/31, only BuildMozPPCList.txt and BuildMozPPCDebugList.txt are guaranteed to work:

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 dropping the script onto BuildList. This isn't quite as bad as it sounds because the previous projects are already built (unless you changed some major header file).

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.

How long does it take to build?

On a G3 with the source and IDE on a RAM disk, it takes about 25 minutes. On a PowerTowerPro 225 and everything on the hard drive, it takes about 45mins to an hour. On a 9500/132 it takes over 2 1/2 hours.

The moral of the story: Don't try this on your 6100/66.

What's special about running the debug build?

Running the optimized (non-debug) version is easy, just double-click it and it will work. This is because all the shared libraries are compiled directly into the application. We don't do this with the debug version to facilitate changing bits in projects other than the main one. This way, you don't have to relink the entire app (which can take a while) to see the changes, just the project that was modified.

As a result, you have to find a way to get all the shared libraries from where they are built (scattered throughout the tree) into the same folder as the app so CFM can find them. Luckily, the BuildList script will create all these aliases for you and put them in the right places!

Another nicety about the debug build is that there is a special "trace" function which can be used to display messages about the state of the application as it runs through certain blocks of code. To see these messages (since the Mac doesn't have stdout or stderr) you need to run an application called TraceMonitor. << where do we distribute this???!?>>

How do I build a 68K version?

For now, you can't. The projects have not been kept up to date and aren't even in the tree anymore. If you would like to create them and get all the exports right with CFM-68K, go right ahead. We will be so happy!

Why use IDE_Options.h when all that is in the project file?

It was originally intended to make sure that all 300 of us at Netscape are using the same environment and compilation flags. If something gets turned on/off by accident in the project prefs, it can introduce a subtle bug that can take days to track down for naught. Having a file that specifies exactly what flags should be used guarantees that this can't happen.

Now that we move to net development, I'm sure you will agree that this is even more important.

New 5.0 Features

We can't present this section until after 3/31/98. Please check back here after that. 

Navigator Center (Aurora)

The Navigation Center (referred to as "Aurora" in press releases) is an attempt to make it easier to access and organize information on the web. The NC unifies Bookmarks, History, Search, and local files into a sequence of workspaces which are accessible from a single location in the browser window. One of the ways the NavCenter diverges from a similar concept seen from our competition is the ability for users to create their own workspaces to organize and store information from both the web and their desktop.

Personal Toolbar

Navigator

Composer Features

Unfinished "Features"

We can't present this section until after 3/31/98. Please check back here after that.  This source release is not of beta quality, hence it will have lots of bugs that a normal beta (or even an alpha) would not have. There are many features which we are not even close to being finished with, let alone knowing what the final UI will be. Here are some things that we know about but didn't have time to get to before the code left the building. Feel inclined to help us out? Grrrrrrreat!

Aurora

Aurora is definitely a work in progress. Here are the bugs that we just don't have time to fix Still major work to do:

General FE Problems

Pitfalls

There are a couple of pitfalls that we have to keep straight when it comes to editing resources.

Why do I keep getting messages about unknown custom types in Constructor?

For starters, make sure you have an alias to the following two files in your Constructor folder: You may have to explicitly open these files up while running Constructor to be able to see the new types, especially for the ones in MailNewsCppbs.cnst. Not sure why yet.

For editing other kinds of resources, we have a TMPL file for ResEdit/Resourcerer. Place these in the appropriate location for your resource editor

Why don't my toolbar buttons work anymore in the browser window?

Because of the way we have the toolbars as CIncludeViews (which work in a similar way to #include in C/C++), the RidL will be messed up if you edit the main browser window PPob. Constructor regenerates this list based on all the controls that are in the view when you save, but because we use CIncludeView, the toolbar buttons aren't actually in the view so the RidL is empty. They will still show up when you build, but they won't do anything because they are not registered with the browser window. Until we fix this, just use Resourcer to replace the incorrectly generated one with an old version. The old version is about 58 bytes long and the new one is about 10 so you should be able to easily tell which is which.

Why are there so many damn resources?

As you may have noticed, we've got too many damn resources. Most of them are 'STR ' resources which are generated at build time and contain all of our cross-platfrom strings. We would like to generate these resources more intelligently (into 1/10 the number of 'STR#' resources maybe) but ran out of time before the source had to go out. Before you rush out and change it for us, stop! There are some constraints on the final solution, mostly to do with i18n and l10n being able to leverage existing work on older product to do new products. If you want to help us out with this, please send us some email and we can have out i18n team talk with you to make sure it gets done correctly!

Why doesn't it work better with Internet Config?

For starters, the main reason why we never drank the IC kool-aid was that there was no support for multiple profiles. Being one of the main features which our competition did not have, we thought this was pretty important. There are rumblings in the IC world that IC 2.0 will support multiple profiles. Great! That still leaves us with the second reason: there are many, many, many preferences that we use that are not reflected in IC. As a result, we already have to maintain prefs for those that are not covered by IC so we can't be totally IC dependent.

Of course, now that the source is free, maybe we can drive the direction of IC to include all of our wacky networking prefs.

Where are all my old 4.0X bookmarks and prefs?

In the process of getting the source ready for distribution, we removed all mentions of "Netscape" from the product. As you may know, the 4.0X preferences are stored in a folder called "Netscape Users." Well, that folder is now called "Navigator Users" and the preference file is now called "Navigator Preferences" instead of "Netscape Preferences."

It's probably best not to use any of your old prefs at this point since some of them rely on security calls that are no longer in the free source product. After you create a new profile (and you will have to when you start the free source), copy your bookmarks.html file from your old profile into the new user profile folder and replace the empty one that's already there (if there is one).

For your old bookmarks to be seen, you must throw away the "NavCntr" folder created in your new profile folder. After you do that bookmarks will be imported into Aurora automagically. Note that changes that you make to your bookmarks in 5.0 will not (as of today) be written back to the Bookmarks.html file, but instead are stored in a database within the "NavCntr" folder. If anything gets corrupted in the NavCenter, you can always throw this folder into the trash and your original bookmarks will be reimported.

Also note that these new bookmarks and preferences are totally separate from your 4.0X prefs.

History and Future

History

Excuse me while I ramble...

Future

There is certainly a lot to do. In order to not duplicate too much work (since we are still working on this full time here at Netscape), I've put together a list of what we plan on doing and what we want to do but probably won't get around to because of time constraints.

Things that we are going to focus on:

Things we would like some help on:
Mike Pinkerton (pinkerton@netscape.com)

Copyright © 1998 Netscape Communications Corporation