Mac OS X Build Prerequisites

Firefox quick start

It only takes a few steps to get Mozilla building for most people, for most purposes. The other sections on this page go into more detail on complete build requirements for various Mozilla projects. These steps will get the most recent (trunk) version of Firefox built on Mac OS X 10.5 or 10.6.

1. Install Xcode Tools. Insert the "Mac OS X Install DVD" (which came with your computer), and find the Xcode or XcodeTools installer in the "Optional Installs" folder. Alternatively, download the latest XCode from the ADC site (the version that comes on the DVD with late 2008 MacBook Pros, for example, has non-working profiling tools, e.g. Shark).

2. Install MacPorts. Go to their install page, download the .dmg for your platform, and install it. If you already have an old version of MacPorts installed, ensure it's up to date by running:

$ sudo port selfupdate
$ sudo port sync

3. Use MacPorts to install the packages needed for building Firefox:

$ sudo port install mercurial libidl autoconf213

This will ask for your root password. You'll then see lots of output as MacPorts builds and installs these packages and their dependencies -- it takes a while, so go grab a cup of coffee.

Common errors include:

• sudo doesn't accept a blank password: create a password for your account in System Preferences.
• port command not found: add it to your path (see troubleshooting section below).


4. Check that Mercurial works by typing:

$ hg version

If this fails with the error "ValueError: unknown locale: UTF-8", then see the workarounds on the Mercurial wiki's Unix Install page.

When trying to clone a repository you may get an HTTP 500 error (internal server error). This seems to be due to something that Mac Mercurial sends to the server (it's been observed both with MacPort and selenic.com Mercurial binaries). Try restarting your shell, your computer, or reinstall Mercurial (in that order) then report back here what worked, please.

 5. Create a file named .mozconfig in your home directory. For building trunk on Mac OS X 10.5 and later, you can use the following for starters:

. $topsrcdir/browser/config/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg
mk_add_options MOZ_MAKE_FLAGS="-s -j4"
ac_add_options --enable-debug
ac_add_options --disable-optimize
ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.5.sdk

(mozilla-central builds prior to 2009-09-14 used the MacOSX10.4u.sdk instead of MacOSX10.5.sdk.)

For builds prior to 2009-12-16 on Mac OS X 10.6, also append the following:

CC="gcc-4.2 -arch i386"
CXX="g++-4.2 -arch i386"
ac_add_options --target=i386-apple-darwin8.0.0
ac_add_options --enable-macos-target=10.5
# bug 491774. crashreporter won't build in cross compile
ac_add_options --disable-crashreporter

HOST_CC="gcc-4.2"
HOST_CXX="g++-4.2"
RANLIB=ranlib
AR=ar
AS=$CC
LD=ld
STRIP="strip -x -S"
CROSS_COMPILE=1

The reason Mac OS X 10.6 requires a more complex mozconfig file is that by default, the tools on Mac OS X 10.6 compile 64-bit binaries, and trunk versions before 2009-12-16 were not ready for 64-bit builds on Mac OS X.

Currently, 64-bit compilation is supported on Mac OS X 10.6, and you no longer need to cross-compile for 32-bit.  If you want to build a 32-bit version of Firefox on Mac OS X on a trunk version of 2009-12-16 or later, you can append the above lines to your .mozconfig in order to force the build process to produce a 32-bit version of Firefox.

This will create a debug build of Firefox. For other options, see Configuring Build Options.

6. Get the Mozilla source.

For trunk, use Mercurial (hg):

$ hg clone http://hg.mozilla.org/mozilla-central/ mozilla
$ cd mozilla

For older versions such as Firefox 3.0.x, use CVS:

$ cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co mozilla/client.mk mozilla/browser/config/mozconfig
$ cd mozilla
$ make -f client.mk checkout

7. Build it.

$ make -f client.mk build

8. Launch your application. From the top directory, the application is at obj-ff-dbg/dist/Minefield.app or obj-ff-dbg/dist/MinefieldDebug.app. "Minefield" is the default build name of the "unbranded" Firefox executable that you have built. Note that you may not want to move the binary, as soft links inside the bundle will be wrong and the application might not launch. From the command-line, you can launch with (using the correct capitalization):

$ open obj-ff-dbg/dist/MinefieldDebug.app

Hardware requirements

There are no specific hardware requirements, provided that the hardware accommodates all of the software required to build Mozilla. Mozilla can take a very long time to build, so recommended development systems are listed alongside the minimum requirements.

• Processor: PowerPC G4 or later, PowerPC G5 or Intel CPUs recommended. Mozilla can now be built for either type of processor, or as a universal binary for both types (see Mac OS X Universal Binaries).
• Memory: 256MB RAM minimum, 1GB recommended.
• Disk Space: At least 1GB of free disk space for non-debug builds; development/debug builds require at least 2.5GB of free disk space.

Software requirements

• Operating System: Mac OS X 10.5.8 or later. It is advisable to upgrade to the latest “point” release (currently 10.5.8 and 10.6.3) by running Software Update, found in the Apple menu.
  • Beginning with Mozilla 1.9.3 (mozilla-central), Mac OS X 10.5 is both a build- and run-time requirement; for 64-bit builds, Mac OS X 10.6 is both a build- and run-time requirement.
  • Beginning with Mozilla 1.9 (cvs trunk), Mac OS X 10.4 is both a build- and run-time requirement.
  • Mozilla’s 1.8.0 and 1.8.1 branches will run on Mac OS X 10.2 (“Jaguar”), but the build requires a minimum of 10.3 (“Panther”).
  • No recent version of Mozilla will build or run on 10.1 (“Puma”).
  • For additional details, see the Mac compatibility matrix.

To install the following software requirements, you may need administrative privileges on the system.

• Development Environment: Xcode Tools 3.0 or later. Earlier versions of Xcode and Developer Tools are no longer supported (Xcode 2.x is still supported on the Mozilla 1.9.0, 1.9.1, and 1.9.2 branches for building on Mac OS X 10.4 hosts; Xcode 2.5 is recommended on Mac OS X 10.4. Xcode 2.0 is not recommended, but Xcode 2.1 and later work properly. Xcode 1.5 is still supported on the Mozilla 1.8 and 1.8.0 branches.) Tested Xcode configurations are listed in the Mac compatibility matrix. Installing the cross-development environments (SDKs) is required; consult the Mac compatibility matrix to find the specific SDKs required for the branch(es) and product(s) you are building. These are selected by clicking the “Customize” button in the Xcode installer. There are two ways to obtain or upgrade Xcode:
  • Download: Download Xcode from Apple. This ensures that you’ll install the latest version of the tools available for your computer. You’ll need a (free) Apple Developer Connection membership. Note that Xcode updates are not installed by Software Update at this time.
  • DVD or CD: Most Macs and retail versions of Mac OS X include an Xcode installer on the installation discs. Check your discs for Xcode or Developer Tools.
• Package Management: A package management system is not strictly required, but simplifies the installation of additional build dependencies. There are two package management systems that are compatible with the Mozilla build system, Fink and MacPorts (formerly DarwinPorts). Note that package installation may be a time-consuming but automated process using either tool.
  • MacPorts, formerly DarwinPorts. You may download the MacPorts installer corresponding to your operating system release. 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.
  • fink (not recommended).
• libIDL and GLib, libraries used by Mozilla’s IDL (interface definition language) file parser. These may be installed using MacPorts using the commands listed below. Glib is installed automatically as part of the libidl install. Administrative privileges are required, provide your password to the sudo command if requested:

  $ sudo port sync
  $ sudo port install libidl

• autoconf version 2.13 is needed if you plan on making changes to the Mozilla configure.in files on versions up to 1.9 and when building from mozilla-central. Newer versions of autoconf, including those that come with Xcode and installed in /usr/bin, are incompatible with Mozilla ( bug 104642).

  $ sudo port install autoconf213

  The above commands install 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.

  When building from mozilla-central, use mk_add_options AUTOCONF=autoconf213 in your .mozconfig

• Mercurial source control system (if you're planning to work on post-1.9.0 code). See Mercurial#Installing.
• To build the Mozilla 1.9.0, 1.9.1, or 1.9.2 branches on a Mac OS X 10.4 build host, additional packages are required, so run the following command to obtain them:

  $ sudo port install python py25-zlib py25-hashlib

.mozconfig options and other tunables

These options are specific to Mozilla builds for Mac OS X. For a more general overview of build options and the .mozconfig file, see Configuring Build Options. For specific information on configuring to build a universal binary, see Mac OS X Universal Binaries.

• Compiler: If you are using Mac OS X 10.4 (“Tiger”) or later on PowerPC and are working on the 1.8 branch or earlier, you should change the system default compiler to gcc 3.3, the compiler used to produce official PowerPC builds. Use the following command:

  $ sudo gcc_select 3.3

  As an alternative to changing the system default compiler, you may specify the compiler to use for a Mozilla build at configure time by setting the CC and CXX environment variables to select your desired C and C++ compilers. You can enter these commands in the Terminal before starting a Mozilla build, or you can place them in your .mozconfig file:

  export CC=gcc-3.3
  export CXX=g++-3.3

  Mozilla will build with gcc 4.0 (provided that Xcode 2.1 or later is installed), and some developers prefer this newer compiler. Applications built using gcc 4.0 will only run on Mac OS X 10.3.9 and later. Official Intel builds are produced with gcc 4.0. Intel builds must be produced with gcc 4.0 (Apple's gcc 3.3 cannot produce Intel binaries), but you can use gcc 3.3 on an Intel Mac to cross-compile for PPC. The current trunk (Mozilla 1.9) requires gcc 4.0 to build.

  Be aware that the gcc 3.3 compiler for Mac OS X at optimization level -O3 is unable to build Mozilla, and that any compiler with the -fast optimization mode selected on PowerPC will result in a build failure.

The following options, specified with ac_add_options, are lines that are intended to be added to your .mozconfig file.

• Mac OS X SDK: This selects the version of the system headers and libraries to build against, ensuring that the product you build will be able to run on older systems with less complete APIs available. Selecting an SDK with this option overrides the default headers and libraries in /usr/include, /usr/lib, and /System/Library. Mac OS X SDKs are installed in /Developer/SDKs during the Xcode installation by selecting the Cross Development category in the installer’s Customize screen.

  ac_add_options --with-macos-sdk=/path/to/SDK

  Official trunk builds now use /Developer/SDKs/MacOSX10.5.sdk but prior to 2009-09-14 used /Developer/SDKs/MacOSX10.4u.sdk. The 1.9.x branches use /Developer/SDKs/MacOSX10.4u.sdk. On the 1.8.0 and 1.8.1 branches, official PowerPC builds use /Developer/SDKs/MacOSX10.2.8.sdk, while official Intel builds use /Developer/SDKs/MacOSX10.4u.sdk.
  Building with --enable-dtrace requires the 10.5 SDK: --with-macos-sdk=/Developer/SDKs/MacOSX10.5.sdk

  Note that some frameworks (notably AppKit) behave differently at runtime depending on which SDK was used at build time. This may be the source of bugs that only appear on certain platforms or in certain builds.

  You will not be able to build Mozilla using the 10.2.8 SDK included in the Xcode 2.4 installer. Upgrade to Xcode 2.4.1 or newer.

  Use of an SDK is highly recommended, especially when building on Mac OS X 10.3 with Xcode 1.5.
• Deployment Target: This option selects the minimum OS version that the resulting application will run on. Proper use of this option requires additional support in the code.

  ac_add_options --enable-macos-target=version

  This option is not recommended. The default for the trunk on all platforms is 10.5, while on the 1.9.0-1.9.2 branches it is 10.4. The default for PowerPC builds on the 1.8.0 and 1.8.1 branches is 10.3, while the default for Intel builds on those branches is 10.4. Official builds use these defaults.
• Prebinding: The Mozilla build system allows you to build an application and libraries that are prebound. This improves application launch time on Mac OS X 10.3.3 and earlier.

  ac_add_options --enable-prebinding

  The default is to not prebind. Official PowerPC builds are prebound. Official Intel builds are not prebound, as no Intel build will run on any release earlier than 10.4.
• Sample .mozconfig: This .mozconfig file is suitable to build an Intel version of Minefield (equivalent to Firefox), which will only run on Intel-based Macs running Mac OS X 10.5 or newer:

  . $topsrcdir/browser/config/mozconfig
  ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.5.sdk
  ac_add_options --disable-tests

  The following .mozconfig file is suitable to build a PowerPC version of Minefield (equivalent to Firefox) from the Mozilla 1.8 and 1.8.0 branches able to run on the widest possible range of computers. This may be used on any PowerPC Mac meeting the software requirements:

  export CC=gcc-3.3
  export CXX=g++-3.3
  . $topsrcdir/browser/config/mozconfig
  ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.3.9.sdk
  ac_add_options --enable-prebinding
  ac_add_options --disable-tests

Build defines

For Mac OS X builds, defines are set up as follows:

• XP_MACOSX is defined
• XP_UNIX is defined
• XP_MAC is not defined. XP_MAC is obsolete and is slowly being removed from the source tree (see bug 281889). It was used for CFM (non-Mach-O) builds for the classic (pre-X) Mac OS.

This requires care when writing code for Unix platforms that exclude Mac:

#if defined(XP_UNIX) && !defined(XP_MACOSX)

Troubleshooting

• After installing Xcode 2.4, the build fails in nsLookAndFeel.cpp with:
  error: `kThemeBrushAlternatePrimaryHighlightColor' undeclared (first use this function).

  The 10.2.8 SDK included in Xcode 2.4 (build 8K1079) contains a bug that prevents Mozilla from building with that SDK. Apple has been notified of this bug, which is being tracked as Radar 4671592. This bug has been fixed as of Xcode 2.4.1.

• After installing QuickTime 7.0.4 on Mac OS X 10.3.9, the build fails in libwidget_mac.dylib with:
  ld: /usr/lib/gcc/darwin/3.3/libstdc++.a(eh_personality.o) illegal reference to symbol: ___cxa_begin_catch defined in indirectly referenced dynamic library /usr/lib/libstdc++.6.dylib.

  To work around this conflict, you will need to use an SDK. Select the MacOSX10.2.8.sdk (recommended), or, if you must, you can also use MacOSX10.3.0.sdk. See the section on .mozconfig Options and Other Tunables for detailed instructions on using an SDK.

  Apple linked the QuickTime 7.0.4 framework against the shared libstdc++.6 library available in Mac OS X 10.3.9 and later, but the compiler (gcc 3.3) and build tools used on these systems do not expect to link against this library. gcc 3.3 expects to use its own statically-linked libstdc++. The QuickTime stub frameworks in the SDKs do not share this problem.

• QuickTime SDK Update: If you install or update QuickTime 7, you may also need to install an updated QuickTime SDK, available from “Software Update” in the Apple menu. This update is only needed if Software Update indicates that it is available to you. You will need this update if your build fails because it is unable to find Sound.r.
• Using Fink, you get apt-get: command not found.

  apt-get is not in your $PATH. Close and reopen Terminal and try again. If the error persists, Fink was unable to fully configure itself in your environment. Take these steps:

  • If you use the bash shell, the default since Mac OS X 10.3, edit your ~/.bashrc file, adding the following line. Don’t neglect the leading period and space.

    . /sw/bin/init.sh

  • If you use the tcsh shell, edit your ~/.tcshrc file, adding the following line:

    source /sw/bin/init.csh

  After modifying the appropriate file, close and reopen Terminal and try again.

• Using MacPorts (DarwinPorts), you get port: command not found.

  port is not in your $PATH. Close and reopen Terminal and try again. If the error persists, DarwinPorts was unable to fully configure itself in your environment. Take these steps:

  • If you use the bash shell, the default since Mac OS X 10.3, edit your ~/.profile (or ~/.bash_profile or ~/.bash_login, if either exists) file, adding the following line:

    export PATH="/opt/local/bin:/opt/local/sbin:$PATH"

  • If you use the tcsh shell, edit your ~/.tcshrc file, adding the following line:

    setenv PATH "/opt/local/bin:/opt/local/sbin:$PATH"

  After modifying the appropriate file, close and reopen Terminal and try again.
• Using Fink with Virex 7.2: There is a conflict between Fink and Virex 7.2. Both place files within /sw. If you have Virex installed, you will need to upgrade to at least version 7.2.1, as described in the Fink News (2003-04-16).
• The build stops while building libwidget.rsrc in widget/src/mac

  Delete, or rename ~/Library/Preferences/.GlobalPreferences.plist. We're not quite sure what setting in that file is causing this problem. Note that if you remove this file, system preferences such as preferred locales and recent programs will also disappear.

• The build complains about missing IDL headers: Make sure you installed the orbit distribution via Fink's apt-get, and that you edited your .bashrc to source the /sw/bin/init.sh file or your .tcshrc file to source the /sw/bin/init.csh file.
• Can't find dlfcn.h with error nsTraceRefcnt.cpp:68: dlfcn.h: No such file or directory

  Make sure you have the libdl.dylib from Fink. If you install bash from Apple, it will provide a copy of libdl.dylib which will not come with the headers (eg. dlfcn.h) needed to compile new programs that use the library, such as Mozilla. The solution is to remove the bash from Apple and install the bash from Fink. (Thanks to Alex Stewart for helping us track this down.)

Building with --enable-dtrace fails with configure: error: dtrace enabled but sys/sdt.h not found 

Make sure you use the 10.5 SDK, not 10.4 as in the default configuration.