251
edits
Calendar:Hacking: Difference between revisions
no edit summary
m (→Creating and submitting a patch: added some DevMo links) |
No edit summary |
||
| (27 intermediate revisions by 13 users not shown) | |||
| Line 1: | Line 1: | ||
<small>[[Calendar:Home Page|<< Back to Calendar Home Page]]</small> | |||
{{Outdated}} | |||
== Beginner's Guide to Hacking Sunbird/Lightning == | == 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. | 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. | ||
| Line 10: | Line 13: | ||
* A jar extract/build tool. | * 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 | ** Most zip utilities are capable of working with .jar files as well. Some may require that you rename .jar files to .zip first | ||
* A [http://ftp.mozilla.org/pub/mozilla.org/calendar/sunbird/nightly/latest-trunk/ | ** Windows XP can handle zip files by default but misses some higher-end functions which are necessary to work effectively on Sunbird or Lightning. [http://www.7-zip.org/ 7-Zip] is an excellent Open Source alternative with a Linux port, [http://www.filzip.com/ FilZip] is a viable freeware alternative. | ||
** Note that | * A current nightly build of either [http://ftp.mozilla.org/pub/mozilla.org/calendar/sunbird/nightly/latest-trunk/ Sunbird] or [http://ftp.mozilla.org/pub/mozilla.org/calendar/lightning/nightly/latest-trunk/ Lightning] | ||
* A text-editor | ** There is also a nightly build based on the latest stable mozilla core for [http://ftp.mozilla.org/pub/mozilla.org/calendar/sunbird/nightly/latest-mozilla1.8/ Sunbird] or [http://ftp.mozilla.org/pub/mozilla.org/calendar/lightning/nightly/latest-mozilla1.8/ Lightning] | ||
** Windows users | ** Note that these are not the same as a ''pre release'' build of this programs. | ||
* 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 [http://notepad-plus.sourceforge.net/ Notepad++], [http://www.flos-freeware.ch/notepad2.html notepad2] and [http://www.pspad.com/ 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 program capable of creating DIFF files (Most CVS programs are capable of doing this.) | ||
** Windows users who do not want to install the recommended CVS program might use [http://gnuwin32.sourceforge.net/packages/diffutils.htm diffutils] from the GnuWin32 project. | |||
** Another option for Windows users who want a little Linux is [http://www.cygwin.com/ Cygwin], which not only gives you diff but also CVS, you can then use your favourite Windows editor. | |||
* A CVS program (kinda optional, but not really) | * A CVS program (kinda optional, but not really) | ||
'''Linux users''' will find most of these programs available by default with their distro. | '''Linux users''' will find most of these programs available by default with their distro. | ||
'''Windows users''' won't have these tools installed by default, but if you have followed the windows build instructions above, you have downloaded the required tools | '''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! === | === Hacking! === | ||
| Line 32: | Line 39: | ||
Inside here you will find 3 folders: <tt>content, locale,</tt> and <tt>skin</tt>. | Inside here you will find 3 folders: <tt>content, locale,</tt> and <tt>skin</tt>. | ||
* <tt>content</tt> holds all of the XUL and JavaScript files that form the Sunbird front-end code. This is where the majority of hacking takes place. | * <tt>content</tt> holds all of the XUL and JavaScript files that form the Sunbird front-end code. This is where the majority of hacking takes place. | ||
* <tt>skin</tt> holds all of the icons and CSS files for Sunbird. Keeping this separate allows for Sunbird to be easily themed. | * <tt>skin</tt> holds all of the icons and CSS files for Sunbird. Keeping this separate allows for Sunbird to be easily themed. | ||
* <tt>locale</tt> holds all of the strings (words/letters) that are used throughout the program. Keeping these separate allows for easy localization of Sunbird. | |||
** If the <tt>locale</tt> folder cannot be found within calendar.jar, it is likely located in calendar-yourlocale.jar. | |||
==== XUL Hacking ==== | ==== 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.) | 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 [http://bugzilla.mozilla.org/show_bug.cgi?id=270907 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 <tt>content/calendar</tt>. Open this file in your text-editor. | 4.) The main Sunbird window lives in the calendar.xul file inside <tt>content/calendar</tt>. Open this file in your text-editor. | ||
5.) Scroll down until you see something that looks like: | 5.) Scroll down until you see something that looks like: | ||
<tt> | <tt> | ||
<vbox id="left-hand-content" persist="width"> | |||
<tabbox id="tablist" persist="selectedIndex"> | <tabbox id="tablist" persist="selectedIndex"> | ||
<tabs> | <tabs> | ||
| Line 58: | Line 67: | ||
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 <tt>locale</tt>? Well, 'Calendar' here is living in <tt>content</tt> which is bad. Change the line back to <tt>label="&calendar.calendartab.label;"</tt> and restart Sunbird to make sure you did it correctly. | 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 <tt>locale</tt>? Well, 'Calendar' here is living in <tt>content</tt> which is bad. Change the line back to <tt>label="&calendar.calendartab.label;"</tt> and restart Sunbird to make sure you did it correctly. | ||
9.) The majority of the strings for Sunbird live in <tt>calendar.dtd</tt> | 9.) The majority of the strings for Sunbird live in <tt>calendar.dtd</tt> inside the <tt>locale/en-US</tt> 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 <tt>calendar.calendartab.label</tt> and | 10.) Find the ENTITY named <tt>calendar.calendartab.label</tt> and change its value from 'Date' to 'Calendar'. Save the file. | ||
11.) Put the new <tt>calendar.dtd</tt> file in your calendar.jar (overwriting the old file) and close the jar tool. | 11.) Put the new <tt>calendar.dtd</tt> file in your calendar.jar (overwriting the old file) and close the jar tool. | ||
| Line 67: | Line 76: | ||
Congratulations, this is the proper way to change that string. | Congratulations, this is the proper way to change that string. | ||
==== JS Hacking ==== | ==== 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. | 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 <tt>calendar.js</tt> in the function <tt>calendarInit()</tt> Open that file in your text-editor. | 4.) The main Sunbird front-end loading takes place in <tt>calendar.js</tt> in the function <tt>calendarInit()</tt>. Open that file in your text-editor. | ||
5.) Find the <tt>calendarInit()</tt> function. (You'll need to scroll down somewhat.) | 5.) Find the <tt>calendarInit()</tt> function. (You'll need to scroll down somewhat.) | ||
| Line 107: | Line 117: | ||
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. | 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 ' | 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. | 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 [http://bonsai.mozilla.org/cvsquery.cgi?treeid=default&module=CalendarClient&branch=&branchtype=match&dir=%2Fmozilla%2Fcalendar&file=&filetype=match&who=&whotype=match&sortby=Date&hours=2&date=week&mindate=&maxdate=&cvsroot=%2Fcvsroot Bonsai] to confirm this. Congratulations! You've just fixed your first bug. | 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 [http://bonsai.mozilla.org/cvsquery.cgi?treeid=default&module=CalendarClient&branch=&branchtype=match&dir=%2Fmozilla%2Fcalendar&file=&filetype=match&who=&whotype=match&sortby=Date&hours=2&date=week&mindate=&maxdate=&cvsroot=%2Fcvsroot Bonsai] to confirm this. (If he doesn't check it in, add the <code>checkin-needed</code> 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. | 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. | ||
| Line 121: | Line 131: | ||
==== Tips for making good patches ==== | ==== 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 | * 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 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. | * 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. | * 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. | ||
| Line 128: | Line 138: | ||
* Don't be afraid to ask for help! | * Don't be afraid to ask for help! | ||
=== Useful | === Useful tools === | ||
* [irc://irc.mozilla.org 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. | * [irc://irc.mozilla.org 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. | ||
* [http://lxr.mozilla.org/mozilla/ LXR] - Great for searching the mozilla codebase for examples, particular code lines, etc. | * [http://lxr.mozilla.org/mozilla/ LXR] - Great for searching the mozilla codebase for examples, particular code lines, etc. | ||
| Line 134: | Line 144: | ||
* [http://developer.mozilla.org/ DevMo] - The Mozilla Developer's Center. Tons of great links and articles on almost everything Mozilla-hackish imaginable. | * [http://developer.mozilla.org/ DevMo] - The Mozilla Developer's Center. Tons of great links and articles on almost everything Mozilla-hackish imaginable. | ||
* [[Calendar:Dev_Guide|Sunbird/Lightning developer's guide]] - Another work in progress. | * [[Calendar:Dev_Guide|Sunbird/Lightning developer's guide]] - Another work in progress. | ||
* [http://www.geocities.com/gekacheka/venkman/index.html Venkman Javascript Debugger] patched to be usable in Sunbird, Thunderbird | * [http://www.geocities.com/gekacheka/moz/tool/dom-inspector/index.html DOM Inspector] patched to be installable in Sunbird (separate versions for 1.8 branch [0.5] and 1.9 trunk [0.6+]); optional [http://www.geocities.com/gekacheka/moz/tool/dom-inspector/inspector-widget/index.html InspectorWidget] toolbar extension for DOM Inspector. | ||
* [http://www.geocities.com/gekacheka/moz/tool/venkman/index.html Venkman Javascript Debugger] patched to be usable in Sunbird, Thunderbird | |||
* [http://www.geocities.com/gekacheka/moz/tool/extensiondev/index.html Extension Developer] with Javascript Shell. Patched to be installable in Sunbird, recent Thunderbird. | |||
* [http://www.geocities.com/gekacheka/moz/tool/FileBugReport/index.html 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). | |||
* [http://www.geocities.com/gekacheka/moz/tool/leakmon/index.html Leak Monitor] patched to be installable in Sunbird. | |||
=== Useful settings === | |||
* You can receive [[http://developer.mozilla.org/en/docs/Setting_up_extension_development_environment 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 <tt>chrome/calendar.jar</tt> extract this file to <tt>chrome/calendar</tt> and change the file <tt>calendar.manifest</tt> to:<code>ss</code> | |||
# 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 <tt>XPC.mfl</tt> and <tt>XUL.mfl</tt> 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. | |||
=== Other possibly useful links === | === Other possibly useful links === | ||
*[http://developer.mozilla.org/en/docs/Sunbird_Theme_Tutorial Sunbird theme creation tutorial] | *[http://developer.mozilla.org/en/docs/Sunbird_Theme_Tutorial Sunbird theme creation tutorial] | ||
*[http://developer.mozilla.org/en/docs/Hacking_Firefox Hacking Firefox Guide] | *[http://developer.mozilla.org/en/docs/Hacking_Firefox Hacking Firefox Guide] | ||
[[category:calendar|Hacking]] | |||