View source for User:Smorgan/BuildInstructionsRefactor

<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.

</div>


        <div class="note">
          <p><strong>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 <!--Cocoazilla (a separate project to implement the full Mozilla suite using Cocoa), or -->CHBrowserView, which is just one piece of Camino. If you are new to Camino development, please see our [http://www.caminobrowser.org/development/ developer introduction] for an overview of project conventions and the tools you'll need.</strong></p> <!-- change that link to wiki's contrib overview when that is suitably complete -->
        </div>

        <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== 
        <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>

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.

===Installing Mac OS X Cross Development SDKs===
        <p>Camino requires a custom Xcode installation to build properly: during installation, click the &quot;Customize&quot; button and turn on the &quot;Cross Development&quot; 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|Appendix]] for details.</p><!-- do we need to specify which SDKs? it's mentioned in the FAQ-->

        <p>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).</p>

=== 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 <code>/Library/Caches/com.apple.Xcode.501/SharedPrecompiledHeaders</code> (where <code>501</code> is your user ID) before building Camino.

==<code>libIDL</code> and <code>glib</code>== 
<!-- or "Third-Party Build Dependencies" or something instead ?
-->
<!--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-->
Mozilla requires <code>libIDL</code> (and <code>autoconf-2.1.3</code>, if you plan 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 a package manager like [http://www.macports.org/ MacPorts] (formerly DarwinPorts) or [http://www.finkproject.org/ Fink].  MacPorts is more commonly used and is recommended.  When installing a new major version of Mac OS X, be sure to upgrade your package manager to the version appropriate for that Mac OS X version.

# Download the [http://www.macports.org/install.php#pkg latest MacPorts release] for your version of Mac OS X and install it.
#: 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.
# 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>sudo port install libidl</code>
##: This will take some time as the sources for <code>libIDL</code> and its dependencies are downloaded and installed. 
## <code>sudo port install autoconf213</code>
##: The above command installs autoconf-2.13 to <code>/opt/local/bin/autoconf213</code> using MacPorts. 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.'''

==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.''
        <p>Prepare your CVS client using the following parameters:</p>
        <ul>
          <li><code>server: cvs-mirror.mozilla.org</code></li>
          <li><code>root directory: cvsroot</code></li>
          <li><code>username: anonymous</code></li>
          <li><code>password: anonymous </code></li>
        </ul>
        <p>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:</p>

        <p><code>$ export CVSROOT=:pserver:anonymous:anonymous@cvs-mirror.mozilla.org:/cvsroot</code></p>
        <p>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 &quot;bash&quot; at the command line and hitting &quot;return.&quot;)</p>
        <p>For more information on Mozilla CVS, see [http://developer.mozilla.org/en/docs/Mozilla_Source_Code_Via_CVS Mozilla Source Code Via CVS].</p>

==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 [[Development:Building:FAQ|FAQ]] for changes you will need to make to some of these commands.''

''If you are building from the [ftp://ftp.mozilla.org/pub/mozilla.org/camino/source source tarball], skip to step 4 of this section.  '' 

<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>Pull the main build makefile and configuration directory:<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.
          </li>
          <li><code>cd</code> into the <code>mozilla</code> directory that was just created:<br />
            <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. For a development build add the following to your <code>.mozconfig</code> file (note the leading dot and space):<br />

<pre>. $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</pre>

(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 <code>.mozconfig</code> file, see the [[Development:Building:mozconfig|.mozconfig page]].
</li>

<li>Pull source and build:
* To pull the source and build in one step, use:<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 />

* To pull the source without building, use this command:<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 />
<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>
<!--</ul>-->
</ol>                    

<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 [[Development:Building:FAQ|FAQ]] and [[Development:Building:Build Errors|Common Build Errors]] pages.</p>

==Development==                    
        <p>To work on Camino application code, open up the <code>Camino.xcodeproj</code> project (from the <code>camino</code> 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.)</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>

===Camino code===
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===
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).

===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.)
        <p>Before updating your tree, visit the [http://tinderbox.mozilla.org/showbuilds.cgi?tree=Camino 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 <code>cd</code> to your <code>mozilla</code> directory and run the following commands '''to update and rebuild your entire tree''':<br />
<code>$ make -f client.mk</code><br />
(To pull updated source files for the entire tree without rebuilding, substitute <code>$ make -f client.mk checkout</code> for the second command, and then <code>make</code> as usual when you are ready to build.)<br /><br />
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''', <code>cd</code> to your <code>mozilla/camino</code> directory and run the following commands:<br />
<code>$ cvs update -dP</code><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).  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>===

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.

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.

===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> that defines a new OBJDIR to provide a clean build.
<!-- you do this just by "swapping" .mozconfigs and defining a new objdir -->

===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>.

==Appendix==

* [[Development:Building:FAQ|Build FAQ]]
* [[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.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)''