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

- MacFE - the Macintosh front end, including all the things you see and some you don't.
- XP - cross platform back end code, mostly written in C. You will see this used like, "This is an XP problem" which means it's broken everywhere.
- MW - Metrowerks Corporation. They make our build tools (CodeWarrior) and PowerPlant
- PP - PowerPlant, the GUI framework on which our app is built
- CWProX - CodeWarrior Pro version X. You'll probably see CWPro1, CWPro2, and CWPro3. We may also just refer to this as CW.
- IDE - Integrated Development Environment. CodeWarrior is an IDE.

### Building

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

- 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

Here's a list of other build tools that you need to install in order to build and where to get them:

- MacPerl 5 MPW Tool
- 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 (ns: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.
- ToolFrontEnd
- patch 2.1

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:

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

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:

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:

    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.

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

    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.

    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)

    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:

- BuildMozPPCList.txt
- BuildMozPPCDebugList.txt
- BuildNavPPCDebugList.txt [ might work ]
- BuildNavPPCList.txt [ might 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.

##

Unfinished "Features"

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

##

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:

- ns:cmd:macfe:rsrc:CrossProduct:Mozilla_Custom_CPPbs
- ns:cmd:macfe:rsrc:Communicator:MailNewsCppbs.cnst

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

- ns:cmd:macfe:rsrc:CrossProduct:Mozilla_Custom_TMPLs
- ns:cmd:macfe:rsrc:CrossProduct:Other_Comm_TMPLS.rsrc

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

- Built using Metrowerks PowerPlant, the client has been PPC native from day one. 68K support was dropped in 5.0 due to the high cost of maintenance. Any takers?
- Mail/News was added in 2.0 and Composer was added in 3.0 (called Navigator Gold). Both were dramatically improved with 4.0.
- Java came to the Mac in 3.0, even though Windoze and unix had it in 2.0.
- Multi-byte language support for inline edit fields added in 4.0
- The preferences used to be STR# resources. Now they are done in javascript.
- Because of the sheer number of resources (and the "theoretical limit" on the number of resources in a file imposed by the Resource manager -- which we still exceed on a daily basis), a number of strings and icons were moved out of the main application and into a file called "Netscape Resources" in 4.0
- For plain-text email/form composition, we used VText up through 4.0. For 5.0, we switched to WASTE because of its minimal impact on the PowerPlant hierarchy. VText caused us fits every time we wanted to upgrade to a newer version of PowerPlant because it wrapped its tentacles around every limb of PowerPlant.
- 4.0 included a new memory management scheme which drastically reduced the amount of memory used by the client. This is why the memory partition of 4.0 is about half of 3.0.
- A version of Navigator sans Mail/News/Composer debuted with 4.03, and again two days later with 4.03.1.

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

- More NavCenter work
- Solve the issues with too many 'STR ' resources (see note on issues page)
- Modularization (HTML display isolated from networking, etc)
- use new Appearance Manager classes in PowerPlant
- Navigation Services (new open/save dialogs in Allegro) support. We have an ancient SDK and have integrated it in a few places, but the current implemenation that we have doesn't work very well. It's cool, though.
- More drag and drop in composer.
- More support for Internet Config (see note on issues page).
- external Java VM support (MRJ, etc)

Things we would like some help on:

- printing support
- 68K version
- Context Menu Manager support
- bug fixes of any kind
- performance tuning of any kind
- getting around the limitation of 255 hierarchical menus imposed by the OS. This would let us do a "real" personal toolbar with folders that have popup menus.
- Fixing the build system so it uses makefiles without having to give up the CW IDE for source browsing/editing.
- better publishing in Composer
- add NavCenter to Composer window
- better table editing in Composer

Copyright © 1998 Netscape Communications Corporation