Calendar:Hacking
|
THIS PAGE MAY BE OUTDATED |
| This article is in parts, or in its entirety, outdated. Hence, the information presented on this page may be incorrect, and should be treated with due caution until this flag has been lifted. Help by editing the article, or discuss its contents on the talk page. |
Contents
Beginner's Guide to Hacking Sunbird/Lightning
So, you think you might want to help out with the Sunbird or Lightning projects? 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 Mozilla Sunbird and/or Lightning projects.
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 Sunbird or Lightning from source. (Windows 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 jar extract/build tool.
- Most zip utilities are capable of working with .jar files as well. Some may require that you rename .jar files to .zip first
- Windows XP can handle zip files by default but misses some higher-end functions which are necessary to work effectively on Sunbird or Lightning. 7-Zip is an excellent Open Source alternative with a Linux port, FilZip is a viable freeware alternative.
- A current nightly build of either Sunbird or Lightning
- A text-editor, who is capable of working with files created on Windows, Linux or Mac OS X.
- Windows users are strongly discouraged from using the Notepad text-editor. Viable freeware alternatives are Notepad++, notepad2 and PSPad. These editors 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).
- A program capable of creating DIFF files (Most CVS programs are capable of doing this.)
- A CVS program (kinda optional, but not really)
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 windows build instructions above, you have downloaded the required tools.
Hacking!
Time to make your first changes to the code. We're going to use Sunbird as an example.
1.) If you haven't done so already, unzip your current nightly build of Sunbird and make sure it runs properly. Then close it.
2.) Open the 'chrome' folder inside the folder where you unzipped Sunbird.
3.) Find the calendar.jar file and open it with your jar tool.
Inside here you will find 3 folders: content, locale, and skin.
- content holds all of the XUL and JavaScript files that form the Sunbird front-end code. This is where the majority of hacking takes place.
- skin holds all of the icons and CSS files for Sunbird. Keeping this separate allows for Sunbird to be easily themed.
- locale holds all of the strings (words/letters) that are used throughout the program. Keeping these separate allows for easy localization of Sunbird.
- If the locale folder cannot be found within calendar.jar, it is likely located in calendar-yourlocale.jar.
XUL Hacking
Our first hack is going to be to change the name of tab that holds the minimonth (the small calendar in the upper-left of the screen). If you recall back to the days of Sunbird 0.2, this tab used to say 'Calendar'. However, since the other tab is named 'Calendars', it was confusing, and so it was changed in Bug 270907. We're going to try to change it back, just as an exercise. (DON'T CLICK THAT LINK YET. Try to work through this on your own. If you get stuck, you can look at the patch in that bug for guidance, though.)
4.) The main Sunbird window lives in the calendar.xul file inside content/calendar. Open this file in your text-editor.
5.) Scroll down until you see something that looks like:
<vbox id="left-hand-content" persist="width">
<tabbox id="tablist" persist="selectedIndex">
<tabs>
<tab label="&calendar.calendartab.label;"/>
<tab label="&calendar.listofcalendarstab.label;"/>
</tabs>
Here are our tab labels. It's a bit confusing since they don't actually say 'Date' and 'Calendar'. For more information on how localized strings work, see XULPlanet's article
6.) Change label="&calendar.calendartab.label;" to read label="Calendar" and save the file.
7.) Place your new calendar.xul back inside content/calendar (overwriting the old one) and close the jar tool.
8.) Restart Sunbird and observe the renamed tab.
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 locale? Well, 'Calendar' here is living in content which is bad. Change the line back to label="&calendar.calendartab.label;" and restart Sunbird to make sure you did it correctly.
9.) The majority of the strings for Sunbird live in calendar.dtd inside the locale/en-US folder. 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 (often only prior to a release) to the new strings. Patches involving string changes/additions/deletions should only change en-US files.
10.) Find the ENTITY named calendar.calendartab.label and change its value from 'Date' to 'Calendar'. Save the file.
11.) Put the new calendar.dtd file in your calendar.jar (overwriting the old file) and close the jar tool.
12.) Restart Sunbird 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-3 above.
4.) The main Sunbird front-end loading takes place in calendar.js in the function calendarInit(). Open that file in your text-editor.
5.) Find the calendarInit() function. (You'll need to scroll down somewhat.)
6.) Insert the following (after the '{'):
alert('Hello World!');
and save the file.
7.) Place your new calendar.js back inside content/calendar (overwriting the old one) and close the jar tool.
8.) Restart Sunbird 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. (This is currently a short list, but all bug-triagers have now been told to start adding to this list on a more regular basis, so expect it to grow.) 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 calendar.jar file and test them by restarting Sunbird. 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 calendar.jar are slightly different from the actual source files. In an ideal world, you'll check out the source code and create your patch based on that. If your changes are small however, your reviewer may be willing to accept a chrome patch for the short term. If you plan on submitting several patches, you really need to work from CVS.
1.) Check out the Mozilla source code. See the DevMo article for more details on this step.
2.) Open up the relevant files and make the same changes to them that you made to your calendar.jar files.
3.) Use your CVS program's diff utility to create a file that contains information about the files you changed. This is usually done with a command something like cvs diff -prU 8 mozilla/calendar/ > myPatch.diff
See the DevMo article for more details on this step.
4.) Go to the bug you've been working on and choose 'Create an Attachment'. Put the path to the file that CVS diff created in the proper box, and give your patch a short title describing your changes. Describe in detail the changes that you've made in the Description box. Check the 'Patch' checkbox under content type.
5.) Important: Ask for a review! In the dropdown menu next to 'review', choose the '?', since you're asking for the review. In the textbox next to the '?' place the email address of one of the calendar developers.
Adequate reviewers can be found on the Calendar:Module_Ownership page.
If your patch involves changes to the user interface (UI), set the 'ui-review' flag to '?' as well, place the email address of the UI module owner or peer in the textbox, and attach a screenshot (.gif, .jpg, or .png) of your proposed change.
6.) Wait for the review. If you haven't heard anything in 5 days, please 'poke' the review. (Ideally, talk to them on IRC. At a minimum, post a comment in the bug.) If you haven't heard anything in 10 days, please choose a different reviewer.
7a.) If your review request is granted: Your reviewer will 'check in' your patch and (in most cases) mark the bug as FIXED. You can use Bonsai to confirm this. (If he doesn't check it in, add the checkin-needed keyword to the bug, and the checkin monkeys will commit it for you, usually within the next week or two.) Congratulations! You've just fixed your first bug.
7b.) If your review request is denied: Don't lose heart! This happens more often than not. Your reviewer will tell you changes that need to be made to the patch in order for it to be acceptable for checkin. Repeat this process with those changes in mind, submit another patch, and ask for another review.
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
- IRC - Sunbird and Lightning hackers and reviewers like to hang out in the #calendar channel on irc.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.
- LXR - Great for searching the mozilla codebase for examples, particular code lines, etc.
- XULPlanet - a great reference on all things XUL.
- DevMo - The Mozilla Developer's Center. Tons of great links and articles on almost everything Mozilla-hackish imaginable.
- Sunbird/Lightning developer's guide - Another work in progress.
- DOM Inspector patched to be installable in Sunbird (separate versions for 1.8 branch [0.5] and 1.9 trunk [0.6+]); optional InspectorWidget toolbar extension for DOM Inspector.
- Venkman Javascript Debugger patched to be usable in Sunbird, Thunderbird
- Extension Developer with Javascript Shell. Patched to be installable in Sunbird, recent Thunderbird.
- File Bug Report extension adds "File Sunbird Bug Report" to Sunbird's tools menu. Opens new Calendar bug report page, filling the build-id field with Sunbird's userAgent id (not the browser's).
- Leak Monitor patched to be installable in Sunbird.
Useful settings
- You can receive [more debug messages] with some preference settings.
- You can work within directories rather than JAR files. This eliminates the need to rebuild the jar files after a debug cycle. To work within chrome/calendar.jar extract this file to chrome/calendar and change the file calendar.manifest to:
ss
# Settings for working with a directory structure # instead of calendar.jar skin calendar classic/1.0 calendar/skin/classic/calendar/ content calendar calendar/content/calendar/ content branding calendar/content/branding/ xpcnativewrappers=yes
After setting this you should delete the two files XPC.mfl and XUL.mfl or the complete profile folder in the local directory, (shell:Local AppData\Mozilla\sunbird\profiles under Windows XP). Otherwise the old code from the jar file may be executed.
