Calendar:Build

<< Back to Calendar Home Page

This guide gives you all the information you need to get started with calendar development. While this guide might be quite long, I assume you will need 20-30 minutes ( + time to build the app) to set up everything and have a running development environment.

Note this guide is written for use directly from the console. There is no known documentation to set up a build environment inside IDE's like eclipse. If you manage to set up eclipse for calendar, it would be great if you could contribute documentation!

Setting up prerequisites

General documentation here

The general section on build prerequisites is quite complete and should be used to determine what is needed.

Additional, Mac-Specific info

You should install Xcode (i.e 2.4.1). This may be available on your MacOS Tiger restore CD (takes about ten minutes)

Next you need to install either Fink or MacPorts. I went with MacPorts. You can download it here. Installing MacPorts is as simple as running the installer found in the mounted .dmg. (five minutes)

Next, use MacPorts to install libIDL (which also installs GLib). You will need to have your administrative password ready; takes around five to ten minutes, depending on your internet connection.

sudo port sync
sudo port install libidl

Getting the source

There is extensive documentation on how to get the Calendar source code on developer.mozilla.org.

The source code must be checked out via Mercurial (hg).

In general, you should use a directory for the source code that does not contain spaces or such, i.e on windows "C:\Documents and Settings\MyUsername\My Documents\mozilla" is not a good choice.

Before you start to build, you will need to configure your build environment to build Lightning. Since Lightning is an extension it needs to be built together with its host application Thunderbird.

# Enter the source directory
cd src (we assume that src/ is your source directory here)

# Generate a mozconfig yourself, or use this minimal default one for Thunderbird
echo 'ac_add_options --enable-application=mail' > .mozconfig

# Add calendaring to Thunderbird
echo 'ac_add_options --enable-calendar' >> .mozconfig

# Builds with the object directory the same as the source directory are not
# supported, so set the object directory here. Note: Whether you have the
# object directory within the source directory is up to you. .hgignore includes
# objdir-* and obj-*, making your object directory start with one of them
# will make change finding easier and hg faster, but moving it to outside
# will make things like grep easier and quicker as well.
echo 'mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../objdir-tb' >> .mozconfig

# configure will be automatically generated using the 'autoconf-2.13'
# command.  If autoconf-2.13 isn't the right name for your system, as
# is the case on OS X using MacPorts and on Ubuntu Linux, use the 
# real command name as demonstrated below. (Note: it's "autoconf2.13"
# rather than "autoconf213" for Ubuntu 8.04, at least.)
echo 'mk_add_options AUTOCONF=autoconf213' >> .mozconfig

# Now do the build; configure will be run automatically
make -f client.mk build

Building the source (first time)

If you have not previously built the source with the tree you just checked out, you need to do a full compile. Depending on platform and computer specs, this might take a while (Example: MacBook Pro, 2.2Ghz, 2GB ram, ~25-30 Minutes) Go have a beer in between or whatever you prefer :-) This will not be needed as often later on.

If everything went well, the last output won't contain any errors and you are ready to start your development build of sunbird. If you run into problems, please see the troubleshooting section at the bottom of this page.

Running Lightning

This section assumes you have a working Thunderbird (3.0 beta2 or later) installed. The best way to add Lightning to Thunderbird is to follow the general steps, but for Lightning and Thunderbird. The extension ID for Lightning is {3550f703-e582-4d05-9a08-453d09bdfdc6}. You should use a separate profile for development, to not destroy your normal profile.

The following steps make it easy on Linux, the profile path may be a bit different depending on your system. Remember to replace your profile name. This might also work out in a similar form on Windows and Mac.

# Enter the Lightning directory in your object directory
cd @TOPSRCDIR@/../objdir-tb/dist/xpi-stage/lightning

# Create a new profile directory
pwd > ~/.mozilla-thunderbird/<development profile path>/extensions/{3550f703-e582-4d05-9a08-453d09bdfdc6}

Now you can start thunderbird with your development profile.

thunderbird -P <development profile name>

This way, when you change code you will always be able to use the latest code, without reinstalling the extension.

Updating Calendar

If something has changed in calendar code, you will want to get the latest changes. The general documentation suggests you use client.py to get all new changes:

# Enter the source directory
cd src

# Update your local hg repository with the newest changes
python client.py checkout

Building Sunbird and Lightning (after first time)

After you have done a full build, it is usually not necessary to do the full build again for a while. The only case you might want to do a full build again is if something changed outside of calendar code that seems to affect building calendar (i.e a toolkit change).

Lightning

Lightning always needs to be made in one piece, so just issue the following command:

# Enter the Lightning source directory in your object directory
cd @TOPSRCDIR@/../objdir-tb/calendar/lightning

# Start building
make

After this you can start thunderbird with your development profile, and you should be up to date.

Debugging and Preferences

You should set up your debugging environment in the same way you would for extension development. A nice guide can be found here on developer.mozilla.org.

Getting started with coding

This of course depends on what you want to do. Usually, people come to the project since they want something specific fixed. If you are proficient with developing in large projects, you probably know how to get started and can directly start with whatever you wanted to fix. Its always a good idea to see if there is already a bug filed, in case someone else is working on it. If not, go ahead and file the bug and assign it to yourself.

If you don't have much experience with a larger project but do have an idea what you want to fix, then you can take a look at the old dev guide or the calendar hacking guide. While both are not always up to date, they give some information on the parts of code in calendar.

On the other hand, if you have no idea what to start with but would really like to develop calendar code, you can take a look at the list of good first bugs.

A lot of Calendar code is written in Javascript. This makes it easy to start with development. The user interface consists of XUL, an XML-based user interface language.

Regarding general documentation, you should find everything you need on developer.mozilla.org. Especially interesting are the pages about Extensions, JavaScript (specifically, the re-introduction to JavaScript) and XUL (specifically, the XUL Tutorial).

If you have calendar-specific questions, you can request help on IRC in #calendar, or in the mozilla.dev.apps.calendar newsgroup. If you have more general Javascript or XUL questions, you can request help on IRC in #developers. Both IRC channels are on irc.mozilla.org

Creating a Patch

General documentation here.

After you have changed everything you wanted to, you should take a look at the Style Guide, to make sure your code follow the calendar style guidelines we use.

Next, you need to create the patch. The following command can be used to create a patch of all changed files. Additional commands are needed if you added new files.

# Enter the source directory
cd src

# Create the patch
hg diff >c:\my_first_bug.diff

If you want to add new files, you will need to add those with the hg add command. After doing this, you can create the patch as described above.

Now take a final look at the patch if it contains everything you wanted it to contain. You are ready to upload the patch to the bug. If there is no bug for your patch yet, you can create one.

You will need to request review from someone specific to make sure your patch is looked at. Take a look at the Module Ownership page to find a reviewer. In general you can pick the first reviewer of the module you changed, but to be nice, you should take a look at each reviewer's Request Queue to find out who doesn't have too much to do. Note that some reviewers are not active, the module ownership page has the details though.

If you changed UI, its always a good idea to add a screenshot and request ui-review from a ui-reviewer. See also the module ownership page.

The review process usually starts off with a ui-review. It is possible, that the code reviewer will postpone the review until you have ui-review+, in case it is clear that the UI will stay as proposed. In the code review, the reviewer checks if the style fits the Style Guide, and does a general check if the patch works as advertised. To ease review, you should make sure there are no (new) error console warnings or errors, and all tests pass (cd @TOPSRCDIR@/../objdir-tb/calendar; make -C test check).

As soon as you have r+ from all reviewers (r+ means having a positive review, also known as r=shortname), you should fix everything that was requested, and upload a new patch. Unless you have Mercurial (hg) access yourself, the reviewer will generally take care of checking in the patch. If that's not the case, or he forgets to do so, you can add the checkin-needed keyword to the bug.

After the patch is checked in and all aspects of the bug are taken care of, the reviewer will resolve the bug as FIXED. The patch will then be available in the next spun nightly. When it is available, it is always a good practice to test the functionality using the original steps to reproduce. If everything works as proposed, you can set the bug as VERIFIED. If any regressions show up, you should file a new bug and set the regression keyword on it.

Applying a patch

OUTDATED - WE NEED THE APPROPRIATE HG COMMANDS HERE

From time to time, you might need to apply a patch from someone else, or maybe your own patch. This is quite easy, but note that if you plan on applying the patch, making some changes and then want to create a patch that doesn't contain the patch you originally applied, it might be quite a bit harder. This isn't very often the case though.

To apply a patch you need to find out what the path prefix is and match up the -p option. Assuming you or the other person used the process above to create the patch, you can use the following commands to apply the patch

cd $MOZILLA/calendar
# --dry-run tests the patching process to ensure that the patch will go
# ahead cleanly. Be sure to run --dry-run at least once before running
# the actual patching process.
patch -p0 -i ~/my_first_bug.diff --dry-run
# Now check if the patch applies cleanly, or you are willing to fix the 
# places it went wrong. When you are confident, you can call:
patch -p0 -i ~/my_first_bug.diff

# If the file to patch was not found, take a look at the patch headers. For
# example, if the header contains "+++ themes/winstripe/calendar-views.css",
# then you need to go into the base directory and call again. If the header
# contains "+++ mozilla/calendar/base/Makefile.in", you can use -p2 instead to
# strip the "mozilla/calendar" part.
patch -p2 -i ~/my_first_bug.diff

If some changes went wrong, patch will create rejects files. To resolve changes, you should open the original file and the rejects file. On large rejects files, you might want to open the rejects file twice so you can see the lines that need to be removed and the lines that need to be added at the same time.

If you want to get rid of all changes at once, you can issue the following command. Warning: This will get rid of all changes to the calendar tree you have made.

# Enter the source directory
cd src

# Overwrite all local changes
hg update -C

Creating Extensions with the Build System

If you have gotten this far and want to create an extension for Sunbird or Lightning instead of adding core functionality, it is also easily done. The advantage of this method, is that you don't have to take care of different chrome.manifests for development and deploying and also don't have to take care of zipping together the .xpi file yourself or via a script.

Specifics exceed the scope of this document, but Calendar:Creating_an_Extension covers this quite well.

Using directories rather than JARs

Sometimes it is simpler to develop chrome in a directory. If you choose a JARed structure for releasing, you can still develop with a directory structure by editing your chrome.manifest. For example, calendar.jar in the Lightning extension, rather than having

content calendar jar:chrome/calendar.jar!/content/calendar/

use

content calendar chrome/content/calendar

Troubleshooting

If you are having trouble, feel free to ask in #calendar on irc.mozilla.org. If you find no help there, try #developers. Do read the Mozilla documentation before asking.

Common Build Errors

Hidden symbols Original Documentation here

/usr/bin/ld: something.so: hidden symbol `nsSomeClass::SomeFunc(someArg*)' isn't defined
/usr/bin/ld: final link failed: Nonrepresentable section on output

This can easily be worked around by adding the following line to your mozconfig

ac_cv_visibility_pragma=no