Development:Building:Mozilla 1.9.0 Branch

We're directing users to this page instead of the outdated build instructions on the main caminobrowser.org website because the instructions for building Camino have changed substantially in recent months and because we need flexibility to be able to update instructions quickly to cope with changes in the Mozilla and Camino builds.

If you have comments or suggestions, please add them to the Discussion page.

The purpose of this page is to guide you through building and running Camino®. Camino is a stand-alone web browser powered by the Gecko rendering engine. It shouldn't be confused with CHBrowserView, which is just one piece of Camino. If you are new to Camino development, please see our developer introduction for an overview of project conventions and the tools you'll need.

These instructions assume that you are familiar with basic UNIX command-line functionality, such as cd and mkdir. For an introduction to the UNIX command line, please see this tutorial.

Preparing to build: Xcode

Mac OS X 10.3.9 or later and Xcode 1.5 or Xcode 2.1 or later (excluding Xcode 2.4.0) are now required for building Camino. Xcode is included on a separate disk with the purchase of a new Mac and is available as a free download from Apple Developer Connection.

Building on 10.3.9/Xcode 1.5 is deprecated and will not be possible for much longer on the CAMINO_1_5_BRANCH (Camino 1.5.x), MOZILLA_1_8_BRANCH (Camino 1.6) and the trunk.

Installing Mac OS X Cross Development SDKs

Camino requires a custom Xcode installation to build properly: during installation, click the "Customize" button and turn on the "Cross Development" section. If you have previously installed Xcode without this option, run the installer again to add Cross Development before attempting to build Camino. Currently PowerPC builds required the 10.3.9 SDK (MOZILLA_1_8_0_BRANCH/Camino 1.0.x still requires the Mac OS X 10.2.8 SDK on PPC) and Intel builds require the 10.4.u SDK; Universal builds require both SDKs. To build a Universal Camino, you must be running Mac OS X 10.4 or higher and use Xcode 2.1 or higher (excluding Xcode 2.4.0).

Regardless of which version of Mac OS X you are using, we recommend you always upgrade to the latest "point" release of the OS (e.g., Mac OS X 10.3.9 and Mac OS X 10.4.9 as of June 2007) and the latest Xcode version available for that version of Mac OS X (1.5 and 2.4.1, respectively).

Upgrading Xcode

When you upgrade to a newer version of Xcode, be sure to re-install the Cross Development SDKs from the new version. In addition, delete the Xcode header cache in /Library/Caches/com.apple.Xcode.501/SharedPrecompiledHeaders (where 501 is your user ID) before building Camino.

Choosing the correct compiler version on Mac OS X 10.4

If you are building on Mac OS X 10.4 ("Tiger") or later on PowerPC, you must change the default system compiler to gcc 3.3, the compiler used to produce official PowerPC builds. Use the following command:

$ sudo gcc_select 3.3

Be sure to repeat this step each time you install an Xcode upgrade.

Builds on Intel Macintoshes, and on PowerPC Macs running Mac OS X 10.3.9, use the proper compiler versions (gcc 4.0.1, from Xcode 2.1 or later, on Intel, and gcc 3.3, from Xcode 1.5, on 10.3.9) by default, so no changes are needed.

libIDL and glib

Follow the instructions on the Mozilla Mac OS X Build Prerequisites page for installing Fink or DarwinPorts (MacPorts) and using them to install libIDL and glib. DarwinPorts is recommended for Intel-based Macs. If you are using Fink, be sure to remove the /sw directory entirely and reinstall Fink if you upgrade to a new major version of Mac OS X.

Shared Menus Framework

Building Camino also requires that you download and properly install the Shared Menus Framework. The binary that ships with this framework is PowerPC-only and will cause Intel builds (including universal binary builds) to fail. Because of this, building on Intel Macs (or building a Universal Camino) requires building a universal binary of the framework from the source code contained in the Shared Menus Framework distribution. The following steps will walk you through downloading, building (if necessary), and installing the Shared Menus Framework.

1. Download the Shared Menus Framework.
2. Decode the .bin file using StuffIt Expander if necessary and mount the disk image.
3. If you are building a PowerPC-only Camino, skip to step 4; if you are building on an Intel Mac or plan on building a Universal Camino, you will need to follow the instructions below to create a Universal Shared Menus Framework from the included source code.
   1. Copy the SharedMenusCocoa folder from the disk image to your hard drive. You can now eject and discard the disk image.
   2. Open the SharedMenusCocoa folder, and double-click the SharedMenusCocoa.pbproj project inside. This will launch Xcode.
   3. In the dialog that appears, click “Upgrade a Copy” to upgrade the project file to the Xcode 2.1 format. Name your upgraded copy SharedMenusCocoa.xcodeproj.
   4. From the “Project” menu, select “Upgrade All Targets in Project to Native”, and click “Upgrade” in the sheet that appears.
   5. A “Native Target Upgrade Log” window will appear. It may be closed.
   6. From the “Project” menu, select “Edit Project Settings”, and select the “Build” tab in the settings window.
   7. Set “Architectures” to ppc i386 by double-clicking Architectures, typing “ppc i386”, and pressing return.
   8. Add the following four new settings. Settings are added by clicking the “+” button below the settings list. You should add these settings:
      • GCC_VERSION_i386 = 4.0
      • GCC_VERSION_ppc = 3.3
      • SDKROOT_i386 = /Developer/SDKs/MacOSX10.4u.sdk
      • SDKROOT_ppc = /Developer/SDKs/MacOSX10.3.9.sdk
   9. Close the settings window.
   10. From the “Project” menu, choose “Set Active Build Configuration”, and set it to “Default”.
   11. Click “Build” in the project window’s toolbar, and wait for the build process to complete. It should complete successfully with no errors, although some warnings may be produced.
   12. You now have a universal binary of SharedMenusCocoa. Quit Xcode.
4. Install the framework.
   • PowerPC-only builds: copy the SharedMenusCocoa.framework file from the build directory on the disk image and place it in /Library/Frameworks
     You can now eject and discard the disk image.
   • Intel-only or Universal builds: copy the newly-built SharedMenusCocoa.framework from build/Default/SharedMenusCocoa.framework to /Library/Frameworks.
5. You now need to create a reference to the Shared Menus Framework inside the appropriate SDK folder(s). If you are building a Universal Camino, follow the steps for both PowerPC and Intel builds below. Note: recent versions of Xcode will automatically have a link from /Developer/SDKs/*/Library/Frameworks to Library/Frameworks, in which case this step is not necessary (and will cause build failures), so be sure to check before following these steps.
   • PowerPC builds:
     1. Check to see if you have the folder /Developer/SDKs/MacOSX10.3.9.sdk
        If so, proceed to step 2; if not, install the Xcode Cross Development tools as described above.
     2. $ sudo mkdir -p /Developer/SDKs/MacOSX10.3.9.sdk/Library/Frameworks
     3. $ cd /Developer/SDKs/MacOSX10.3.9.sdk/Library/Frameworks
     4. $ sudo ln -s /Library/Frameworks/SharedMenusCocoa.framework SharedMenusCocoa.framework
   • Intel builds:
     1. Check to see if you have the folder /Developer/SDKs/MacOSX10.4u.sdk
        If so, proceed to step 2; if not, install the Xcode Cross Development tools as described above.
     2. $ sudo mkdir -p /Developer/SDKs/MacOSX10.4u.sdk/Library/Frameworks
     3. $ cd /Developer/SDKs/MacOSX10.4u.sdk/Library/Frameworks
     4. $ sudo ln -s /Library/Frameworks/SharedMenusCocoa.framework SharedMenusCocoa.framework

Setting up your CVS Environment

If you are building from the source tarball and never plan to update your Camino source code except by downloading a new source tarball, you can skip this section. Most users should perform these steps, however.

Prepare your CVS client using the following parameters:

• server: cvs-mirror.mozilla.org
• root directory: cvsroot
• username: anonymous
• password: anonymous

If you are using Terminal.app (recommended) and the bash shell (the default for user accounts created under Mac OS X 10.3 or later), the following command will set up and save the above CVS configuration information:

$ export CVSROOT=:pserver:anonymous:anonymous@cvs-mirror.mozilla.org:/cvsroot

If you are using another shell, you will have to use a different command to save the CVS configuration, but all subsequent commands in the checkout and build process are the same. (You can get to a bash shell at any time by typing "bash" at the command line and hitting "return.")

For more information on Mozilla CVS, see Mozilla Source Code Via CVS.

Pulling Source and Building Gecko and Camino

N.B. These instructions will build the “trunk” by default. If you want to build a specific branch (or a release or milestone from cvs rather than from the source tarball), please see the FAQ for changes you will need to make to some of these commands.

If you are building from the source tarball, skip to step 4 of this section.

1. cd into the directory where you would like to keep your copy of the Camino source code (e.g., cd ~/lizard).
2. Pull the main build makefile and configuration directory:
   $ cvs co mozilla/client.mk
$ cvs co mozilla/camino/config/mozconfig
$ cvs co mozilla/build/macosx/universal/mozconfig
   The last file is needed only if you are building a Universal Camino. Please note that if you only want to compile Camino for use on an Intel Mac, you do not need to build a Universal Camino.
3. cd into the mozilla directory that was just created:
   $ cd mozilla
4. In your mozilla directory, create a plain text file called .mozconfig (note the leading period). This file is where you will set up the options for your Camino build. To begin, add the following line to your .mozconfig file (note the leading dot and space):
   . $topsrcdir/camino/config/mozconfig
   

   Universal builds will need to add the following lines immediately after the above line:
   

   . $topsrcdir/build/macosx/universal/mozconfig
ac_add_app_options ppc --with-macos-sdk=/Developer/SDKs/MacOSX10.3.9.sdk
ac_add_app_options ppc --enable-macos-target=10.3
   

   Universal builds must also be built using an OBJDIR; be sure to add an OBJDIR line to your .mozconfig:
   

   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoUni
   

   .mozconfig options

   In addition to specifying ("sourcing") the default Camino (and Universal) .mozconfig files and specifying an OBJDIR, your .mozconfig should also contain settings to configure the type of build, and optionally to speed up builds on multi-processor or dual-core Macs.

   Optimized or Debug Mode Build

   The default settings will create an optimized build of Camino. To build in debug mode (for easier troubleshooting during development), add the following two lines:
   ac_add_options --disable-optimize
ac_add_options --enable-debug

   Please Note: It's important to be aware of whether you've set up .mozconfig for a debug or optimized build, because you must match that setting when building Camino from Xcode. If the settings are not matched, key build variables won't get set correctly and vtables will be out of alignment. The net result is that either you won't link, or you'll crash at startup.

   If you are doing a Universal build, you must do an optimized (non-debug) build, as the Mozilla build system will fail towards the end of an attempt to make a Universal debug build.

   Static or Dynamic Build

   By default, Camino is built dynamically. To do a static build of Camino (which means that most of the components are compiled directly into the Camino binary), you can add the following lines to your .mozconfig file:
   ac_add_options --disable-shared
ac_add_options --enable-static

   Static builds are used for distribution but are not recommended for development.

   Building More Quickly on Dual Core or Dual-CPU Machines

   If your machine has two CPUs or a dual core processor (like the Core Duo), you can take advantage of that while building Camino. Add the following to your .mozconfig file:
   mk_add_options MOZ_MAKE_FLAGS=-j4

   Sample .mozconfig

   Below are some sample .mozconfig files, pre-configured for typical usages.

   Development:

   . $topsrcdir/camino/config/mozconfig
   ac_add_options --disable-optimize
   ac_add_options --enable-debug
   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoTrunk

   N.B. It is not necessary to build a Universal Camino for development (unless you plan on doing evil things that only work with gcc 4 and you need failed builds as a reminder). In fact, the Mozilla build system will fail towards the end of an attempt to make a Universal debug build.

   Single-Architecture Distribution:

   . $topsrcdir/camino/config/mozconfig
   ac_add_options --disable-shared
   ac_add_options --enable-static

   Universal Distribution on a Dual-CPU Mac:

   . $topsrcdir/camino/config/mozconfig
   . $topsrcdir/build/macosx/universal/mozconfig 
   ac_add_app_options ppc --with-macos-sdk=/Developer/SDKs/MacOSX10.3.9.sdk
   ac_add_app_options ppc --enable-macos-target=10.3
   ac_add_options --disable-shared
   ac_add_options --enable-static
   mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoUni
   mk_add_options MOZ_MAKE_FLAGS=-j4

5. Pull source and build:
   • To pull the source and build in one step, use:
     
   $ make -f client.mk
   This will automatically pull the source code from the CVS server and build Camino (including various components of Mozilla that Camino requires). The final Camino build ends up in mozilla/dist (or $OBJDIR/dist).
   
   
   • To pull the source without building, use this command:
     
   $ make -f client.mk checkout MOZ_CO_PROJECT=macbrowser
   You can then build at any time by running make -f client.mk alldep from the mozilla directory.
   
   
   • If you're using the source tarball, use the following instead of the above commands:
     
   $ cd mozilla (if you are not already in mozilla)
   $ make -f client.mk alldep

For more information on the build process, see Mac OS X Build Prerequisites and Mac OS X Universal Binaries in the Mozilla Developer Center.

If your build fails, consult the FAQ section below as well as the Common Build Errors page.

Development

To work on Camino application code, open up the Camino.xcode project (from the camino directory) in Xcode. You can edit code, build, and run from inside of Xcode.

When building with Xcode, make sure your build settings match those in your .mozconfig file: from the "Active Build Style" item in the toolbar, choose "Development" for a debug build, or "Deployment" for an optimized build. If you do not match your settings to your .mozconfig, your build will fail.

Upgrading the Camino project file on Mac OS X 10.4

Because Camino tinderboxen still run Mac OS X 10.3.9, the project file is still an Xcode 1.5-style project, and you will need to upgrade the project file before you can build from Xcode on Mac OS X 10.4. To upgrade your copy of the project file, follow these steps:

• Open Xcode and choose “Open” from the “File” menu
• Browse to mozilla/camino/ and select Camino.xcode
• Choose “Upgrade a Copy” and click the “Save” button in the resulting dialog.
• On Intel Macs, or if you're building a Universal Camino, perform the following three steps as well:
• Choose “Edit Project Settings” from the “Project” menu
• In the “General” tab, select “Mac OS X 10.4 (Universal)” in the “Cross-Develop Using Target SDK” drop-down menu.
• Click on “Change” in the panel that pops up.

Note that whenever Camino.xcode changes, you will need to repeat these steps. Luckily, the project file does not change often.

Widget Code

If you've edited the Cocoa widget code, you can make in mozilla/widget/src/cocoa to rebuild the widget library with your changes. The easiest way to get the new version of the library into Camino to test it is to use cp to copy it into the Camino application package (into mozilla/camino/build/Camino.app/Contents/MacOS/components). (This tactic does not work for static builds, which is why they are not recommended for development.) As an alternative, you can make in embedding/config and mozilla/camino again.

Other changes

If you've changed code only within the camino directory, you can rebuild using Xcode. (Again, make sure your build settings match your .mozconfig file).

If you've changed anything outside the camino directory (aside from widget code — see above), you cannot build from inside Xcode, and will need to make -f client.mk from the mozilla directory.

Updating the source and rebuilding

Since the Mozilla core (Gecko) and Camino code are always under constant development, you will periodically want to update your source tree to stay current and to make sure your code will not conflict with any changes that have happened since you began working. (You will always want to make sure your tree is current before beginning work on the code and before submitting a patch for review.)

Before updating your tree, visit the Tinderbox and make sure that the 2nd, 3rd, and 6th columns are green (these are the Camino trunk builds). Then cd to your mozilla directory and run the following commands to update and rebuild your entire tree:
$ cvs update -dP client.mk
$ make -f client.mk

It's possible in most cases to update only Camino code (unless Gecko changes have made changes to Camino code), but it is still recommended that you update your entire tree regularly. To update only the Camino code, cd to your mozilla/camino directory and run the following commands:
$ cvs update -dP
$ make

For OBJDIR builds used by most developers, replace make with cd ../../{OBJDIR}/camino; make (the sample development .mozconfig above specifies an OBJDIR by default).

Packaging a build for testing

Sometimes you'll want to create a custom build to allow a large new feature to receive wider testing from the community before review or landing. In order to do this, you need to build with a “distribution” .mozconfig. Then, when your build is complete, run make in {OBJDIR}/camino/installer to produce a disk image for distribution.

Cleaning your tree

Sometimes your build will fail because there are stale build products somewhere in the tree and new ones that conflict, or for other reasons related to the state of your tree. This can be fixed by cleaning your tree. To clean your tree, cd to mozilla and try make -f client.mk clean. If that doesn't work, you need to make -f client.mk distclean.

FAQ

Q. What versions of Mac OS X, Xcode, development SDK, and gcc are supported for building Camino?
A. There is a constantly-updated matrix of working build configurations on the Mozilla Wiki.

However, Camino officially supports building with Xcode 2.1 or higher, 10.3.9 SDK, and gcc 3.3 on Mac OS X 10.4.8 PPC and Xcode 2.1 or higher, 10.4u SDK, and gcc 4 on Mac OS X 10.4.8 Intel, and these build instructions and the default .mozconfig settings expect build environments to conform to these requirements. Your build will fail if you do not adhere to these requirements or make all the configuration changes required for another working configuration. If you wish to be daring, SDK Support documents the known states of various OS/compiler/SDK combinations when building Camino code.

Q. Can I build on Mac OS X 10.4 on PowerPC using gcc 4?
A. Yes, with a few caveats. Builds produced with gcc 4 will only run on Mac OS X 10.3.9 and above. Because of this, official Camino releases for PowerPC will continue to be built with gcc 3.3. To use gcc 3.3 on Tiger, simply enter sudo gcc_select 3.3 in a terminal.

The version of gcc 4 that initially shipped with Mac OS X 10.4 Tiger is a pre-release version and will not build Camino. Users with Xcode 2.0 must either upgrade to Xcode 2.1, which includes a working version of gcc 4, or to switch to gcc 3.3 with sudo gcc_select 3.3.

Q. Can I build on Case-Sensitive HFS or UFS?
A. Yes, on the trunk and the MOZILLA_1_8_BRANCH.

Q. How do I build a release version of Camino or build Camino from a specific branch?
A. These build instructions will build the "trunk" code for Camino, the site of ongoing development. If you want to build the latest Camino release, download and unpack the source tarball for that release instead of checking out source from cvs.

For release builds of Camino, be sure to add the following lines to your .mozconfig file:
ac_add_options --disable-shared
ac_add_options --enable-static

After editing your .mozconfig, start your build by running make -f client.mk from your mozilla directory.

If you wish to build the Camino code that exists on a certain branch, you should follow the main instructions for checking out the source code but modify the two cvs co commands to include the appropriate branch tag. To build Camino code on the Mozilla 1.8 branch (code that will become Camino 1.6), the appropriate commands are as follows:
$ cvs co -r MOZILLA_1_8_BRANCH mozilla/client.mk
$ cvs co -r MOZILLA_1_8_BRANCH mozilla/camino/config/mozconfig

Note that all Camino development is done on the trunk and back-ported to the branches if needed, so those wishing to become involved in Camino development should follow the main instructions.

Note that Camino 1.0.x/MOZILLA_1_8_0_BRANCH requires a different SDK configuration in order to build; see below.

Q. What are the requirements for building Camino 1.0.x stable releases?
A. If you wish to build Camino 1.0.x for PPC or Universal, you must install the Mac OS X 10.2.8 SDK and properly configure your build.

• Ensure you have selected gcc 3.3 for PowerPC builds.
• In the section for configuring the Shared Menus Framework, follow the instructions for setting up the symbolic links for PowerPC builds except replace all instances of MacOSX10.3.9.sdk MacOSX10.2.8.sdk.
• Omit the SDK selection and Mac OS X target selection lines from your .mozconfig, as they will cause Universal builds of Camino 1.0.x to fail; remove the following from the sample Universal .mozconfig:
  ac_add_app_options ppc --with-macos-sdk=/Developer/SDKs/MacOSX10.3.9.sdk
ac_add_app_options ppc --enable-macos-target=10.3

Q. What are the cvs tags for recent branches, releases, and milestones?
A. Use the following cvs tags in your cvs co -r commands above in order to build these versions of Camino:

• CAMINO_1_5_RELEASE - Camino 1.5 release
• MOZILLA_1_8_BRANCH - Ongoing Camino 1.6a1pre development (will become Camino 1.6)
• CAMINO_1_5_BRANCH - Camino 1.5.x security releases

Q. Why can't I get a fresh copy of Camino to build?
A. Despite our best efforts, sometimes the Mozilla or Camino tree is "red," meaning that the source code won't build properly in its current state. Before you pull, you can check the status on Camino's tinderbox. If the Camino tinderbox or the Mac builds or UNIX/Linux builds in the SeaMonkey or Firefox tinderboxes are red, you probably should avoid checking out.

If your build fails, just wait until things go green again and re-pull Camino.

(Confused? Here's an introduction to Tinderbox).

If the tree was green when you pulled your source, consult the list of common build errors and see if your error is listed. If so, follow the steps listed there to fix your build.

Q. I get an error from the Terminal or from Xcode when trying to build Camino; what's wrong?
A. Consult the list of common build errors and see if your error is listed. If so, follow the steps listed there to fix your build.

Q. My Camino build crashes at startup; what's wrong?
A. This has most likely occurred because you are building from within Xcode and have set up your .mozconfig for an optimized build and Xcode for a debug build, or the other way around. Follow the instructions above to set your build mode in both the .mozconfig and Xcode, or just build from the command line using make -f client.mk.

Q. What if I still can't get Camino to build?
A. First check the Build Errors page to see if you've run in to any of the common errors. If not, there are two places to go for help building Camino:

• The #camino IRC channel at irc.mozilla.org is a good place to find some Mac weenies in real time who, if you ask nicely and don't be a pest, will happily get you on your way.
• For non-real-time build help, the Camino forum at MozillaZine has a number of regulars who can usually solve your build woes.