Thunderbird:Backend Hacking Guide For Newbies

Back to ...

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

Back-end Programming for Thunderbird (draft)

So, you love C/C++ and want to contribute to Thunderbird, but you are new to Mozilla development in general, and don't know what frameworks, technologies, tools involved in it. You are at the right place, this page is prepared for you.

First, a little bit background. Thunderbird is a cross-platform mail application developed on top of Mozilla framework. It's an open-source application used by millions, and evolving around its contributors. Mozilla framework is the central toolkit, and C/C++ is the core language for back-end programming. Tier 1 platforms for Thunderbird are Windows, Linux and Mac OS X (both PPC and Intel). So, when you develop code for Thunderbird, you have the obligation to make sure that your code works on all of these platforms, unless it's a platform specific patch.

Mozilla development process is large scale and highly distributed. Tools play an essential role to coordinate this collective effort. Every hacker MUST get familiar with these tools to involve.

Tool Arsenal for Mozilla Development

Build Prerequisites

• Compiler editor settings

• Windows
• Linux
• Mac OS X
• Others

If you wish to build the palm sync extension, you will need to install the Palm CDK (requires free registration).

Debuggers

• MSVC (Windows)
• gdb (Linux, Mac OS X)
• ??

Bug Filing/Tracking/Fixing

Note: Bugzilla is where people who don't even build / debug can contribute, so this should be at the top of the list. nth10sd 11:13, 17 April 2008 (PDT)

In Mozilla development process 'bug' is a broader term than its conventional meaning which is software defect. A bug means anything related to the product and the development process including feature requests, performance improvements and even process improvements. You can file a bug about almost anything that you think that would contribute to the success of the project.

• Bug Writing Guidelines
• Bugzilla Page

A good way to start understanding the Mozilla development process is to join others during a bugday and get familiar with bug triaging. You can find more on bugdays and bug triaging at the following links:

• Thunderbird Bug Triage
• Thunderbird Bugday

Note to author: Add a starting to bug fixing section. Mention best practices, keywords, how to search etc.. Look IRC transcripts dated Apr 30th. Things to talk about; what are keywords how to use them, what are products and components, etc...

Source Control Management

• CVS <link>
• Bonsai <link>

Patching

• Patch

Collaboration

• Pastebin <link>

Build Automation

• Thunderbird Tinderbox
• Tinderstatus for watching Tinderbox status from SeaMonkey or Firefox.
• Performance:Tinderbox_Tests
• MailNews:Performance_Testing
• How to set up a tinderbox (e.g. for standalone/test use)

Community

• IRC
  • Chatzilla
• Newsgroups
• ....

Development Process

Review, Super review <link>

• Licensing
• Toolkit Review Policy
• Gecko Code Reviews

Getting the Source

- <link>

Setting up the Development Environment

• Windows

Note for Windows programmers: If you develop code mostly on Windows and   looking for the same Visual Studio comfort ....

• Mac
• Linux

Building the Code

Folder hierarchy and meaning (public, src, main folders -- mailnews, mail, xpcom, etc..)

<link>

Mozilla Framework Libraries used by Thunderbird

PL

What is PL? How it is different than platform's C runtime, Secure C functions, etc...

NSPR

NSPR is a cross-platform library to provide Mozilla application with OS-agnostic facilities such as threading, I/O operations, networking, logging and more. It is crucial for a Mozilla C/C++ hacker to be familiar with this library in order to work with Thunderbird backend.

Although NSPR documentation is not up-to-date, still it is a very good starting point before you go and check the source code. You can find NSPR documentation at the following links.

• The Netscape Portable Runtime Page
• The Netscape Portable Runtime Reference

PSM / NSS

Personal Security Manager (PSM) consists of a set of libraries that perform cryptographic operations on behalf of a client application. These operations include setting up an SSL connection, object signing and signature verification, certificate management (including issuance and revocation), and other common PKI functions.

• PSM Home Page

NSS provides a complete open-source implementation of the crypto libraries used by AOL, Red Hat, Sun, and other companies in a variety of products.

• NSS Home Page

libMime

short introduction

XPCOM

XPCOM is Mozilla's simplified cross-platform component object model. IDL firebot: uuid, <link>

• Using nsCOMPtr
• Reference Management
  • Ownership Guide
  • Weak References
• Creating XPCOM Components
• XPCOM string guide
• XPCOM Reference

NECKO

The mozilla networking library, Necko, is an extensible, scriptable API for client-side networking tasks built on XPCOM and NSPR. It provides:

• generic and extensible framework for fetching URLs
• async framework for pumping data to consumers (i.e., non-blocking i/o)
• generic cache service (LRU data store for mozilla)
• async DNS resolution
• implementations of common protocols (http, ftp, file, imap, etc.)

More info at:

• Necko Home Page
• Source Code
• FAQ
• Necko Interfaces
• Embedding Network Library
• Creating a New Protocol Handler
• Newsgroup - news://news.mozilla.org/netscape.public.mozilla.netlib
• IRC - irc://irc.mozilla.org/#mozilla

GECKO

What is Gecko

XUL

What is XUL 

• XUL Planet
• Online XUL editor from Ted Mielczarek

Best Practices

Memory allocation

<link>

nsCOMPtr<>

<link>

Assertions

....

Logging/Tracing Thunderbird

Thunderbird logging mechanism is activated by setting couple environment variables before running Thunderbird. Two environment variables that should set are;

1) NSPR_LOG_MODULES: Module name and level separated by colon
2) NSPR_LOG_FILE: Path to the log file

• Module activity logging

General rule is to set NSPR_LOG_MODULES to the literal defined in the implementation file of the module in question. For example to log timer events, the value should be set to "nsTimerImpl:5" as defined in the header file of the timer module.

• Protocol logging

Detailed information about protocol logging can be found at Mail Logging/Troubleshotting and [Mailnews:LDAP Address Books|LDAP Protocol Logging].

• Misc
  • Performance:Leak_Tools
  • Debugging Memory Leaks
  • QA:Home_Page:Firefox_3.0_TestPlan:Leaks:LeakTesting-How-To

Understanding threading, Proxy etc.. !!!

... + <link>

Unit Testing (TUnit, cppUnit etc..)

• MailNews:Performance_Testing
• MailNews:Automated_Testing
• Mozilla Automated Testing

....

Development tools

 o Locklint
 o Firebug
 o

Common Idioms, and Patterns

.... Event sinks, bounded buffers, monitors etc.. .... PR_SUCESS, PR_FAIL ....

Advanced Topics

... Instrumentation, optimization, performance etc...

Sample Projects

• Sample project to learn how to patch and how to submit a patch
• Using NSPR in your applications

 MSVC project
 XCODE project
 SlickeEdit project??
 Eclipse??

• XPCOM: Developing an XP component and running it in a standalone application

 MSVC project
 XCODE project
 SlickeEdit project??
 Eclipse??

• ...

Major Thunderbird Entities

Currently, Thunderbird supports four different incoming (IMAP, POP3, NNTP, RSS) and one outgoing messaging protocols (SMTP). Each incoming protocol provides its own implementation (i.e. imap protocol).

Each message source (url+logininfo+protocol) is represented by an Account entity, and all accounts are managed by AccountManager. Each account has an associated IncomingServer that is implemented by the corresponding account protocol.

Identity contains all the personal outgoing mail information for a given person. Although all account types can have multiple associated identities by design, RSS do not need this entity, as does any other account that does not interact with compose code.

AddressBook is the central repository of the user's contacts. Physical store of this entity is abook.mab file in the profile directory, and it is in Mork format. See Address Book Planning page for recent improvements.

Thunderbird uses a folder-based hierarchical representation to organize messages. Folder is the logical entity that contains message contents belong to the same hierarchical level. Message content consists of message headers and message body including attachments. These two entities are stored in different physical stores to improve the system performance. Every Account has a root folder, which may have several subfolders (each potentially with their own subfolders, ad infinitum) which are actual folders on the hosting operating system.

Database entity represents the physical store of message. Each "Folder" (in the Thunderbird sense) which can contain messages is represented by two files (in the OS sense): the messages themselves (headers and bodies, in human-readable mbox format) are in one file ("folder" name without extension), while a second file (msf file in Mork format) indexes them for fast access to a given message.