Mac OS X Universal Binaries

  • Revision slug: Mac_OS_X_Universal_Binaries
  • Revision title: Mac OS X Universal Binaries
  • Revision id: 94600
  • Created:
  • Creator: Josh
  • Is current revision? No
  • Comment 19 words added, 18 words removed

Revision Content

NOTE: substantive changes to this page (non-editorial) should be reviewed by one of the build-config peers

It is possible to build Mozilla applications as a universal binary that runs natively on multiple architectures. Universal binaries contain:

  • Compiled executable code for two architectures, such as:
    • the main executable (for example, firefox-bin)
    • shared libraries and binary plugins (for example, libxpcom.dylib)
  • A single copy of all other non-executable files, including:
    • application resources (for example, browser.jar)
    • localization packages (for example, en-US.jar)

On the Gecko 1.9.2 and lower branches, universal binaries are PPC/i386 binaries. On Gecko 2.0 and higher branches, universal binaries are i386/x86_64.

{{ :en/Build_Documentation/TOC() }}

Prerequisites

The universal build system is supported on the trunk, Mozilla 1.9.1 and Mozilla 1.9.2 branches. You should be familiar with the Mac OS X build prerequisites before attempting to build a universal binary of a Mozilla product. The prerequisites for universal binaries are the same. "libIDL" and "GLib" need only be installed in the host architecture.

Configuration

This section describes how to check out the necessary files and configure Mozilla to build as a universal binary.

Your .mozconfig File

When preparing your own .mozconfig file, you must source the $topsrcdir/build/macosx/universal/mozconfig config fragment . It should be sourced after any product-specific mozconfig, in case it needs to override any options.

Universal binaries must be built as objdir builds, so MOZ_OBJDIR must be set. The location of your objdir is unimportant, so long as you provide one.

Here is a sample .mozconfig suitable for building a universal binary of Firefox in a release configuration:

. $topsrcdir/browser/config/mozconfig
. $topsrcdir/build/macosx/universal/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../build
ac_add_options --disable-tests

In this example, the objdir is placed adjacent to the mozilla directory, in a directory called build.

Building

Once the configuration is in place, building Mozilla as a universal binary is as easy as performing an ordinary build. Type:

make -w -f client.mk

The source code required for your build will be checked out and compiled. Two build passes are made: one to compile Mozilla for PowerPC, and another for Intel processors. Understandably, this process takes approximately twice as long as compiling for a single processor. After both passes are complete, the results are automatically merged into a single universal binary.

Results of a Build

Two subdirectories are created in your objdir, one for each architecture (ppc, i386, or x86_64). Each of these directories contains a complete processor-specific build. The merged universal binary is placed in both build directories, one via symlink, at dist/universal.

Packaging

For most products, when configured as a universal binary, the packaging phase will produce a disk image containing the merged universal binary. In order to perform the packaging phase, you must keep the new objdir structure in mind. If you had used the sample .mozconfig above, you would build a universal disk image of Firefox by typing:

make -C ../build/ppc/browser/installer

The disk image will be produced in ../build/ppc/dist. You could just as easily substitute i386 for ppc, this only affects the location that the disk image is produced in.

To bypass universal packaging, and create a disk image containing the application for a single processor only, you can override the UNIVERSAL_BINARY variable, setting it to empty. This will package Firefox for Intel processors into a disk image, the result will not launch at all on PowerPC:

make -C ../build/i386/browser/installer UNIVERSAL_BINARY=

Appendices

Cross-Compilation

The universal build process is implemented as a PowerPC build followed by an Intel build. Whichever build is not native is performed as a cross-compilation. If desired, it is also possible to use Mozilla’s cross-compilation support to cross-compile on Mac OS X without doing a full universal build. The prerequisites are the same as for a universal build, but instead of configuring for a universal binary, the following settings are added to the .mozconfig:

# Use the next section if cross-compiling for Intel on a PowerPC:
CC="gcc-4.0 -arch i386"
CXX="g++-4.0 -arch i386"
ac_add_options --target=i386-apple-darwin8.0.0
ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.4u.sdk

# Use the next section if cross-compiling for PowerPC on an Intel, on the
# 1.9 branch or higher:
# CC="gcc-4.0 -arch ppc"
# CXX="g++-4.0 -arch ppc"
# ac_add_options --target=powerpc-apple-darwin8.0.0
# ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.4u.sdk

# Use the next section if cross-compiling for PowerPC on an Intel, on the
# 1.8.0 or 1.8.1 branches only:
# CC="gcc-3.3 -arch ppc"
# CXX="g++-3.3 -arch ppc"
# ac_add_options --target=powerpc-apple-darwin8.0.0
# ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.2.8.sdk

# This section remains the same for any type of cross-compilation.
HOST_CC="gcc-4.0"
HOST_CXX="g++-4.0"
RANLIB=ranlib
AR=ar
AS=$CC
LD=ld
STRIP="strip -x -S"
CROSS_COMPILE=1

ac_add_options --disable-libIDLtest
ac_add_options --disable-glibtest

Intel Release History

{{ languages( { "ja": "ja/Mac_OS_X_Universal_Binaries" } ) }}

Revision Source

<p><span class="comment">NOTE: substantive changes to this page (non-editorial) should be reviewed by one of the build-config peers</span></p>
<p>It is possible to build Mozilla applications as a <a class="external" href="http://developer.apple.com/transition/">universal binary</a> that runs natively on multiple architectures. Universal binaries contain:</p>
<ul> <li>Compiled executable code for two architectures, such as: <ul> <li>the main executable (for example, <code>firefox-bin</code>)</li> <li>shared libraries and binary plugins (for example, <code>libxpcom.dylib</code>)</li> </ul> </li> <li>A single copy of all other non-executable files, including: <ul> <li>application resources (for example, <code>browser.jar</code>)</li> <li>localization packages (for example, <code>en-US.jar</code>)</li> </ul> </li>
</ul>
<p>On the Gecko 1.9.2 and lower branches, universal binaries are PPC/i386 binaries. On Gecko 2.0 and higher branches, universal binaries are i386/x86_64.</p>
<p>{{ :en/Build_Documentation/TOC() }}</p>
<h3 name="Prerequisites">Prerequisites</h3>
<p>The universal build system is supported on the trunk, Mozilla 1.9.1 and Mozilla 1.9.2 branches. You should be familiar with the <a href="/En/Developer_Guide/Build_Instructions/Mac_OS_X_Prerequisites" title="En/Developer_Guide/Build_Instructions/Mac_OS_X_Prerequisites">Mac OS X build prerequisites</a> before attempting to build a universal binary of a Mozilla product. The prerequisites for universal binaries are the same. "libIDL" and "GLib" need only be installed in the host architecture.</p>
<h3 name="Configuration">Configuration</h3>
<p>This section describes how to check out the necessary files and configure Mozilla to build as a universal binary.</p>
<h4 name="Your_.mozconfig_File">Your .mozconfig File</h4>
<p>When preparing your own <code><a href="/en/Configuring_Build_Options" title="en/Configuring_Build_Options">.mozconfig</a></code> file, you must source the <code>$topsrcdir/build/macosx/universal/mozconfig</code> config fragment . It should be sourced after any product-specific <code>mozconfig</code>, in case it needs to override any options.</p>
<p>Universal binaries must be built as <a href="/en/Configuring_Build_Options#Building_with_an_Objdir" title="en/Configuring_Build_Options#Building_with_an_Objdir">objdir builds</a>, so <code>MOZ_OBJDIR</code> must be set. The location of your objdir is unimportant, so long as you provide one.</p>
<p>Here is a sample <code>.mozconfig</code> suitable for building a universal binary of Firefox in a release configuration:</p>
<pre class="eval">. $topsrcdir/browser/config/mozconfig
. $topsrcdir/build/macosx/universal/mozconfig
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../build
ac_add_options --disable-tests
</pre>
<p>In this example, the objdir is placed adjacent to the <code>mozilla</code> directory, in a directory called <code>build</code>.</p>
<p>Building</p>
<p>Once the configuration is in place, building Mozilla as a universal binary is as easy as performing an ordinary build. Type:</p>
<pre class="eval">make -w -f client.mk
</pre>
<p>The source code required for your build will be checked out and compiled. Two build passes are made: one to compile Mozilla for PowerPC, and another for Intel processors. Understandably, this process takes approximately twice as long as compiling for a single processor. After both passes are complete, the results are automatically merged into a single universal binary.</p>
<h4 name="Results_of_a_Build">Results of a Build</h4>
<p>Two subdirectories are created in your objdir, one for each architecture (<code>ppc</code>, <code>i386</code>, or <code>x86_64</code>). Each of these directories contains a complete processor-specific build. The merged universal binary is placed in both build directories, one via symlink, at <code>dist/universal</code>.</p>
<h4 name="Packaging">Packaging</h4>
<p>For most products, when configured as a universal binary, the packaging phase will produce a disk image containing the merged universal binary. In order to perform the packaging phase, you must keep the new objdir structure in mind. If you had used the <a href="#Your_.mozconfig_File">sample <code>.mozconfig</code></a> above, you would build a universal disk image of Firefox by typing:</p>
<pre class="eval">make -C ../build/ppc/browser/installer
</pre>
<p>The disk image will be produced in <code>../build/ppc/dist</code>. You could just as easily substitute <code>i386</code> for <code>ppc</code>, this only affects the location that the disk image is produced in.</p>
<p>To bypass universal packaging, and create a disk image containing the application for a single processor only, you can override the <code>UNIVERSAL_BINARY</code> variable, setting it to empty. This will package Firefox for Intel processors into a disk image, the result will not launch at all on PowerPC:</p>
<pre class="eval">make -C ../build/i386/browser/installer UNIVERSAL_BINARY=
</pre>
<h3 name="Appendices">Appendices</h3>
<h4 name="Cross-Compilation">Cross-Compilation</h4>
<p>The universal build process is implemented as a PowerPC build followed by an Intel build. Whichever build is not native is performed as a cross-compilation. If desired, it is also possible to use <a class="external" href="http://www.mozilla.org/build/cross-compiling.html">Mozilla’s cross-compilation support</a> to cross-compile on Mac OS X without doing a full universal build. The <a href="#Prerequisites">prerequisites</a> are the same as for a universal build, but instead of configuring for a universal binary, the following settings are added to the <code>.mozconfig</code>:</p>
<pre class="eval"># Use the next section if cross-compiling for Intel on a PowerPC:
CC="gcc-4.0 -arch i386"
CXX="g++-4.0 -arch i386"
ac_add_options --target=i386-apple-darwin8.0.0
ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.4u.sdk

# Use the next section if cross-compiling for PowerPC on an Intel, on the
# 1.9 branch or higher:
# CC="gcc-4.0 -arch ppc"
# CXX="g++-4.0 -arch ppc"
# ac_add_options --target=powerpc-apple-darwin8.0.0
# ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.4u.sdk

# Use the next section if cross-compiling for PowerPC on an Intel, on the
# 1.8.0 or 1.8.1 branches only:
# CC="gcc-3.3 -arch ppc"
# CXX="g++-3.3 -arch ppc"
# ac_add_options --target=powerpc-apple-darwin8.0.0
# ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.2.8.sdk

# This section remains the same for any type of cross-compilation.
HOST_CC="gcc-4.0"
HOST_CXX="g++-4.0"
RANLIB=ranlib
AR=ar
AS=$CC
LD=ld
STRIP="strip -x -S"
CROSS_COMPILE=1

ac_add_options --disable-libIDLtest
ac_add_options --disable-glibtest
</pre>
<h4 name="Intel_Release_History">Intel Release History</h4>
<ul> <li><a class="external" href="http://www.mozilla.com/firefox/">Firefox 1.5.0.2</a>, released as a universal binary on 2006-04-13</li> <li><a class="external" href="http://www.mozilla.com/thunderbird/">Thunderbird 1.5.0.4</a>, released as a universal binary on 2006-06-01</li> <li><a class="external" href="http://www.mozilla.org/projects/seamonkey/">SeaMonkey 1.0.2</a>, released as a universal binary on 2006-06-01</li> <li><a class="external" href="http://www.caminobrowser.org/">Camino 1.0</a>, released as a universal binary on 2006-02-14</li>
</ul>
<p>{{ languages( { "ja": "ja/Mac_OS_X_Universal_Binaries" } ) }}</p>
Revert to this revision