Thunderbird:Start Hacking

<< Back to Thunderbird Dev page

Beginner's Guide to Hacking Thunderbird

So, you think you might want to help out with Thunderbird? Great! What's that? You don't have any idea where to begin? Hopefully this document can help. It's designed to be an introduction to submitting your first patch(es) to the Thunderbird codebase.

Getting the right tools

Before you can begin, you're going to need several tools setup on your computer. Note: Some hackers have found it useful to simply begin by building Thunderbird from source. (Instructions) If you can do this, you will (almost) automatically have all the right tools to begin hacking. However, since building is a rather complicated process, you may wish to come back to it at a later stage.

You will need:

• A Bugzilla account
• A program to extract the contents of .jar files (which are named as .ja files in Thunderbird's case). E.g. 7-zip on Windows.
  • Most zip utilities are capable of working with .jar files as well. Some may require that you rename .jar files to .zip first
• A current nightly build of Thunderbird
• A text-editor, who is capable of working with files created on Windows, Linux or Mac OS X.
  • Windows users must not use Windows' Notepad text-editor which doesn't show Linux linebreaks properly. A viable freeware alternative for Windows is Notepad++. This editor will get you a better view of the code (i.e you will see which braces close which codeblocks, 'if','var' and so on will be bold, among other stuff).

Linux users will find most of these programs available by default with their distro.

Windows users won't have all of these tools installed by default, but if you have followed the build instructions above, you have downloaded the required tools.

Hacking!

Time to make your first changes to the code.

1.) If you haven't done so already, unzip your current nightly build of Thunderbird and make sure it runs properly. Then close it.

2.) Inside the folder where you unzipped Thunderbird, open the 'omni.ja' file with the zip program. Rename it to omni.zip if necessary to unzip it. Unzip the contents into a folder, let's say 'omni'.

3.) In the 'omni' folder, delete the folders 'jsloader' and 'jssubloader'. These have source files cached for faster loading and if you don't remove them, your changes to the real source files will be ignored by Thunderbird.

In the 'omni' folder, you find a variety of folders that create the front-end of the application.

• content - many of the front-end files
• components - some often used files (in different contexts).
• defaults - default values for preferences
• hyphenation - dictionaries used in compose context
• modules - often used files which once imported share their properties with all context which have been imported to (set a property to 1 in context A and context B will see that value)
• res - resources like graphics, e.g. for the HTML compose editor

The 'content' folder has the following subfolders:

• chat - contains files for the instant messaging and social media component of Thunderbird
• classic - contains many of the css (style) and image files for the default theme
• comm - contains some of the core "communicator" files (you usually won't worry about these.)
• devtools - contains the developer tools, e.g. the code for the error console
• en-US - these contain the strings used in the application, translated to English. When using another locale, you may see a different folder name.
• gloda - the files for the global search database. Used to search across folders
• messenger - this is where most of the XUL and JS files for Thunderbird are.
• newsblog - contains files specific to blog-reading (RSS)
• pippki - certificate management related files
• toolkit - the common files shared by all Mozilla toolkit applications (Firefox, Thunderbird). These define common widgets and other useful tools.

4.) Open the folder 'messenger'.

Inside here you will find a content folder, with 4 sub-folders

• branding - Thunderbird specific branding materials
• messagebody - contains a file used for printing the address book
• messenger - most front-end files for Thunderbird
• messenger-smime - files related to smime processing

XUL Hacking

Our first hack is going to be to add a bit of personalization to Thunderbird. We're going to display a label above the list of folders that reads 'My Folder List.'

1.) The main Thunderbird window lives in the mailWindowOverlay.xul file inside content/messenger. Open this file in your text-editor.

2.) Search for 'savedFiles.label'

           <menuitem id="appmenu_openSavedFilesWnd"
                     label="&savedFiles.label;"
                     key="key_savedFiles"
                     oncommand="openSavedFilesWnd();"/>

A menuitem is an element in a menu. label sets its text. For more information on various XUL elements, see MDN XUL Reference.

3.) Change label="&savedFiles.label;" to read value="My Saved Files". (The original label has an "&" and a ";" because it is an entity. More on this below.)

Now these lines should look like this this:

           <menuitem id="appmenu_openSavedFilesWnd"
                     label="My Saved Files"
                     key="key_savedFiles"
                     oncommand="openSavedFilesWnd();"/>

Save the mailWindowOverlay.xul file.

4.) Zip the content in the 'omni' folder (not the omni folder itself) and rename the zip file to 'omni.ja' and use it to replace the old omni.ja you unzipped earlier

5.) Start Thunderbird and notice your new label in the 'Tools' menu!

Yay! Great work. You just made your first changes to the code. There's only one problem... remember how we said earlier that all strings live in the en-US folder? Well, 'My Saved Files' here is living in the messenger folder which is bad. Change the line back to label="&savedFiles.label;", zip, rename and replace and restart Thunderbird to make sure you did it correctly. Your label will now read "Saved Files".

6.) In the folder en-US open the folder locale/en-US/messenger.

7.) Many of the strings for Thunderbird live in messenger.dtd here. Open it in your text editor. Note: Changes to strings are always made first to the en-US file. Other localizers will then update their files to the new strings. Patches involving string changes/additions/deletions should only change en-US files.

8.) Find the ENTITY named savedFiles.label and change its value from 'Saved Files' to 'My Saved Files'. Save the file.

9.) Zip, rename and replace the 'omni' folder/ 'omni.ja'.

10.) Restart Thunderbird and observe the changes.

Congratulations, this is the proper way to change that string.

JS Hacking

No hacking introduction would be complete without a 'Hello World' example of some sort. So, here's ours. Start with steps 1 and 2 above.

3.) Open the file 'mailCore.js' from the 'messenger' folder..

4.) Find the openSavedFilesWnd() function. (You'll need to scroll down somewhat.)

5.) Insert the following (after the '{'):

alert('Hello World!');

and save the file.

6.) Zip, rename and replace the 'omni' folder/ 'omni.ja'.

7.) Restart Thunderbird, open the 'Tools' menu, click on 'My Saved Files' and observe the 'Hello World!' greeting.

Finding a bug to fix

So, by now you're (hopefully) eager to actually fix some real bugs! You may have come here because you already had a bug you wanted to fix. If so, great! The best bugs to fix are usually the ones that annoy you personally. If not, look at the list of good first bugs or other common bug queries. Pick one that sounds interesting to you.

If you have the proper Bugzilla permissions, please assign the bug to yourself. If not, please post a comment in the bug saying that you are working on it. If you stop working on the bug, please say so as well!

Submit a comment with the basic outline of how you plan to fix the bug. (Or if you have IRC access, talk about the proposal there.) There is nothing more frustrating than working hard on a patch, only to be told that the reviewer wanted the patch solved in a different way. Make sure that your proposed changes (ESPECIALLY changes to the User Interface) are acceptable before investing your valuable time.

Now, for the hard-work part: Fix the bug. Continue to make changes to your messenger.jar file and test them by restarting Thunderbird. Repeat until the bug is solved.

Creating and submitting a patch

Wow! You've fixed the bug you were working on? Fantastic! Time to submit a patch so that everyone can enjoy the fruits of your labor. The first thing to recognize is that the files inside omni.ja are slightly different from the actual source files. Read how to land a patch.

Tips for making good patches

• Comments inside the code are encouraged! Remember, someone else is going to have to go back and read your code later without any clue of what you were thinking when you were doing it. Make sure that this can be done with as little pain as possible
• Don't just fix things, fix them correctly. If you find yourself adding lots of special cases for what seems like a simple task, the patch probably won't be approved without a very good reason. Mozilla code is complicated enough as it is; don't make it more so.
• Be careful about random whitespace changes. Don't add newlines to irrelevant areas, and make sure you remove extra newlines you added while experimenting.
• While alert() (and it's cousin dump()) are useful for debugging, they should not remain in code that will be checked in. Remove any alert()s you may have used for testing.
• Use spaces, NOT tabs.
• Follow the existing style of the document you're working on. If default indenting is 4 spaces, use 4 spaces. If it's 2, use 2. If braces are placed on the same line as for and if (ie if (a == b) {) keep it this way. If they're on the next line, keep it that way.
• Don't be afraid to ask for help!

Useful tools

• Matrix - Thunderbird hackers and reviewers like to hang out in the #maildev Matrix channel on chat.mozilla.org. They're usually more than happy to answer your questions if you get stuck on a part of a patch. Be patient when asking questions, though. Hackers have to sleep, eat, and work too, so it may take several hours before someone sees your question and responds.
• DXR - Great for searching Thunderbird's codebase for examples, particular code lines, etc.
• MDN - The Mozilla Developer Network. Tons of great links and articles on almost everything Mozilla-hackish imaginable.
• Thunderbird developer website - Has most everything that you need to get started.
• Getting involved - More links to communities and resources.

Useful settings

• You can receive more debug messages with some preference settings.

Other possibly useful links

• Hacking Firefox Guide