Development:Building:Mozilla 1.9.2 Branch

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

Mac OS X 10.4.11 and Xcode 2.4.1 or later are now required for building Camino (Xcode 2.5 on Mac OS X 10.4.11 or Xcode 3 on Mac OS X 10.5.8 are recommended; on Mac OS X 10.5, the MacPorts package system that can be used to install certain build dependencies—see below—requires Xcode 3.1). Xcode is included on a separate disk with the purchase of a new Mac, and the latest version is always available as a free download from Apple Developer Connection.

Note that Gecko 1.9.2 (and thus Camino) does not yet build “out-of-the-box” on Mac OS X 10.6. At appropriate places in this guide, you will be referred to supplemental information in Development:Building:Mac OS X 10.6, which describes local changes you must make in order to build successfully on Mac OS X 10.6. (Bug 514495 is tracking the ability to build out-of-the-box on Mac OS X 10.6.)

In addition to disk space required by developer tools and build prerequisites, you will need approximately 2 GB of free disk space for a single debug tree (a Universal build requires approximately 50% more free space).

Installing Mac OS X Cross Development SDKs

Camino requires a custom Xcode installation to build properly: during installation, turn on the “Mac OS X 10.4 SDK” option (in older versions of Xcode, you may have to click the “Customize” button and turn on the “UNIX Development” and “Mac OS X 10.4 SDK” options—the latter is part of the “Cross Development” section in even older Xcode versions). If you have previously installed Xcode without these options, run the installer again to add Cross Development before attempting to build Camino. Current versions of Camino require the 10.4u SDK for PPC, Intel, and Universal builds. If you are building older versions of Camino, other SDKs are required; see the Appendix for details.

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.4.11, Mac OS X 10.5.8, and Mac OS X 10.6.4 as of June 2010) and the latest Xcode version available for that version of Mac OS X (Xcode 2.5 on 10.4.11, Xcode 3.1.4 on 10.5.8, Xcode 3.2 on 10.6.4; previous versions of Xcode are available from http://developer.apple.com/resources/, "Developer Downloads", "Developer Tools" and then search for "Xcode").

Upgrading Xcode

When you upgrade to a newer version of Xcode, even a minor-point release, 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) or $TMPDIR/../-Caches-/com.apple.Xcode.501 before building Camino. Xcode 3.1 and higher have an “Empty Caches…” menu item in the Xcode menu that will perform this step.

Installing libIDL and autoconf-2.13

Mozilla requires libIDL and autoconf-2.13 in order to build (the version of autoconf shipped with Xcode will not work; you must install autoconf-2.13). While you can build these packages (and their dependencies) from source yourself, most developers use MacPorts. MacPorts is easier to use and is recommended. When installing a new major version of Mac OS X, be sure to upgrade MacPorts to the version appropriate for that Mac OS X version.

1. Download the latest MacPorts release for your version of Mac OS X and install it.

   MacPorts installs in /opt/local by default. After running the MacPorts installer, the changes that it makes to the shell environment will be available in any new Terminal window.

2. Open a new Terminal window and install the ports (N.B. you will need to use an Administrator account or your account must be listed in the sudoers file)
   1. $ sudo port install libidl +universal

      This will take some time as the sources for libIDL and its dependencies are downloaded and installed. If you are on Mac OS X 10.6 and already have some ports installed, see below for additional steps that are required. (The +universal flag is not necessary on Mac OS X 10.4 or 10.5.)

   2. $ sudo port install autoconf213 +universal

      The above command installs autoconf-2.13 to /opt/local/bin/autoconf213 using MacPorts. You will need to type autoconf213 to run it when other documentation might instruct you to run autoconf. Do not install the autoconf package without the 213 suffix.

The +universal flag is not necessary on Mac OS X 10.4 or 10.5, but it is required on Mac OS X 10.6. If you try to build Gecko and Camino on 10.6 without installing libIDL using the +universal flag, you will need to make -f client.mk distclean before building again.

Installing libIDL in an existing MacPorts installation on Mac OS X 10.6

MacPorts on 10.6 is unable to install libIDL with the +universal flag if you have already installed any of libIDL’s dependencies without the +universal flag; this is reported to be a MacPorts bug.

According to internet sources, you should be able to use sudo port upgrade --enforce-variants libidl +universal to force MacPorts to upgrade all of libIDL’s dependencies to the +universal variant; you should then be able to install a +universal MacPorts. (As a last resort, try the MacPorts migration steps, or remove MacPorts and reinstall from scratch.)

Installing Mercurial

Current Mozilla development uses Mercurial (“hg”) for version control. Unlike common version-control systems (CVS, svn), Mercurial is not included as part of the Mac OS X Developer Tools.

Mercurial has binary packages available for Mac OS X 10.5 and 10.6, or you can install it via MacPorts. As of August 2010, Mercurial in MacPorts fails to install on Mac OS X 10.6 due to bad checksums for patches in python dependencies; use the Mercurial binary package instead. [Looks like this is fixed as of Feb 2012 --cl]

To install Mercurial from MacPorts:

• $ sudo port install mercurial

  This will take some time as the sources for mercurial and its dependencies are downloaded and installed.

  N.B. The version of Mercurial from MacPorts will install Python 2.6; by default that version of Python will attempt to build all of X.org X11 for the Python IDE. You can avoid this extra compile time by first installing Python 2.6 with the no_tkinter variant and then installing Mercurial: $ sudo port install python26 +no_tkinter; sudo port install mercurial

Selecting the Required Python Version on Mac OS X 10.4

The Gecko build system requires at least Python 2.4, but Mac OS X 10.4 ships with Python 2.3. If you use MacPorts to install Mercurial, it will install Python 2.6. You can then install python_select to make the MacPorts version the default Python version.

$ sudo port install python_select
$ sudo python_select -s python26  (some MacPorts versions instead require sudo python_select python26 )

Unfortunately, the Gecko configure script may fail to detect the MacPorts Python and will still fail, claiming Python 2.4 or greater is not installed. If this happens, configure can be tricked by making a symlink of the MacPorts Python that points to a “Python binary filename” that configure looks for:

$ sudo ln /opt/local/bin/python /opt/local/bin/python2.5

Setting up your Hg 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, and if you are doing development, you should not use the tarball. (In particular, unlike a tarball from CVS, a tarball from Hg does not contain the metadata necessary to provide an updatable source tree.)

Mercurial configures itself via a hidden .hgrc file in your home folder. Create a new plain-text ~/.hgrc file in your favorite text editor and populate it with the following:

[ui]
username = Your Name <email@domain.tld>
merge = internal:merge

[defaults]
commit = -v
diff = -U 8 -p
qdiff = -U 8

[diff]
git = 1
showfunc = 1
unified = 8

Mozilla’s Mercurial instructions exhort you to choose a merge program now and to learn how to use it, without providing much useful guidance. The configuration above defaults to the traditional “try to merge and leave conflict markers” merging; if you have a favorite visual merge tool, configure it now, but otherwise you may want try various tools later on to see if such a tool exists for Mac OS X that doesn’t suck and doesn’t make you want to gouge your eyes out.

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 5 of this section. Be sure to follow the link to learn about other .mozconfig settings, since the sample is for a development build.

Before beginning to pull the source (or unpack the tarball), open a new Terminal window (or tab); this is necessary because MacPorts updates your PATH and the new PATH (and newly-installed programs in directories in the new PATH) aren’t available to the existing Terminal windows (or tabs).

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 Gecko source:
   $ hg clone -r CAMINO_2_1_SECBRANCH http://hg.mozilla.org/releases/mozilla-1.9.2/ mozilla
   (Note: Prior to 2012-05-01, the clone command did not include -r CAMINO_2_1_SECBRANCH)
   This will download hundreds of megabytes to your computer and will take anywhere from 20 minutes to an hour to complete.
   (If you have a slow or flaky connection, you may want to use the mozilla-1.9.2 Mercurial bundle (unpacking instructions) to bootstrap your mozilla-1.9.2 clone.)
3. cd into the mozilla directory that was just created:
   $ cd mozilla
4. Pull the Camino source:
   $ hg clone http://hg.mozilla.org/camino/ camino
   It is very important that you are in the mozilla directory when issuing this command. This will download the Camino source to the appropriate location and should take about 5-10 minutes.
5. 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. For a development build add the following to your .mozconfig file (note the leading dot and space):
   

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

   N.B. If you are trying to build on Mac OS X 10.6, please refer to the .mozconfig section of the Development:Building:Mac OS X 10.6 supplemental instructions for additional .mozconfig contents.

   (The MOZ_MAKE_FLAGS setting improves build speed, assuming you have a multi-processor or multi-core machine. For older machines, remove that line.)

   For examples of other builds types, or to learn more about the .mozconfig file, see the .mozconfig page.

6. Mac OS X 10.6 only - Apply local patches:
   On Mac OS X 10.6, you must apply several local patches to make your build succeed. The Local Patches section of the Development:Building:Mac OS X 10.6 supplemental instructions contains links to the required patches.
7. Build:
   $ make -f client.mk build
   This will automatically Camino (including various components of Mozilla that Camino requires). The final Camino build ends up in mozilla/dist (or $OBJDIR/dist).

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 and Common Build Errors pages.

Development

To work on Camino application code, open up the Camino.xcodeproj project (from the camino directory of your OBJDIR) in Xcode. You can edit code, build, and run from inside of Xcode. (You can, of course, use an editor of your choice and rebuild either from Xcode or from the command line.)

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.

Camino code

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

.in and generated files

However, if you’ve edited the source files for certain files that are generated during the build process (e.g., the .in files for .strings files, all-camino.js, or the Makefile) or any of the geckochrome overrides, you will need to rebuild using the command line: cd $OBJDIR/camino; make

Non-Xcode-managed source directories

Source directories that appear in the DIRS variable in Makefile.in must be built from command line and cannot be built in Xcode (and, in some cases, must be rebuilt before changes to Xcode-managed source files will compile successfully).

Currently, these are feedhandlers, flashblock, geckochrome, idl, jsbridge, striptease, safebrowsing, and typeaheadfind.

To (re)build any of the directories, build from the command line: cd $OBJDIR/camino; make

Camino.xcodeproj project file

Changes to the project file must be made from the source directory, using the source directory’s project file, in order for paths to be correct and for hg diff to pick up the changes. However, if you use an OBJDIR, you’ll need to propagate those (as well as any added or renamed sourcefile directories) from the source directory to the OBJDIR before attempting to rebuild.

If you use the command-line, just cd $OBJDIR/camino; make.

If you prefer to build in Xcode:

1. Close the OBJDIR copy of the project, if it is still open.
2. From the command line: cd $OBJDIR/camino; make export

   This updates the project file, the Makefile, and the sourcefile directory symlinks, and generates any headers from .idl files, but it does not compile any code (see Development:Building:Common_make_Targets for more information about various make targets).

3. Re-open the updated OBJDIR project file and build or debug as normal.

For more information about making changes to the project file, see Development:Coding.

Mozilla code

Unlike Camino code, nearly all Mozilla code is build with Makefiles, so there are no project files to ease development integration, and as a consequence you must open files manually in Xcode or your favorite editor.

Setting up a Camino-specific .hgignore file for the Mozilla repository

If you plan to work on Mozilla code, you’ll want to add a repository-specific .hgignore file for the Mozilla repository, so that Camino files do not show up as unknown when running Mercurial commands in the Mozilla repository.

To do this, edit the mozilla/.hg/hgrc file and add the following lines:

[ui]
ignore = ~/.hgignore-mozcamino

Then, in your favorite text editor, make a new plain-text file in your home directory named .hgignore-mozcamino with the following lines:

# Make mozilla-{central|1.9.2} ignore camino
^camino

Widget code

If you’ve edited the Cocoa widget code, you can make in $OBJDIR/widget/src/cocoa to rebuild the widget library with your changes and then copy the new version of the widget library into your build.

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 $OBJDIR/camino/build/Development/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 $OBJDIR/camino again.

Other changes

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 (or make from the root of your OBJDIR, if you're using an OBJDIR as recommended by the sample development .mozconfig above).

Stopping or continuing on Xcode build errors

Depending on your preferences, you may want to set Xcode (and xcodebuild) to stop building when it hits a build error (rather than to spend time continuing to build the rest of Camino only to produce a broken executable) or to continue trying to build after errors (perhaps in order to maximize the number of errors you see in a given build attempt). In Xcode 3.1 and newer, this defaults to continuing to build past errors; in older versions of Xcode, the default was to stop on errors.

To change this value, toggle the “Continue building after errors” checkbox in the “Build Options:” section of the “Building” pane of Xcode’s preferences (or, when Xcode is not running, use the command line defaults write com.apple.Xcode PBXBuildsContinueAfterErrors -bool false—or true to continue building—to set this preference).

(Note that if you have a -j value set in your .mozconfig, xcodebuild may continue “building” for a short time after hitting an error as the additional tasks that were already running finish.)

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 columns whose headings end in “Cm2.1-M1.9.2” are green . Then cd to your mozilla directory and run the following commands:
$ hg pull -u
$ cd camino
$ hg pull -u
Then, to rebuild Gecko and Camino:
$ cd ..
$ make -f client.mk build

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:
$ hg pull -u
$ 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). Note that in OBJDIR builds, you must run make from the command line after a hg pull -u that pulls certain types of changes, including project changes and changes to any .strings file, since updated versions of these files are copied into the OBJDIR or regenerated by Makefile targets.

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. You can use your existing source tree but “swap in” a deployment .mozconfig that defines a new OBJDIR to provide a clean build.

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.

Appendix

• Build FAQ
• Common Build Errors
• .mozconfig Details
• Common make Targets
• Building on the Mozilla 1.9.0 and Camino 2.0 branches
• Building on the Mozilla 1.8.* branches (Camino 1.6.x, Camino 1.5.x, Camino 1.0.x) (in progress)
• Building Dependencies from Source (in progress)
• Providing Software Update for Third-Party Camino Builds