A.2. Building the Source Code
Now that you have the Mozilla source code, what do you do with it? Unlike the Mozilla binaries that are available for download, you can not start using Mozilla once you have all the source code on your computer. Before you can start using the source, you need to set up your working environment and then build Mozilla.
For the Mozilla source to compile on your computer properly, two main aspects of your build environment must be set up. These aspects are the necessary tools and the proper environment variables. You would expect such a large code base to require a large number of tools, but there aren't so many. Table A-1 lists the tools you need to build and run the source code. All information here is presented in more detail at http://www.mozilla.org/build/, including links for getting the tools.
Table A-1. Platform tools used to build the Mozilla source code
|
Linux |
Windows |
Macintosh |
|---|---|---|
|
egcs 1.0.3 (or higher), gcc 2.95.2 |
Microsoft Visual C++ Version 6.0 or later (with service pack 3) |
Code Warrior Pro 7 (including Plugin SDK) |
|
GTK+ / Glib 1.2.0 |
Cygnus toolkit for Windows (the build page lists the specific components) |
Menu Sharing Toolkit 1.4 |
|
GNU make 3.74 |
Netscape Wintools (modified versions of gmake, shmsdos, and uname) |
ToolServer |
|
Perl 5.005 (or higher) |
Perl5 for Win32 |
MacPerl cpan-mac distribution Perl AppleEvents module Perl Launch module |
|
zip 2.3 (or higher) |
Zip for Win32 |
Compress:Zlib module Archive::Zip module |
|
LibIDL 0.6.3 (or higher) |
(Required for static build) XML::RegExp XML::Parser XML::DOM | |
|
Autoconf 2.12 (optional) |
The Linux environment is usually set up by default with all the tools listed for that platform; it therefore requires less time to retrieve and set up programs. Linux distributions usually come with a native compiler that is compatible with the Mozilla build system. Most build time is used compiling the C++ source code -- the language most files are written in. Therefore, the compiler is the central component of the build system. Linux uses egcs or gcc, Windows uses Microsoft Visual C++, and Macintosh uses Metroworks Code Warrior. The latest version of CVS for each platform accompanies all tools listed in Table A-1.
You can set various environment settings for each platform to configure and optimize your build environment. Most settings are optional and some are essential. One essential is the CVSROOT variable, which tells the CVS server where to look for the tree's home or root. The next section looks at the differences between the Unix, Windows, and Macintosh platforms.
A.2.1. Unix Environment
Unix is probably the easiest platform to configure. In fact, because it's a developer's platform, it is designed to work with little or no user interaction. In the source tree, script is provided to do all the work for you. To run it, you need only the following steps:
> cd mozilla > ./configure
Running this command gathers all necessary system information and the list of Makefiles needed to compile the source. This command needs to be run only when a Makefile is added or removed from the tree. After this, it is sufficient to compile Mozilla by launching gmake with no arguments.
Alternatively, you can use the Unix Build Configurator, an online tool (http://webtools.mozilla.org/build/config.cgi) that lets you change certain settings if you run into any obstacles when building. It allows setting external package configuration, a choice of Mozilla components, and debugging and optimization options. Once this setting is made, let Mozilla take over via the client.mk script:
> gmake -f client.mk
One useful post-build setting is the ability to run Mozilla from any directory (rather than just dist/bin). To test this option, use MOZILLA_FIVE_HOME to point to the full path, to the dist/bin, or wherever your executable resides.
A.2.2. Windows Environment
The setup is different on Windows and requires more interaction on the user's part, mostly in setting up environment variables. Table A-2 lists these variables and expected values. Note that some values are optional.
Table A-2. Windows environment variables used to build Mozilla
|
Variable |
Value |
Description |
|---|---|---|
|
MOZ_BITS |
32 |
Specifies whether you use a 16-bit or 32-bit operating system. |
|
MOZ_DEBUG |
1 (optional) |
Set only if you want a build with debug information. Remove this variable to enable it by default. |
|
MOZ_SRC |
<path to top of source tree> |
The directory into which you uncompress or check out the Mozilla source. Ensure that the path does not end with a trailing slash (\). |
|
MOZ_TOOLS |
<usually the Cygwin root directory> |
The directory where gmake is installed, usually placed there by the wintools.zip package (refer to Table A-1). |
|
WINOS |
%OS_TARGET% (see the OS_TARGET variable) |
An abbreviation for the operating system that is also used internally by the OS. Windows 2000 takes a value of WINNT. It matches the top-level directory on the filesystem that contains all OS files. |
|
OS_TARGET |
WINNT (or WIN95) |
A Mozilla representation of the OS_TARGET variable |
|
_MSC_VER |
1200 (or 1100 for VC++ 5) |
The version of the Microsoft Visual C++ runtime environment running on your machine. The value of 1200 is Version 6, the most reliable version. |
|
DISABLE_TESTS |
1 (Optional) |
Set only if you do not want to build test directories and binaries. Remove this variable to leave it enabled by default. |
|
MOZ_DISABLE_JAR_PACKAGING |
1 (Optional) |
Set only if you want to turn off compression into the chrome structure's JAR files. Remove this variable to leave it enabled by default. |
|
MOZ_CONFIG |
<path to config file> |
This variable is required only for gmake builds. |
|
PATH |
%PATH%;%MOZ_TOOLS%\bin;c:\cygwin |
The PATH variable is an existing variable that needs the Cygwin root and binary directories appended. The operating system looks at this variable when looking for program executables and DLLs. |
You can set these variables either by using the set command for per session variables or the System > Advanced > Environment Variable panel in Control Panel to set them more permanently.
 | Once your environment is set and the tools are in place, you can begin the build. Go to the mozilla directory in the source code and from there, run the make script (client.mk) with the necessary arguments: >make -f client.mk build_all |
Once your environment is set and the tools are in place, building can begin. Go to the mozilla directory in the source code and from there, run the make script (client.mak) with the necessary arguments:
> nmake -f client.mak build_all
Table A-3 lists these arguments and what they do. Leaving out this compile flag starts an incremental build or a fresh build if there is no previous build available.
When building incrementally, try to use the provided make script instead of the cvs checkout and build_all commands. The latter command can lead to inconsistencies in file versions and may re-download files that you do not even need to your tree.
Table A-3. Make flags
|
Flag |
Function |
|---|---|
|
pull_all |
Gets only the source code. |
|
build_all |
Builds only the existing source code. |
|
pull_and_build_all |
Retrieves the source code and then builds it. |
|
pull_and_build_all_dep |
Does a dependent build after retrieving the source code. The source tree is not accessed in a dependent build. |
|
pull_ clientmak |
Pulls only the latest version of the build file client.mak. |
|
clobber_all |
Deletes all files produced from a previous build to enable a completely fresh build. |
|
Pull_xpconnect |
Retrieves the XPConnect module. You can retrieve other modules this way, including nspr and psm. |
To rebuild without pulling the tree, use:
> make -f client.mk build_all_depend
To get or update the source code and not build, use:
> make -f client.mk checkout
A.2.3. Macintosh Environment
In terms of environment setup, necessary resources, and actual compile time, the Mac OS is the least straightforward of the three major platforms Mozilla builds on. There are several different kinds of Mac builds at mozilla.org, but this section focuses on just two: the Classic Mac OS 9's standard build, which has been the default for a long time, and Mac OS X's Code Fragment Manager (CFM).
Mac OS X builds are becoming more popular as the platform is adopted more widely. Better performance and native Unix build system tools have boosted developer support for Mozilla on Mac OS X. However, the Macintosh is by far the most resource hungry of all platforms Mozilla builds on. The minimum specification includes 1 GB of disk space and 128 MB of memory, but you will probably need even more in reality.
To compile the source, check out the module mozilla/build/mac/build_scripts. Once the download is complete, go to the folder and run BuildMozilla.pl for an optimized build or BuildMozillaDebug.pl for a debug build. Running the CodeWarrior environment during or before running build scripts is useful. When you run the build script, you will be asked for the location of CodeWarrior, if it is not already running. You can change some build options through a local preferences file, which can be found in the system preferences folder for system variables or at the root of the Mozilla tree for tree-specific variables. You can find more information on fine-tuning the build at http://www.mozilla.org/build/mac-build-system.html.
When the compile is complete, you need to take an extra step to start it. Mozilla needs certain things set properly so it can gather the information it needs at runtime. Traditional Mac OS systems have no concept of environment variables per se, but one alternative is to use a startup file called NSPR Logging that comes with Mozilla in the same directory as the application. Its lines are in the following format:
ENV:NSPR_LOG_MODULES=nsComponentManager:5 ENV:NSPR_LOG_FILE=xpcom.log
Dragging this file onto Mozilla starts the application with those settings. You can edit this file by adding or changing the ENV lines or make another file. This modification method is useful for single session settings. For more permanent settings, you can create a file called ENVIRONMENT and put it in the same folder as Mozilla. Mozilla picks up the environment variables in the ENVIRONMENT file when it runs. The file contents look something like:
NSPR_LOG_MODULES=nsComponentManager:5 NSPR_LOG_FILE=xpcom.log
The Mac OS X CFM version uses the same build system as OS 9. If you build, you need to adjust the following setting in order to build with Carbon, which is a set of APIs that transition developers from OS9 and earlier releases to the new OS X system architecture:
In your Prefs folder, add the following line to the Mozilla[debug/opt] build prefs file:
options carbon 1
For more information on pulling the Mozilla source on OS X, the OS X build process, and other OSX Mozilla resources, see http://www.mozilla.org/ports/fizzilla/.