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

General documentation here

Source code should be checked out via CVS. To do so you should first create your mozconfig. This is an example mozconfig for calendar which can be used:

mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@
mk_add_options MOZ_CO_PROJECT=calendar # We want to checkout calendar
mk_add_options MOZ_CO_USE_MIRROR=1 # use cvs-mirror
# mk_add_options MOZ_CO_LOCALES=de # Can be used to also checkout a language
# mk_add_options MOZ_MAKE_FLAGS="-j3" # Can be used if you have multiple processors
mk_add_options JS_READLINE=1

# ac_add_options --with-macos-sdk=/Developer/SDKs/MacOSX10.4u.sdk # Needed on MAC
ac_add_options --enable-application=calendar # We want to build calendar
ac_add_options --disable-installer # Installer not needed for development
ac_add_options --disable-airbag # I have had problems with airbag in the past
ac_add_options --disable-crashreporter # (Optional) Disable if you don't want it
ac_add_options --enable-debugger-info-modules=yes # More debug info
# ac_add_options --enable-debug # (Optional) Lots of debugging. Maybe more than you actually want!
ac_add_options --enable-extensions=default,lightning,inspector,venkman # Some extensions in the /extensions directory
ac_add_options --enable-tests # You should enable tests to make sure everything works before posting a patch
# ac_add_options --enable-system-cairo # I needed this on linux

# The following options can be used to reduce/disable debugging.
# ac_add_options --enable-optimize
# ac_add_options --disable-static --enable-shared
# ac_add_options --disable-debug

Save this file to your home directory to a file called ".mozconfig".

Now you can start checking out code. Use the following commands for the initial checkout. Do this in a folder where you want to have your tree. In general, you should use a directory that does not contain spaces or such, i.e on windows "C:\Documents and Settings\MyUsername\My Documents\mozilla" is not a good choice.

A note about versioning: While with other projects like Firefox, TRUNK is the latest and greatest, calendar code is commited to both MOZILLA_1_8_BRANCH and TRUNK. This means the only differing factor is the mozilla codebase. We are currently releasing from the more stable MOZILLA_1_8_BRANCH, so you should also develop on this branch.

To clarify, Calendar version 0.8 is MOZILLA_1_8_BRANCH, while Calendar 0.6a1 is TRUNK.

cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co -r MOZILLA_1_8_BRANCH mozilla/client.mk
cd mozilla
make -f client.mk checkout

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.

Assuming you are still in the mozilla directory you changed to above, now issue the following command:

make -f client.mk build

This will build everything needed for calendar. 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 Sunbird

You will find the binary to start Sunbird under the following paths. I assume $MOZILLA is the mozilla directory you changed to above. The obj- part may vary depending on platform, build system, and number of bits. The path on Mac also differs (i.e CalendarDebug.app) if you use --enable-debug

# Windows
$MOZILLA/obj-i686-pc-cygwin/dist/bin/sunbird.exe
# Linux/Solaris
$MOZILLA/obj-i686-pc-linux-gnu/dist/bin/sunbird
# Mac
$MOZILLA/obj-i386-apple-darwin9.2.2/dist/Calendar.app/Contents/MacOS/sunbird

Some interesting command line switches:

-g               (Mac,Linux) Start using gdb as a debugger 
-P <profile>     Start using a specific profile.
                 Leave out <profile> to start the profile manager.
-console         (Windows) Open a console for debug messages

Running Lightning

This section assumes you have a working thunderbird (2.0.0.*) installed. The best way to add Lightning to Thunderbird is to follow the general steps, but for Lightning and Thunderbird. The 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.

cd $MOZILLA/obj-*/dist/xpi-stage/lightning
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.mk to checkout all changes:

cd $MOZILLA
cvs up -A -r MOZILLA_1_8_BRANCH client.mk
make -f client.mk checkout

Fortunately, this is not needed very often, especially on MOZILLA_1_8_BRANCH. All you need to do is update the calendar directory. This is much faster than doing a full checkout.

cd $MOZILLA/calendar
cvs up

Go ahead and do the partial checkouts as long as you are able to compile calendar successfully. If you cannot the program to compile and you think it might have to do with other parts of mozilla (i.e toolkit), you can do a full update and compile.

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

Sunbird

Sunbird is usually much faster to compile, since you can selectively build parts of calendar, depending on what changed:

cd $MOZILLA/obj-*/calendar

# The following command makes a full sunbird.
make && make -C sunbird

# If you didn't change anything in the calendar/sunbird directory
make

# If you only changed things in base/content or base/themes or prototypes/wcap
make -C base chrome

# If you only changed things in base, but the above doesn't seem to be enough:
make -C base

Warning: Especially if you make chrome, be sure that you don't have sunbird running. You may override your .jar files. If this happens, go into the top-level object directory and type make. This will remake all .jar files for the whole product (i.e including toolkit)

Lightning

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

cd $MOZILLA/obj-*/calendar/lightning
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.

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. If possible, you should always do the diff inside the $MOZILLA/calendar directory, so its easy to apply the patch.

cd $MOZILLA/calendar
cvs diff -u -U8 -p > ~/my_first_bug.diff

# To add a single new file to the patch
diff -upN /dev/null base/content/path/to/file >> ~/my_first_bug.diff

# To add all new files to the patch (advanced)
for i in `cvs -n up 2>/dev/null | grep '^?' | awk '{print $2}'`; do diff -upN /dev/null $i >> ~/my_first_bug.diff; done

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 $MOZILLA/obj*/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 CVS access yourself, the reviewer will generally take care of checking in the patch. If thats 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

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. If there are cvs conflicts, you might have to remove the files marked with "C ...", and then issue the command again. Warning: This will get rid of all changes to the calendar tree you have made.

cd $MOZILLA/calendar
cvs up -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