Getting Started - Developer

From Thunderforce
Revision as of 20:21, 23 January 2008 by Stevenlawrance (talk | contribs) (Don't use Oribe, and I now use openSUSE 10.3)
Jump to navigation Jump to search

To get started as a developer, you will need to install and set up various programs. It's definitely possible to use alternatives for the proposed tools, though the tools listed below are the ones that I am accustomed to in case if you have any support questions for them. Another caveat is that Novell openSUSE 10.3 is my main development platform and desktop system, so the instructions as-is might not work in Windows yet. I plan to eventually try the below in Windows and fix any issues, though please feel free to try it out and let me know if you run into any issues. Thanks!

The general process is outlined below:

  1. Install the latest Mozilla Thunderbird 2.0 version if you haven't already done so
  2. Install the Thunderforce development tools and plug-ins
  3. Download the Thunderforce source code into a new Eclipse project
  4. Download and compile the Mozilla Thunderbird source code
    • This is optional, but helps immensely with software development and debugging
    • If Thunderforce is crashing Thunderbird, then this optional task will likely be required to quickly and easily find out why the crash is happening
  5. Sign up for a Salesforce.com Apex Developer Network (ADN) account to get a developer edition organization if you haven't already done so
    • Your developer edition organization can be used to develop and test Thunderforce
    • Developer edition organizations have API access, though they are limited to 5000 API calls per 24-hour period
    • You can develop and test Thunderforce even if you don't have API access in your main Salesforce.com organization or if you don't use Salesforce.com at all
  6. Create and configure a Thunderforce testing profile in Thunderbird
  7. Create the Eclipse configurations for running and debugging Thunderforce
  8. Familiarlize yourself with Thunderforce's test framework
  9. Grab a module and develop it
    1. Create a design for your module on the wiki
    2. Implement your module in parallel with your unit tests
      • Unit tests should ideally be created for all public methods that are exposed on the XPCOM interface. Internal methods typically don't need to be tested as they are called by the public methods and, due to how XPCOM works, cannot be easily tested anyway
      • When possible, create your unit test before your code and use the test framework to verify your module's operation under those test cases

Artifacts

Useful Development Links

Development tools and plug-ins

Please install and set up the following:

  1. Eclipse IDE for C/C++ Developers
  2. Create and switch to a new Eclipse workspace for Thunderforce unless if you aren't using Eclipse for anything else
    • This can be accomplished through File -> "Switch Workspace..."
    • Optionally, you can create a shortcut to start the Thunderforce workspace directly by running eclipse or eclipse.exe with "-data" followed by your workspace folder path
      • Example: eclipse.exe -vmargs -Xmx512M -data d:\Devel\Thunderforce
  3. Eclipse Plug-Ins

Thunderforce Eclipse project

The following steps walk you through the process of importing the Thunderforce Eclipse project into your workspace:

  1. In your Thunderforce Eclipse profile, select "Import..." from the "File" menu to begin the process
  2. Within the "Other" group, select "Checkout Projects from SVN" and press the "Next >" button
  3. Create the https://www.moonlightdesign.org/thunderforce/svn repository location if it isn't already created. Press the "Next >" button
  4. When asked to select the folder to be checked out from SVN, select the "trunk" folder and press "Next >"
  5. Eclipse should automatically detect that the project is named Thunderforce. Press the "Finish" button to complete the project setup

The Thunderforce Eclipse project is presently split into three main folders:

  • architecture
    • The high-level architecture and any detailed design diagrams live in here
  • extension
  • tests
    • Integration and unit tests live in this folder, which is structured as a Thunderbird extension. Because these tests are designed to test Thunderforce, this extension requires that the Thunderforce extension is also installed in a Thunderforce profile

Mozilla Thunderbird debug-enabled build

If you are not using a Linux or Apple Mac OS X system for development, you will need to download and install CVS, GNU Make, GNU GCC, and likely other build tools. I'm using Novell openSUSE 10.3 as my desktop at both home and work. You can use Cygwin in combination with other tools, and these instructions have more information on how to get that set up. If you are running Linux, please be sure to add noatime and nodiratime to your filesystem mount options to make handling the Mozilla codebase as fast as possible. On Windows, you can accomplish the same thing with "fsutil behavior set disablelastaccess 1", though that might strangely disable some programs' abilities to detect changes to files

  1. Create a new standard make C++ project in your Thunderforce Eclipse workspace
    1. In the "File" menu, select New -> "Project..." and select "Standard Make C++ Project" in the C++ group or, if that does not exist, "C++ Project" in the C++ group
    2. Select "Cygwin GCC" or whatever is relevant for your platform with "Makefile project" selected if asked for the project type
    3. Name the project "mozilla" without the quotes (case is important in case-sensitive filesystems) and press the "Next >" button
    4. Accept the defaults and press the "Finish" button
    5. Close Eclipse until you are finished with the remaining steps
  2. Download the 2.0 branch of Thunderbird using CVS in the command line
    • Yes, you will need to use the command line and have cvs or cvs.exe in your path. Mozilla uses a Makefile to download the relevant parts of the tree for a given project
    • This process was adapted from Mozilla's CVS build instructions
    1. In a command prompt or shell, change the current directory to your Thunderforce Eclipse workspace's folder
      • That folder should have at least two folders: Thunderforce and mozilla
    2. Download the client.mk file with the following CVS command, exactly as it is written:
      • cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co -r THUNDERBIRD_2_0_0_9_RELEASE mozilla/client.mk
    3. Change the current directory to mozilla
      • cd mozilla
    4. Download Mozilla Thunderbird's source code with CVS by running the following command:
      • make -f client.mk checkout MOZ_CO_PROJECT=mail
  3. Configure Thunderbird to build with debugging options enabled
    1. Create a new text file in the root "mozilla" folder named .mozconfig (include the dot prefix)
      • In this file, add the following items as lines of text:
        . mail/config/mozconfig
        ac_add_options --enable-debug
        ac_add_options --disable-optimize

        # Add the following line if you are compiling on x86_64
        ac_cv_visibility_pragma=no
    2. Run the Autoconf configure script
      • Linux or Cygwin: ./configure
      • Windows: Please feel free to contribute this information here
  4. Build Mozilla Thunderbird with the following command in the root "mozilla" directory:
    • make
  5. Launch Eclipse and see the "mozilla" project populated with Thunderbird's source code
    • You can now easily open files with Ctrl+Shift+R, see where a definition for an identifier in a C++ file exists, find references, and other operations that you can do in Eclipse with C and C++ files

Thunderforce testing profile in Thunderbird

To separate your production email from Thunderforce testing, we suggest that you create a separate Thunderbird profile for Thunderforce testing. You can also use your main Thunderbird profile, but you then run the risk of damaging your email during Thunderforce development.

  1. Ensure that Thunderbird is not running by closing all Thunderbird windows
  2. Start the Thunderbird profile manager in the command line: thunderbird -no-remote -ProfileManager
  3. Create a new profile named ThunderforceTest and press the Exit button to close the profile manager
    • The Eclipse instructions refer to the ThunderforceTest name
  4. Optionally create a shortcut to launch the ThunderforceTest profile, which will work even when you have your default Thunderbird profile running
    • The Thunderbird command to run in this shortcut: thunderbird -no-remote -P ThunderforceTest
  5. In your ThunderforceTest profile's extensions subfolder, create the two following text files. The file names that you will need to use are in bold:
    • thunderforce@moonlightdesign.org
    • thunderforcetest@moonlightdesign.org
      • This file will contain the full absolute file path to the Thunderforce tests folder, such as d:\Devel\Thunderforce\Thunderforce\tests
    • Both of these files will contain one and only one line of text
  6. Download the following essential development extensions for Thunderbird into a temporary folder, such as your desktop
  7. Launch your new ThunderforceTest profile from the command line or from your shortcut
    • If launching from the command line, run: thunderbird -no-remote -P ThunderforceTest
    1. When no accounts exist, Thunderbird automatically displays the account setup wizard. You should see a "Salesforce.com account" option as the second option if everything has been set up properly
      ThunderbirdAccountWizard.png
      • Close the account wizard by clicking on the "Cancel" button and then click on the "Exit" button. Thunderbird will remain open
      • If you do not see the "Salesforce.com account" option, then you might need to force Thunderbird to re-register the components. In your ThunderforceTest profile, delete the compreg.dat file and try again
    2. Install the three extensions that you had downloaded
      • Extensions can be installed by selecting "Add-ons" in the "Tools" menu and then clicking on the "Install..." button in the "Extensions" tab

Eclipse configurations for running and debugging Thunderforce

The following instructions guide you through the process of creating Eclipse configurations for running an debugging Thunderforce.

  • Before trying out new code in Thunderforce, it is advised that you run the basic unit tests to ensure that you don't get silly JavaScript compilation errors and that your new code passes basic positive and negative test cases.

You should repeat this process for each unit test and runtime configuration. The following run and debug configurations are advised:

  • Thunderforce: Run Thunderbird with the ThunderforceTest profile. This is meant for manual integration and functionality testing
  • Thunderforce Basic Tests: Run the simple unit and sanity test cases to ensure that your code change compiles properly and didn't break anything obvious. This is typically run before trying out a new change with the full Thunderforce run configuration
  • Thunderforce Normal Tests: Run the normal unit and integration test cases. When tests of this type are written, running this will likely become a check-in requirement
  • Thunderforce Extra Tests: Run the integration tests that typically take a long time to run. These tests are important, but do not need to be run with every single change
  • Thunderforce All Tests: Run all of the aforementioned tests. CruiseControl might be used to automatically run this in a cycle whenever new code exists

To create a Thunderforce run configuration, perform the following steps:

  1. Select "Run..." from the "Run" menu in Eclipse
  2. Right-click on "C/C++ Local Application" and select "New" from the pop-up menu
  3. Give this run configuration a meaningful name, such as a name mentioned above (Thunderforce, Thunderforce Basic Tests, etc)
  4. Select "mozilla" as the project for this run configuration
  5. Select "dist/bin/thunderbird-bin" or "dist/bin/thunderbird.exe" in the "C/C++ Application" field, depending on which operating system you are running. The "Search Project..." button can be used to located thunderbird-bin or thunderbird.exe
  6. Use one of the following as the program arguments in the "Arguments" tab, depending on what type of run configuration this is:
    • Thunderforce: -no-remote -P ThunderforceTest
    • Thunderforce Basic Tests: -no-remote -P ThunderforceTest -thunderforceTest basic
    • Thunderforce Normal Tests: -no-remote -P ThunderforceTest -thunderforceTest normal
    • Thunderforce Extra Tests: -no-remote -P ThunderforceTest -thunderforceTest extra
    • Thunderforce All Tests: -no-remote -P ThunderforceTest -thunderforceTest all
    • Optionally, you can add, without the quotes, "-jsconsole", "-venkman", or both to also show the JavaScript Console and/or the Venkman JavaScript Debugger, which are both especially helpful when tracking down test failures. As an example, if you want to run the basic tests along with the JavaScript Console and the Venkman JavaScript Debugger, the arguments can be the following: -no-remote -P ThunderforceTest -thunderforceTest basic -jsconsole -venkman
  7. Use "${workspace_loc:mozilla}/dist/bin" without the quotes as the working directory
  8. Add the following environment variables if using Linux. If you are using Windows, skip this step
    VariableValue
    LD_LIBRARY_PATH ${workspace_loc:mozilla}/dist/bin:${workspace_loc:mozilla}/dist/bin/plugins
    LIBRARY_PATH ${workspace_loc:mozilla}/dist/bin:${workspace_loc:mozilla}/dist/bin/components
    moz_debug 1
    moz_debugger gdb
    MOZ_PROGRAM ${workspace_loc:mozilla}/dist/bin/thunderbird-bin
    MOZILLA_FIVE_HOME ${workspace_loc:mozilla}/dist/bin
  9. Leave the environment variable "Append environment to native environment" choice selected
  10. Unselect "Stop on startup at" in the "Debugger" tab unless if you want to have the debugger stop at the main() function whenever the debugger is started
  11. Press the "Apply" button to save this run configuration
  12. To make the subsequent run configurations easier to set up, it's possible to right-click on this configuration in the tree on the left side of the window and select "Duplicate" from the pop-up menu, which is especially helpful for Linux users due to the environment variables

Because debugging makes Thunderbird very slow, it's typically desirable to run Thunderbird in non-debug mode and, when a crash occurs, connect to it with the GNU Debugger and debug from there. I'm not sure if this works in Windows, but it works well on my Linux system. To create this type of target, follow these instructions:

  1. Select "Debug..." from the "Run" menu in Eclipse
  2. Right-click on "C/C++ Attach to Local Application" and select "New" from the pop-up menu
  3. Name this run configuration something meaningful, such as "Thunderforce Crash Debug"
  4. Select "mozilla" as the project
  5. Select "dist/bin/thunderbird-bin" or "dist/bin/thunderbird.exe" in the "C/C++ Application" field, depending on which operating system you are running. The "Search Project..." button can be used to located thunderbird-bin or thunderbird.exe
  6. Press the "Apply" button to save this run configuration
Retrieved from "https://www.moonlightdesign.org/thunderforce/wiki/index.php?title=Getting_Started_-_Developer&oldid=513"