Old Wiki:BuildingCamino
Back to Old Wiki Main Page
What follows is a direct copy from the other wiki. I have not formatted this like I have other pages.
!Building Camino
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 Dev/DevelopingCamino 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
!!!Xcode
Panther (OS X version 10.3.x) and Xcode (version 1.1 or later) are now required for building Camino. (Note that this is not a requirement to build Mozilla.) Xcode is included on a separate disk with the purchase of a new Mac or a copy of Panther, and is available as a [free download] from Apple.
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.
!!!Fink
Follow the instructions on the [Mozilla OS X build page] for installing Fink, using it to install Orbit, and on downloading and installing the Shared Menus framework. As stated in those instructions, if you had installed Fink and Orbit prior to upgrading from Jaguar to Panther, we recommend that you remove the @@/sw@@ directory entirely and install a fresh copy of Fink 0.7.0 or later and a fresh copy of Orbit.
!!!Shared Menus Framework Reference
You will need to create a reference, inside the SDK folder for 10.2.8, to the Shared Menus Framework:
- Check to see if you have the folder @@/Developer/[=SDKs/MacOSX10.2.8.sdk=]@@. If so, skip to step 3.
- Otherwise, check for the folder @@/Developer/[=SDKs/MacOSX10.2.7.sdk=]@@. If you have it, create a symlink:\\
@@$ ln -s /Developer/[=SDKs/MacOSX10.2.7.sdk=] /Developer/[=SDKs/MacOSX10.2.8.sdk=]@@\\
\\ If not, install the Xcode Cross Development tools as described above.
- @@$ mkdir -p /Developer/[=SDKs/MacOSX10.2.8.sdk=]/Library/Frameworks@@
- @@$ cd /Developer/[=SDKs/MacOSX10.2.8.sdk=]/Library/Frameworks@@
- @@$ ln -s /Library/Frameworks/[=SharedMenusCocoa.framework SharedMenusCocoa.framework=]@@
!!!Setting up your CVS Environment
Prepare your CVS client using the following parameters:
- server: @@cvs-mirror.mozilla.org@@
- root directory: @@cvsroot@@
- username: @@anonymous@@
- password: @@anonymous@@
If you are using the command line client (recommended) from the bash shell (the default for OS X 10.3), the following command will set up and save the above server connection information:
@@$ export CVSROOT=:pserver: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 other commands are the same. You can get to a bash shell at any time by typing "@@bash@@" at the command line and hitting "return."
To connect to the CVS server, enter the command
@@$ cvs login@@
Enter the password when prompted. You are now ready to pull the source code from the server.
!!Pulling Source and Building Mozilla and Camino
- @@cd@@ into the directory where you would like to keep your copy of the Camino source code.
- Pull the main build makefile and configuration directory:\\
@@$ cvs co mozilla/client.mk@@\\ @@$ cvs co mozilla/camino/config/mozconfig@@
- @@cd@@ into the @@mozilla@@ directory that was just created:\\
@@$ cd mozilla@@
- 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. To begin, add the following line to your @@.mozconfig@@ file:\\
@@. $topsrcdir/camino/config/mozconfig@@
- [+ 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:\\ @@ac_add_options --disable-optimize\\ ac_add_options --enable-debug@@\\ \\ Please Note: It's important to be aware of whether you've set up @@.mozconfig@@ 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.
- [+ 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 .mozconfig:\\ \\ @@ac_add_options --disable-shared\\ ac_add_options --enable-static@@\\ \\ Static builds are used for distribution but are not recommended for development.
- [+ Building More Quickly on Dual-CPU Machines +]\\
\\ If your machine has two [=CPUs=], you can take advantage of that while building Camino. Add the following to your @@.mozconfig@@:\\ \\ @@mk_add_options MOZ_MAKE_FLAGS=-j4@@
- 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 package ends up in @@mozilla/camino/build@@.
- To pull the source without building, use the command:\\
@@$ make -f client.mk checkout MOZ_CO_PROJECT=macbrowser@@\\ \\ You can then build at any time by running @@make -f client.mk@@ from the @@mozilla@@ directory.
!!Development
To work on Camino front-end code, open up the @@Camino.xcode@@ project (from the @@camino@@ directory) in Xcode. You can edit code, build, and run from inside of Xcode.
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.
!!!Widget Code
If you've edited the Cocoa widget code, you can @@make@@ in @@mozilla/widget/src/cocoa@@ 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 @@cp@@ to copy it into the Camino application package (into [@mozilla/camino/build/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 @@embedding/config@@ and @@mozilla/camino@@ again.
!!!Other changes
If you've changed code only within the @@camino@@ directory, you can rebuild using Xcode. (Again, make sure your build settings match your @@.mozconfig@@).
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.
!!FAQ
- Q. Why can't I get a fresh copy of Camino to build?:\
A. Despite our best efforts, sometimes the Mozilla or Camino tree is "red," meaning that the source code won't build properly in its current state. Before you pull, you can check the status on [Camino's tinderbox]. If the Camino tinderbox or the Mac builds or UNIX/Linux builds in the [Mozilla (aka SeaMonkey)] or [Firefox] tinderboxes are red, you probably should avoid checking out. \\ \\ If your build fails, just wait until things go green again and repull Camino.\\ \\ (Confused? Here's an Dev/DevelopingCamino#tinderbox introduction to Tinderbox).
- Q. I get a link error when building Camino:\
A. This has most likely occurred because you are building from within Xcode and have set up @@.mozconfig@@ 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 @@.mozconfig@@ and Xcode. Or just build from the command line using @@make -f client.mk@@.
- Q. My Camino build crashes at startup -- what's wrong?:\
A. Again, you probably built one piece optimized and the other in debug mode. Make sure they match and try again.
- Q. I get errors that the Camino build failed at some <[=CopyFilesX=]> where X is some number.:\
A. Usually this is because you forgot to @@make@@ in @@embedding/config@@ after making code changes. Follow the instructions carefully, and try again.
- Q. What if I still can't get Camino to build?:\
A. There are two places to go for help building Camino:\\
- The #camino IRC channel at 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.\\
- Join and post to the [Camino mailing list].
