Old Wiki:DevelopingCamino
Back to Old Wiki Main Page
Contents
Camino Development
Want to help us develop Camino? Come right in! Whether you're a student or a guru, we want your assistance. You can get in touch with the Camino developer community to get started -- or read below for a quick overview.
(Don't know how to code at all? There are still other ways you can contribute!)
Goals
Camino is meant to be a simple browser, developed within the following parameters:
- OS X Native UI
- Gecko HTML rendering engine (the engine used by Mozilla and Firefox)
- "Well-behaved" OS X application, taking advantage of the capabilities and features of the operating system and available frameworks, and making an effort to comply with Apple's Human Interface Guidelines
- No email, no address book, no being able to search the web from your javascript console. Just a browser, plain and simple.
To keep Camino easy to develop, as useful a browser, and as "well-behaved" an OS X application as possible, we:
- Use the Cocoa frameworks and Apple's InterfaceBuilder to develop the user interface;
- Leverage the embeddable Gecko Cocoa view provided by CHBrowserView, for the rendering engine;
- Keep the project buildable and debuggable from Xcode.
Camino Development Cycle and Conventions
The Camino development cycle describes in what order development stages have to be completed. The development cycle is designed to facilitate communication within the developer community and, through code review, help ensure that code is not changed carelessly.
- Choose a bug or feature to work on. (If you're not sure what bugs to work on, try searching Bugzilla for unassigned bugs.)
- Make sure a bug has been filed in Bugzilla for the bug you've chosen.
- Let the community know you're working on the bug by assigning the bug to yourself in Bugzilla and contacting the IRC channel or the mailing list.
- Develop your patch. When you think your patch is complete, attach it to the corresponding bug report.
- Request two (2) reviews by setting the review flag and entering the reviewers' email addresses. You can request a review when first uploading the patch, or later by going back and clicking the "Edit" link corresponding to your patch in the "Actions" column of the Attachments table of the bug. Please note that it is considered polite to ask first on the #camino IRC channel at irc.mozilla.org whether the people from whom you intend to request reviews have time for the review.
- When your patch has been reviewed, make sure you incorporate any comments made by the reviewers.
- When both reviewers are positive about the patch (the review flag will be set to "+") you will have to ask for a super review (the same way you ask for a basic review, but fewer people are authorized for super-review).
- When the super review passes, the patch will get checked-in to the source code tree in #CVS CVS as soon as possible.
Please Note: You will have a much easier time getting your code past review if you are familiar with the Mozilla coding practices.
Conventions
Whenever you begin work on something that’s more than a day’s work, we strongly recommend that you let people know about it. Post your plans to the Camino mailing list or let people on the #camino IRC channel (on irc.mozilla.org) know what you are going to do.
If you’re working on fixing a bug, make a note of it in the bug report in Bugzilla to track your progress and to catch the attention of the other developers. If no bug exists already, then file a new bug and assign it to yourself. When adding features, consider adding an enhancement request for the feature in Bugzilla and talking to others about it before implementing it.
Publicizing your efforts lets others know what you’re working on so they can coordinate their work with yours, offer help, and avoid duplicating your work. It opens your work up for peer review, and provides an archive so the same issues don’t need to be rehashed the next time the question comes up. Also, if someone else is working on the same thing, they can let you know and save you a lot of work.
Also see:
Tools We Use
Bugzilla
Bugzilla is a database for bugs (and feature requests). It lets people report bugs and assigns these bugs to the appropriate developers. Developers can use Bugzilla to keep a to-do list as well as to prioritize, schedule and track dependencies.
Note: not all 'bugs' are bugs! Feature requests (also called Requests For Enhancement -- RFE for short) are tracked as Bugzilla entries with the "severity" field set to "enhancement." People often say "bug" when they mean "item in Bugzilla," so RFEs often wind up being called bugs.
Enter the tasks you plan to work on as bugs or enhancement requests: Bugzilla will help you track them and allow others to see what you plan to work on. If people can see your flight plan, they can avoid duplicating your work and can possibly help out or offer feedback.
Also see:
CVS
CVS maintains a history of changes made to files in a source tree by tracking the differences between the state of each file before and after each update. It stamps each change with the time it was made and the username of the person who made it. Usually, the person also provides a brief comment describing why they made the change.
Given that information, CVS can answer questions like:
- Who made a given change?
- When did they make it?
- Why did they make it?
- What other changes did they make?
If you're very unfamiliar with CVS, you may find an introduction to CVS useful.
CVS Access -- Check-out and Check-in
Anybody can download a copy of the Camino source from the Mozilla Foundation's central CVS repository to look at or build on their own computer. You can also browse the code without downloading it, using Bonsai CVS. However, only those developers that are familiar enough with the Mozilla and Camino code can get an account to submit changes to the repository themselves. This helps ensure that check-ins do not introduce new bugs. If you do not have an account, someone else will check your code in after it has been approved. The approval process is explained in our development cycle.
CVS Client
To get your copy of the Camino source code from the repository, you will need a CVS client. While a number of graphical CVS clients are available on OS X, the command-line client (automatically included when you install Apple's Developer Tools / Xcode) is recommended for pulling Camino source from the main repository.
Fink
Fink is a program that modifies Unix software so that it compiles and runs on Mac OS X. Fink also provides easy download and installation of this software, using tools adapted from Debian's dpkg and apt-get.
Camino developers use Fink to install Orbit, a software package required build Camino and the OS X version of Mozilla.
Tinderbox
Each Mozilla project (including Camino) is constantly being rebuilt from the latest source to ensure that there is always a working version to test, and to catch any problems that would block the build before they get too far out of hand.
Tinderbox is a detective tool that allows you to keep track of the latest changes to the source code and how they affect the status of the various builds (for each project and each platform). Builds in progress are shown yellow; successful builds are green; unsuccessful ("broken") builds are red.
Camino builds are currently run on a G3 Mac ("pawn") and a G4 Mac ("boxset"). Before doing a CVS checkout, you'll want to visit Camino's Tinderbox to make sure the code you check out will build successfully on your platform. If the most recent build is green, you're set to go; if it's yellow, you may wish to wait until that build completes -- you won't know until then whether or not it will build properly; if it's red, you'll want to wait until the most recent build is green.
Tinderbox also shows you who checked in which patches; what platforms have built successfully; what platforms are broken and exactly how they are broken (the build logs); and the state of the files that made up the build ("cvsblame"). You can use this information to figure out whose check-ins broke the build -- so you can make sure they fix it.
Gecko
The page layout and rendering engine that Camino shares with Mozilla and Firefox is commonly known as "Gecko." Gecko is already (arguably) the most complete and standards-compliant rendering engine available -- and it is constantly undergoing further improvement. Gecko is embedded into Camino using an element called CHBrowserView that permits it to be used within fully native OS X applications. If you want to work on the way webpages appear within Camino, the following resources will help you familiarize yourself with Gecko:
Cocoa, Objective-C, and Xcode
Camino embeds the cross-platform "Gecko" rendering engine into a native OS X application. The OS X part of Camino is developed using the "Cocoa" application environment, a rich set of object-oriented frameworks for developing native Mac applications.
While Cocoa can also be accessed using Java, we use the Objective-C language (an extension of C), which allows better integration with both the Cocoa frameworks and the Gecko engine. Please see below for websites and books that provide an introduction to the Cocoa frameworks and the Objective-C language.
CHBrowserView, the class that incorporates the Gecko engine (developed in C++) and enables it to be smoothly embedded within an Objective-C Cocoa application like Camino, is developed using Objective-C++ (a variant of Objective-C that is compatible with C++). If you have used both C++ and Objective-C, Objective-C++ should look familiar.
All Camino development is done within Apple's Xcode development environment, which is provided free with recent versions of OS X and is also available as a free download from Apple. (Xcode requires OS X v10.3.x or above).
Sites with more information:
Books you might want to read:
Developer Community and Support
If you have questions about developing Camino, if you're interested in contributing but don't know where to start, or if you're stuck on a knotty development problem with Camino, we recommend contacting the community by stopping by the #camino IRC channel or getting in touch with the mailing list.
Licenses and Legal Mumbo-Jumbo
At the moment, parts of the Mozilla and Camino source are available under either the Netscape Public License (NPL) or the Mozilla Public License (MPL), often in combination with either the GNU General Public License (GPL) or the GNU Lesser General Public License (LGPL), or both.
Essentially, if you wish to download the source and build a modified or unmodified version for your personal use, you are free to do so. If you wish to contribute code to the project, you are encouraged to do so, but you must agree to license the code you contribute in compliance with Mozilla's licensing policy.
Licensing for redistribution or for using parts of the code in other projects is a bit more complex because the code is not all available under a single license. If you intend to redistribute Camino source, distribute Camino binaries other than those created by the Mozilla foundation, or incorporate the source into another application that you plan to distribute, the licensing policy is a good place to start, and you will need to familiarize yourself with the text of the licenses. The [Old Wiki:CaminoCommunity|Camino community] may be able to help with some licensing questions.
Mozilla.org is working towards having all the code in the tree licensed under a MPL/LGPL/GPL tri-license; for more information, see the Relicensing FAQ.
