Difference between revisions of "Development:Building:Mozilla 1.9.0 Branch"

From Camino Wiki
Jump to navigation Jump to search
(→‎Pulling Source and Building Gecko and Camino: add a line to make these instructions able to apply to CAMINO_2_0_BRANCH, too)
 
(40 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div style="margin: 0; padding:0 .5em; border:1px solid pink; background:#FFE8E8;">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.
+
<div class="toclimit-2">
 +
<div style="margin: 0; padding:0 .5em; border:1px solid pink; background:#FFE8E8;">
 +
If you have comments or suggestions, please add them to the [[Talk:Development:Building|Discussion]] page.
  
If you have comments or suggestions, please add them to the [[Talk:Development:Building|Discussion]] page.
 
 
</div>
 
</div>
 +
  
 
         <div class="note">
 
         <div class="note">
Line 10: Line 12:
 
         <p>These instructions assume that you are familiar with basic UNIX command-line functionality, such as <code>cd</code> and <code>mkdir</code>. For an introduction to the UNIX command line, please see this [http://www.macobserver.com/tips/macosxcl101/index.html tutorial].</p>
 
         <p>These instructions assume that you are familiar with basic UNIX command-line functionality, such as <code>cd</code> and <code>mkdir</code>. For an introduction to the UNIX command line, please see this [http://www.macobserver.com/tips/macosxcl101/index.html tutorial].</p>
  
==Preparing to build: Xcode==  
+
==Preparing to Build: Tools==  
         <p>Mac OS X 10.4.10 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.1 are recommended). Xcode is included on a separate disk with the purchase of a new Mac, and the latest version is alwsys available as a free download from [http://developer.apple.com/ Apple Developer Connection].</p>
+
         <p>Mac OS X 10.4.10 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.1 are recommended). 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 [http://developer.apple.com/ Apple Developer Connection].</p>
 +
 
 +
''Note that Gecko (and thus Camino) does not yet build “out-of-the-box” on Mac OS X 10.6. For more information about local changes required to build on Mac OS X 10.6, see {{bug|514495}}.''
  
In addition to disk space required by developer tools and build prerequisites, you will need approximately 4 GB of free disk space for a single debug tree.
+
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===
 
===Installing Mac OS X Cross Development SDKs===
Line 23: Line 27:
 
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 <code>/Library/Caches/com.apple.Xcode.501/SharedPrecompiledHeaders</code> (where <code>501</code> is your user ID) before building Camino.
 
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 <code>/Library/Caches/com.apple.Xcode.501/SharedPrecompiledHeaders</code> (where <code>501</code> is your user ID) before building Camino.
  
==Choosing the correct compiler version on Mac OS X 10.4==
+
===Installing <code>libIDL</code>===
Building Camino on the trunk now requires gcc 4.0.1 as the compiler (this is the default on Mac OS X 10.4, unless you have previously changed it). 
 
  
If you are on a PowerPC Mac and have previously built Camino, you must change the default complier back to gcc 4 and then <code>distclean</code> your existing tree before attempting to build with gcc4. Use the following commands to fix your gcc version and tree:<br /><br />
+
Mozilla requires <code>libIDL</code> (and <code>autoconf-2.13</code>, in the unlikely event that you need to hack any Mozilla <code>configure</code> scripts) in order to build. While you can build these packages (and their dependencies) from source yourself, most developers use [http://www.macports.org/ 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.
  
<code>$ sudo gcc_select 4.0</code><br />
+
# Download the [http://www.macports.org/install.php#pkg latest MacPorts release] for your version of Mac OS X and install it.
<code>$ cd /path/to/mozilla; make -f client.mk distclean</code><br />
+
#: MacPorts installs in <code>/opt/local</code> by default. After running the MacPorts installer, the changes that it makes to the shell environment will be available in any new Terminal window.
:If you are using an OBJDIR, instead use <br />
+
# 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 <code>sudoers</code> file)
<code>$ cd /path/to/$OBJDIR; make distclean</code><br />
+
## <code>sudo port install libidl +universal</code>
 +
##: This will take some time as the sources for <code>libIDL</code> and its dependencies are downloaded and installed. (The <code>+universal</code> flag is not necessary on Mac OS X 10.4 or 10.5.)
 +
## <code>sudo port install autoconf213</code>
 +
##: The above command installs autoconf-2.13 to <code>/opt/local/bin/autoconf213</code> using MacPorts ''(you can skip this step, and install it later if you find need it)''. You will need to type <code>autoconf213</code> to run it when other documentation might instruct you to run <code>autoconf</code>. '''Do not install the autoconf package without the 213 suffix.'''
  
==<code>libIDL</code> and <code>glib</code>==
+
The <code>+universal</code> 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 <code>libIDL</code> using the <code>+universal</code> flag, you will need to <code>make -f client.mk distclean</code> before building again.
<!-- or "Third-Party Build Dependencies" or something instead ?
+
 
-->
+
There are reports that MacPorts on 10.6 is unable to install <code>libIDL</code> with the <code>+universal</code> flag if you have already installed any of <code>libIDL</code>’s dependencies without the <code>+universal</code> flag; this is reported to be a MacPorts bug.
Follow the instructions on the [http://developer.mozilla.org/en/docs/Mac_OS_X_Build_Prerequisites#Software_Requirements Mozilla Mac OS X Build Prerequisites page] for installing Fink or DarwinPorts (MacPorts) and using them to install <code>libIDL</code> and <code>glib</code>.  DarwinPorts is recommended for Intel-based Macs.  If you are using Fink, be sure to remove the <code>/sw</code> directory entirely and reinstall Fink if you upgrade to a new major version of Mac OS X.<!--
 
note about uni status of these? e.g., not required for Uni builds atm, but will be in the future-->
 
  
 
==Setting up your CVS Environment==
 
==Setting up your CVS Environment==
''If you are building from the [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source 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.''
+
'''''N.B.''' Future Camino development is in the process of moving to [http://hg.mozilla.org/ Mercurial]; please see [[Development:Building:Mozilla 1.9.2 Branch]] for Mercurial-related build instructions.''
 +
 
 +
''If you are building from the [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source 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.''
 
         <p>Prepare your CVS client using the following parameters:</p>
 
         <p>Prepare your CVS client using the following parameters:</p>
 
         <ul>
 
         <ul>
Line 55: Line 61:
  
 
==Pulling Source and Building Gecko and Camino==
 
==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|FAQ]] for changes you will need to make to some of these commands.''
+
'''''N.B.''' Future Camino development is in the process of moving to [http://hg.mozilla.org/ Mercurial]; please see [[Development:Building:Mozilla 1.9.2 Branch]] for Mercurial-related build instructions.''
  
''If you are building from the [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source source tarball], skip to step 4 of this section. ''  
+
'''''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 [[Development:Building:FAQ|FAQ]] for changes you will need to make to some of these commands.''
 +
 
 +
'''''N.B.''' If you are trying to build on Mac OS X 10.6, please refer to {{bug|514495}} for additional information.
 +
 
 +
''If you are building from the [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source source tarball], skip to step 4 of this section. Be sure to follow the link to learn about other .mozconfig settings, since the sample is for a development build. ''  
  
 
<ol>
 
<ol>
 
           <li><code>cd</code> into the directory where you would like to keep your copy of the Camino source code (e.g., <code>cd ~/lizard</code>).</li>
 
           <li><code>cd</code> into the directory where you would like to keep your copy of the Camino source code (e.g., <code>cd ~/lizard</code>).</li>
 
           <li>Pull the main build makefile and configuration directory:<br />
 
           <li>Pull the main build makefile and configuration directory:<br />
             <code>$ cvs co mozilla/client.mk</code><br />
+
             <code>$ cvs co mozilla/client.mk mozilla/camino/config/mozconfig mozilla/build/macosx/universal/mozconfig</code><br />
 
+
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.<br />
            <code>$ cvs co mozilla/camino/config/mozconfig</code><br />
+
If you need to build Camino 2.0.x security and stability releases, replace <code>cvs co</code> with <code>cvs co -r CAMINO_2_0_BRANCH</code> in the checkout command above.
 
 
            <code>$ cvs co mozilla/build/macosx/universal/mozconfig</code><br />
 
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.
 
 
           </li>
 
           </li>
 
           <li><code>cd</code> into the <code>mozilla</code> directory that was just created:<br />
 
           <li><code>cd</code> into the <code>mozilla</code> directory that was just created:<br />
 
             <code>$ cd mozilla</code></li>
 
             <code>$ cd mozilla</code></li>
           <li>In your <code>mozilla</code> directory, create a plain text file called <code>.mozconfig</code> (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 <code>.mozconfig</code> file (note the leading dot and space):<br />
+
           <li>In your <code>mozilla</code> directory, create a plain text file called <code>.mozconfig</code> (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 <code>.mozconfig</code> file (note the leading dot and space):<br />
  
            <code>. $topsrcdir/camino/config/mozconfig</code><br />
 
 
:'''Universal builds''' will need to add the following line immediately after the above line:<br />
 
            <code>. $topsrcdir/build/macosx/universal/mozconfig</code><br />
 
:<strong>Universal builds must also be built using an OBJDIR</strong>; be sure to add an OBJDIR line to your <code>.mozconfig</code>:<br />
 
<code>mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoUni</code><br />
 
 
===<code>.mozconfig</code> options===
 
In addition to specifying ("sourcing") the default Camino (and Universal) <code>.mozconfig</code> files and specifying an OBJDIR, your <code>.mozconfig</code> 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:<br />
 
<code>ac_add_options --disable-optimize<br /> ac_add_options --enable-debug</code>
 
 
'''Please Note:''' It's important to be aware of whether you've set up <code>.mozconfig</code> 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 <code>.mozconfig</code> file:<br />
 
<code>ac_add_options --disable-shared<br />
 
ac_add_options --enable-static</code>
 
 
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 <code>.mozconfig</code> file:<br />
 
<code>mk_add_options MOZ_MAKE_FLAGS=-j4</code>
 
 
===Sample <code>.mozconfig</code>===
 
Below are some sample <code>.mozconfig</code> files, pre-configured for typical usages. <!-- Need samples for Intel, G5, dual G4, etc. -->
 
 
====Development:====
 
 
<pre>. $topsrcdir/camino/config/mozconfig
 
<pre>. $topsrcdir/camino/config/mozconfig
 
ac_add_options --disable-optimize
 
ac_add_options --disable-optimize
 
ac_add_options --enable-debug
 
ac_add_options --enable-debug
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoTrunk</pre>
+
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoTrunk
 
+
mk_add_options MOZ_MAKE_FLAGS=-j4</pre>
'''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:====
+
'''''N.B.''' If you are trying to build on Mac OS X 10.6, please refer to {{bug|514495}} for additional <code>.mozconfig</code> contents.
<pre>. $topsrcdir/camino/config/mozconfig
 
ac_add_options --disable-shared
 
ac_add_options --enable-static</pre>
 
  
====Universal Distribution on a Dual-CPU Mac:====
+
(The MOZ_MAKE_FLAGS setting improves build speed, assuming you have a multi-processor or multi-core machine. For older machines, remove that line.)
<pre>. $topsrcdir/camino/config/mozconfig
 
. $topsrcdir/build/macosx/universal/mozconfig
 
ac_add_options --disable-shared
 
ac_add_options --enable-static
 
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../CaminoUni
 
mk_add_options MOZ_MAKE_FLAGS=-j4</pre>
 
  
If you experience errors when using a <tt>-j</tt> flag, you might need to use a lower value with <tt>-j</tt>. Camino’s dual core, dual processor Xserve uses <tt>-j4</tt> while Camino’s dual processor G5 tinderbox uses <tt>-j2</tt>.
+
For examples of other builds types, or to learn more about the <code>.mozconfig</code> file, see the [[Development:Building:mozconfig|.mozconfig page]].
 
</li>
 
</li>
  
Line 132: Line 96:
 
* To pull the source and build in one step, use:<br />
 
* To pull the source and build in one step, use:<br />
 
<code>$ make -f client.mk</code><br />
 
<code>$ make -f client.mk</code><br />
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 <code>mozilla/dist</code> (or <code>$OBJDIR/dist</code>).<br /><br />
+
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 <code>mozilla/dist</code> (or <code>$OBJDIR/dist</code>).<br />
 +
'''N.B.''' On Mac OS X 10.6, you will need to pull the source first, make changes as detailed in [https://bugzilla.mozilla.org/show_bug.cgi?id=514495#c11 Bug 514495 Comment 11] steps 3 and 4, and then build, so use the “To pull the source without building” instructions below instead.<br /><br />
  
 
* To pull the source without building, use this command:<br />
 
* To pull the source without building, use this command:<br />
<code>$ make -f client.mk checkout MOZ_CO_PROJECT=macbrowser</code><br />You can then build at any time by running <code>make -f client.mk alldep</code> from the <code>mozilla</code> directory.<br /><br />
+
<code>$ make -f client.mk checkout MOZ_CO_PROJECT=camino</code><br />You can then build at any time by running <code>make -f client.mk alldep</code> from the <code>mozilla</code> directory.<br /><br />
  
 
* If you're using the source tarball, use the following instead of the above commands:<br />
 
* If you're using the source tarball, use the following instead of the above commands:<br />
 
<code>$ cd mozilla</code> (if you are not already in <code>mozilla</code>)<br /> <!--they should be there, sorta -->
 
<code>$ cd mozilla</code> (if you are not already in <code>mozilla</code>)<br /> <!--they should be there, sorta -->
<code>$ make -f client.mk alldep</code></li>
+
<code>$ make -f client.mk alldep</code><br />
 +
'''N.B.''' On Mac OS X 10.6, you will need to make changes as detailed in [https://bugzilla.mozilla.org/show_bug.cgi?id=514495#c11 Bug 514495 Comment 11] steps 3 and 4 before invoking <code>make -f client.mk alldep</code>.</li>
 
<!--</ul>-->
 
<!--</ul>-->
 
</ol>                     
 
</ol>                     
Line 145: Line 111:
 
<p>For more information on the build process, see [http://developer.mozilla.org/en/docs/Mac_OS_X_Build_Prerequisites Mac OS X Build Prerequisites] and [http://developer.mozilla.org/en/docs/Mac_OS_X_Universal_Binaries Mac OS X Universal Binaries] in the Mozilla Developer Center.</p>
 
<p>For more information on the build process, see [http://developer.mozilla.org/en/docs/Mac_OS_X_Build_Prerequisites Mac OS X Build Prerequisites] and [http://developer.mozilla.org/en/docs/Mac_OS_X_Universal_Binaries Mac OS X Universal Binaries] in the Mozilla Developer Center.</p>
  
<p>If your build fails, consult the [[#FAQ|FAQ]] section below as well as the [[Development:Building:Build Errors|Common Build Errors]] page.</p>
+
<p>If your build fails, consult the [[Development:Building:FAQ|FAQ]] and [[Development:Building:Build Errors|Common Build Errors]] pages.</p>
  
 
==Development==                     
 
==Development==                     
Line 151: Line 117:
 
         <p>When building with Xcode, make sure your build settings match those in your <code>.mozconfig</code> file: from the &quot;Active Build Style&quot; item in the toolbar, choose &quot;Development&quot; for a debug build, or &quot;Deployment&quot; for an optimized build. If you do not match your settings to your <code>.mozconfig</code>, your build will fail.</p>
 
         <p>When building with Xcode, make sure your build settings match those in your <code>.mozconfig</code> file: from the &quot;Active Build Style&quot; item in the toolbar, choose &quot;Development&quot; for a debug build, or &quot;Deployment&quot; for an optimized build. If you do not match your settings to your <code>.mozconfig</code>, your build will fail.</p>
  
===Widget Code===
+
===Camino code===
If you've edited the Cocoa widget code, you can <code>make</code> in <code>$OBJDIR/widget/src/cocoa</code> 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 <code>cp</code> to copy it into the Camino application package (into <code>$OBJDIR/camino/build/Development/Camino.app/Contents/MacOS/components</code>). (This tactic does not work for static builds, which is why they are not recommended for development.) As an alternative, you can <code>make</code> in <code>$OBJDIR/embedding/config</code> and <code>$OBJDIR/camino</code> again.
+
If you've changed code only within the <code>camino</code> directory, you can ''usually'' rebuild using Xcode. (Again, make sure your build settings match your <code>.mozconfig</code> file). 
 +
 
 +
====<code>.in</code> and generated files====
 +
However, if you’ve edited the source files for certain files that are generated during the build process (e.g., the <code>.in</code> files for <code>.strings</code> files,  <code>all-camino.js</code>, or the <code>Makefile</code>) or any of the <code>embed.jar</code> overrides, you will need to rebuild using the command line: <code>cd $OBJDIR/camino; make</code>
 +
 
 +
===Widget code===
 +
If you've edited the Cocoa widget code, you can <code>make</code> in <code>$OBJDIR/widget/src/cocoa</code> 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 <code>cp</code> to copy it into the Camino application package (into <code>$OBJDIR/camino/build/Development/Camino.app/Contents/MacOS/components</code>). (This tactic does not work for static builds, which is why they are not recommended for development.) As an alternative, you can <code>make</code> in <code>$OBJDIR/embedding/config</code> and <code>$OBJDIR/camino</code> again.
  
 
===Other changes===
 
===Other changes===
If you've changed code only within the <code>camino</code> directory, you can usually rebuild using Xcode. (Again, make sure your build settings match your <code>.mozconfig</code> file).  If you’ve edited certain files that are generated during the build process (e.g., <code>.strings</code> files or <code>all-camino.js</code>) or any of the <code>embed.jar</code> overrides, you will need to rebuild using the command line: <code>cd $OBJDIR/camino; make</code>
+
If you've changed anything outside the <code>camino</code> directory (aside from widget code &mdash; see above), you cannot build from inside Xcode, and will need to <code>make -f client.mk</code> from the <code>mozilla</code> directory (or <code>make</code> from the root of your OBJDIR, if you're using an OBJDIR as recommended by the sample development <code>.mozconfig</code> above).
 
 
<p>If you've changed anything outside the <code>camino</code> directory (aside from widget code &mdash; see above), you cannot build from inside Xcode, and will need to <code>make -f client.mk</code> from the <code>mozilla</code> directory (or <code>make</code> from the root of your OBJDIR, if you're using an OBJDIR as recommended by the sample development <code>.mozconfig</code> above).</p>
 
  
 
===Updating the source and rebuilding===
 
===Updating the source and rebuilding===
Line 167: Line 139:
 
<code>$ cvs update -dP</code><br />
 
<code>$ cvs update -dP</code><br />
 
<code>$ make</code><br /><br />
 
<code>$ make</code><br /><br />
For OBJDIR builds used by most developers, replace <code>make</code> with <code>cd ../../{OBJDIR}/camino; make</code> (the sample development <code>.mozconfig</code> above specifies an OBJDIR by default).</p>
+
For OBJDIR builds used by most developers, replace <code>make</code> with <code>cd ../../{OBJDIR}/camino; make</code> (the sample development <code>.mozconfig</code> above specifies an OBJDIR by default).  Note that in OBJDIR builds, you '''must''' run <code>make</code> from the command line after a <code>cvs update</code> that pulls certain types of changes, including project changes and changes to any <code>.strings</code> file, since updated versions of these files are copied into the OBJDIR or regenerated by Makefile targets.</p>
  
 
===Hacking <code>configure</code>===
 
===Hacking <code>configure</code>===
  
Sometimes you need to hack a <code>[http://developer.mozilla.org/en/docs/configure.in configure]</code> script to make Camino build a new Gecko extension (<code>mozilla/extensions/foo</code>) or some other configurable part of the build.  To do this, you have to patch <code>configure.in</code> and then regenerate your local <code>configure</code> to test the build with your changes.
+
On rare occasions you may need to hack a <code>[http://developer.mozilla.org/en/docs/configure.in configure]</code> script to make Camino build a new Gecko extension (<code>mozilla/extensions/foo</code>) or some other configurable part of the build.  To do this, you have to patch <code>configure.in</code> and then regenerate your local <code>configure</code> to test the build with your changes.
  
To do this, you need <code>[http://developer.mozilla.org/en/docs/Mac_OS_X_Build_Prerequisites#Software_Requirements autoconf-2.13]</code> (the version of <code>autoconf</code> that ships with all Mac OS X developer tools will not work).  After you install <code>autoconf</code>, you regenerate <code>configure</code> simply by <code>cd mozilla</code> and <code>autoconf-2.13</code>.  Then rebuild your tree as usual.
+
To do this, you need <code>[[#Installing libIDL|autoconf-2.13]]</code> (the version of <code>autoconf</code> that ships with all Mac OS X developer tools will not work).  After you install <code>autoconf-2.13</code>, you regenerate <code>configure</code> simply by <code>cd mozilla</code> and <code>autoconf213</code>.  Then rebuild your tree as usual.
  
 
===Packaging a build for testing===
 
===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 <strong>build with a “distribution” <code>.mozconfig</code></strong>.  Then, when your build is complete, run <code>make</code> in <code>{OBJDIR}/camino/installer</code> to produce a disk image for distribution.  You can use your existing source tree but “swap in” a deployment <code>.mozconfig</code> the defines a new OBJDIR to provide a clean build.
+
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 <strong>build with a [[Development:Building:mozconfig#Sample_.mozconfig|“distribution” <code>.mozconfig</code>]]</strong>.  Then, when your build is complete, run <code>make</code> in <code>$OBJDIR/camino/installer</code> to produce a disk image for distribution.  You can use your existing source tree but “swap in” a deployment <code>.mozconfig</code> that defines a new OBJDIR to provide a clean build.
 
<!-- you do this just by "swapping" .mozconfigs and defining a new objdir -->
 
<!-- you do this just by "swapping" .mozconfigs and defining a new objdir -->
  
 
===Cleaning your tree===
 
===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, <code>cd</code> to <code>mozilla</code> and try <code>make -f client.mk clean</code>. If that doesn't work, you need to <code>make -f client.mk distclean</code>.
 
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, <code>cd</code> to <code>mozilla</code> and try <code>make -f client.mk clean</code>. If that doesn't work, you need to <code>make -f client.mk distclean</code>.
 
==FAQ==
 
<!-- this section needs to be converted to h3s for questions when h3 text is not larger than h2 text :p -->
 
====Q. What versions of Mac OS X, Xcode, development SDK, and gcc are supported for building Camino?====
 
<strong>A.</strong> There is a constantly-updated [http://wiki.mozilla.org/Mac:Build_Requirements#Compatibility_Matrix matrix] of working build configurations on the Mozilla Wiki.
 
        <p>However, Camino officially supports building with Xcode 2.4.1 or higher, '''10.4u SDK, and gcc 4 on Mac OS X 10.4.11 or 10.5.1''' (Xcode 2.5 recommended for Mac OS X 10.4.11, and Xcode 3.0 recommended for Mac OS X 10.5.x), and these build instructions and the default <code>.mozconfig</code> 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, [[Development:Building:SDK Support|SDK Support]] documents the known states of various OS/compiler/SDK combinations when building Camino code.--></p>
 
 
====Q. Can I build on Case-Sensitive HFS or UFS?====
 
<strong>A.</strong> Yes, on the trunk, the MOZILLA_1_8_BRANCH, and the CAMINO_1_5_BRANCH.<!--  ''At least we think so''; '''this needs verification'''-->
 
 
====Q. How do I build a release version of Camino or build Camino from a specific branch?====
 
<!--this needs some cleanup yet-->
 
<strong>A.</strong> 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 [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source source tarball] for that release instead of checking out source from cvs.
 
      <p>For release builds of Camino, be sure to add the following lines to your <code>.mozconfig</code> file:<br /> <code>ac_add_options --disable-shared</code><br />
 
<code>ac_add_options --enable-static</code><br /><br />
 
After editing your <code>.mozconfig</code>, start your build by running <code>make -f client.mk</code> from your <code>mozilla</code> directory.</p>
 
      <p>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 <code>cvs co</code> commands to include the appropriate branch tag.  To build Camino code on the Mozilla 1.8 branch (Camino 1.6.x), the appropriate commands are as follows:<br /> <code>$ cvs co -r MOZILLA_1_8_BRANCH mozilla/client.mk</code><br />
 
<code>$ cvs co -r MOZILLA_1_8_BRANCH mozilla/camino/config/mozconfig</code><br /><br />
 
Note that <strong>all Camino development is done on the trunk</strong> and back-ported to the branches if needed, so those wishing to become involved in Camino development should follow the main instructions.</p>
 
<p>'''Note''' that Camino 1.6.x/MOZILLA_1_8_BRANCH, Camino 1.5.x/CAMINO_1_5_BRANCH, and Camino 1.0.x/MOZILLA_1_8_0_BRANCH '''all require different SDK and compiler configurations from the trunk, as well as changes to the Shared Menus Framework, in order to build'''; see the [[#Appendix|Appendix]] for more information.</p>
 
 
====Q. What are the cvs tags for recent branches, releases, and milestones?====
 
<strong>A.</strong> Use the following cvs tags in your <code>cvs co -r</code> commands above in order to build these versions of Camino:<ul>
 
<!--<li><code>MOZILLA_1_8_BRANCH</code> - ''Ongoing Camino 1.6b4pre development (will become Camino 1.6)''</li>-->
 
<li><code>CAMINO_2_0_A1_RELEASE</code> - ''Camino 2.0 Alpha 1 milestone release''</li>
 
<li><code>MOZILLA_1_8_BRANCH</code> - ''Camino 1.6.x security releases''</li>
 
<li><code>CAMINO_1_6_5_RELEASE</code> - ''Camino 1.6.5 release''</li> <!-- change this to 1.6.6 when it's released-->
 
<li><code>CAMINO_1_5_5_RELEASE</code> - ''Camino 1.5.5 legacy release (for 10.3.0-10.3.8 users)''</li>
 
<!--<li><code>CAMINO_1_5_BRANCH</code> - ''Camino 1.5.x security releases''</li>-->
 
<li><code>CAMINO_1_0_6_RELEASE</code> - ''Camino 1.0.6 legacy release (for 10.2.8 users)''</li></ul>
 
 
====Q. Why can't I get a fresh copy of Camino to build?====
 
<strong>A.</strong> Despite our best efforts, sometimes the Mozilla or Camino tree is &quot;red,&quot; meaning that the source code won't build properly in its current state. Before you pull, you can check the status on [http://tinderbox.mozilla.org/showbuilds.cgi?tree=Camino Camino's tinderbox]. If the Camino tinderbox or the Mac builds in the  [http://tinderbox.mozilla.org/showbuilds.cgi?tree=SeaMonkey SeaMonkey] or  [http://tinderbox.mozilla.org/showbuilds.cgi?tree=Firefox Firefox] tinderboxes are red, you probably should avoid checking out.
 
 
          <p>If your build fails, just wait until things go green again and re-pull Camino.</p>
 
<!-- restore this when it works again on wiki.cbo          <p> (Confused? Here's an [http://www.caminobrowser.org/development/programming/#tinderbox introduction to Tinderbox]).</p>-->
 
 
          <p>If the tree was green when you pulled your source, consult the list of [[Development:Building:Build_Errors|common build errors]] and see if your error is listed. If so, follow the steps listed there to fix your build.</p>
 
 
====Q. I get an error from the Terminal or from Xcode when trying to build Camino; what's wrong?====
 
<strong>A.</strong> Consult the list of [[Development:Building:Build_Errors|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?====
 
<strong>A.</strong> This has most likely occurred because you are building from within Xcode and have set up your <code>.mozconfig</code> 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 <code>.mozconfig</code> and Xcode, or just build from the command line using <code>make -f client.mk</code>.
 
 
====Q. What if I still can't get Camino to build?====
 
<strong>A.</strong> First check the [[Development:Building:Build_Errors|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 [irc://irc.mozilla.org/#camino #camino] IRC channel at [irc://irc.mozilla.org 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 [http://forums.mozillazine.org/viewforum?f=12 Camino forum at MozillaZine] has a number of regulars who can usually solve your build woes.
 
  
 
==Appendix==
 
==Appendix==
  
 +
* [[Development:Building:FAQ|Build FAQ]]
 
* [[Development:Building:Build Errors|Common Build Errors]]
 
* [[Development:Building:Build Errors|Common Build Errors]]
 +
* [[Development:Building:mozconfig|.mozconfig Details]]
 +
* [[Development:Building:Common make Targets|Common <tt>make</tt> Targets]]
 +
* [[Development:Building:Mozilla_1.9.2_Branch|Building on the Mozilla 1.9.2 branch]]
 
* [[Development:Building:Mozilla 1.8.* Branches|Building on the Mozilla 1.8.* branches]] (Camino 1.6.x, Camino 1.5.x, Camino 1.0.x) ''(in progress)''
 
* [[Development:Building:Mozilla 1.8.* Branches|Building on the Mozilla 1.8.* branches]] (Camino 1.6.x, Camino 1.5.x, Camino 1.0.x) ''(in progress)''
 
* [[Development:Building:Building_Dependencies_from_Source|Building Dependencies from Source]] ''(in progress)''
 
* [[Development:Building:Building_Dependencies_from_Source|Building Dependencies from Source]] ''(in progress)''
 +
* [[Development:Providing Software Update for Third-Party Camino Builds|Providing Software Update for Third-Party Camino Builds]]
 +
 +
</div>

Latest revision as of 16:00, 10 June 2010

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.10 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.1 are recommended). 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 (and thus Camino) does not yet build “out-of-the-box” on Mac OS X 10.6. For more information about local changes required to build on Mac OS X 10.6, see Bug 514495.

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, 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. Trunk versions of currently Camino require the 10.4u SDK for PPC, Intel, and Universal builds. If you are building other 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 and Mac OS X 10.5.1 as of December 2007) and the latest Xcode version available for that version of Mac OS X (Xcode 2.5 on 10.4.11, Xcode 3 on 10.5.1).

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) before building Camino.

Installing libIDL

Mozilla requires libIDL (and autoconf-2.13, in the unlikely event that you need to hack any Mozilla configure scripts) in order to build. 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. (The +universal flag is not necessary on Mac OS X 10.4 or 10.5.)
    2. sudo port install autoconf213
      The above command installs autoconf-2.13 to /opt/local/bin/autoconf213 using MacPorts (you can skip this step, and install it later if you find need it). 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.

There are reports that 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.

Setting up your CVS Environment

N.B. Future Camino development is in the process of moving to Mercurial; please see Development:Building:Mozilla 1.9.2 Branch for Mercurial-related build instructions.

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.

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. Future Camino development is in the process of moving to Mercurial; please see Development:Building:Mozilla 1.9.2 Branch for Mercurial-related build instructions.

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.

N.B. If you are trying to build on Mac OS X 10.6, please refer to Bug 514495 for additional information.

If you are building from the source tarball, skip to step 4 of this section. Be sure to follow the link to learn about other .mozconfig settings, since the sample is for a development build.

  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 mozilla/camino/config/mozconfig 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.
    If you need to build Camino 2.0.x security and stability releases, replace cvs co with cvs co -r CAMINO_2_0_BRANCH in the checkout command above.
  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. 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 Bug 514495 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.

  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).
    N.B. On Mac OS X 10.6, you will need to pull the source first, make changes as detailed in Bug 514495 Comment 11 steps 3 and 4, and then build, so use the “To pull the source without building” instructions below instead.

    • To pull the source without building, use this command:
    $ make -f client.mk checkout MOZ_CO_PROJECT=camino
    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
    N.B. On Mac OS X 10.6, you will need to make changes as detailed in Bug 514495 Comment 11 steps 3 and 4 before invoking 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 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 embed.jar overrides, you will need to rebuild using the command line: cd $OBJDIR/camino; make

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/embedding/config and $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).

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-M1.9” and “CmTrunk” 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:
$ make -f client.mk
(To pull updated source files for the entire tree without rebuilding, substitute $ make -f client.mk checkout for the second command, and then make as usual when you are ready to 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:
$ 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). Note that in OBJDIR builds, you must run make from the command line after a cvs update 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.

Hacking configure

On rare occasions you may need to hack a configure script to make Camino build a new Gecko extension (mozilla/extensions/foo) or some other configurable part of the build. To do this, you have to patch configure.in and then regenerate your local configure to test the build with your changes.

To do this, you need autoconf-2.13 (the version of autoconf that ships with all Mac OS X developer tools will not work). After you install autoconf-2.13, you regenerate configure simply by cd mozilla and autoconf213. Then rebuild your tree as usual.

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