Mobile/Fennec/Android/CommonTips

Common Tips and How-To's

Finding relevant code

Almost all of the Fennec-specific code is in the mozilla-central source tree under:

mobile/android/...

Of particular interest to most new contributors will be:

mobile/android/base/BrowserApp.java # the main Android activity that starts when you open Fennec
mobile/android/chrome/content/browser.js # the main JavaScript file that controls Gecko to make it do what we want

If you are looking for something specific, use the code-search tool at http://dxr.mozilla.org/ to search for relevant pieces of code.

Debugging

For the JavaScript parts of the code base, remote debugging with a desktop version of Firefox is the most effective way to see what is going on, add breakpoints, etc.

For Android Java code, if you have IntelliJ set up, the debugger works well and allows you to set breakpoints, inspect variables and objects, etc. See http://developer.android.com/tools/debugging/ddms.html

Debugging without an IDE is much more primitive, and you can try using Android Log statements and inspecting logcat.

logcat is a tool that is going to show you some logs prompted by the device. It might be a good help if you don't want to or can't run gdb. You can use it by running this command:

 adb logcat -v time

You can make things appear in logcat using printf_stderr. With debug builds, NS_WARNING, NS_ERROR and NS_ASSERTIONS will show up in logcat. If you're trying to debug something, you may wish to pipe the logcat output through grep to filter out irrelevant things (most Fennec-related output will be viewable by

 adb logcat -v time | grep Gecko

but remember that when attaching log output to a bug you should include unfiltered output as there may be relevant log entries under other tags.

If you want more debugging tools, Advanced Debugging is a good place to look.

Coding Style

The Java style follow the Mozilla Coding Style.

Common nits in Reviews

Check for these nits before asking for review for a patch:

• Remove trailing whitespace
• Spacing
  • Four spaces for Java indent (for main Fennec code - android-sync github project has different spacing)
  • Around operators (+, -, etc.) and :
  • Between comment "//" and text
• Braces for Java if statements, even if they are one line
• Comments should be full sentences (capitalization, punctuation)
  • Good comments are useful and clear even for someone reading a particular area of code for the first time
• Avoid using single-letter variables in almost all cases - it makes code harder to read

Lint

We provide some support for linting tools. See Mobile/Fennec/Android/Lint for a list of linting tools we support and expect to be run.

Add an Android string resource

1. Add an XML string entity to mobile/android/base/locales/en-US/android_strings.dtd with the English string you want to add.
2. Add a <string> element to mobile/android/base/strings.xml.in.
3. Build using mach build mobile/android/base or your IDE.

Your new string should appear in org.mozilla.gecko.R.string. Here's an example patch that adds the single string pref_private_data_syncedTabs.

Why is this necessary? Mozilla's main localization process is based on XML entities. Localization teams localize the XML entity definitions using existing tools, but they do not see strings.xml itself. Building prepares the final strings.xml for use. You can be sure your changes are in place by finding your entity and string in $OBJDIR/mobile/android/base/res/values/strings.xml.

Modify an existing Android string resource

1. Find the relevant <string> element in mobile/android/base/strings.xml.in.
2. Find the underlying English string entity in mobile/android/base/locales/en-US/android_strings.dtd. Usually, you'll see <string>&string_entity;<string>; the string entity is string_entity.
3. If your change is just fixing a typo (spelling error, capitalization, whitespace), just update the android_strings.dtd.
4. If you are really changing the string, you also need to change the entity name. It's traditional to add or increment a trailing integer, like string_entity2.
5. Build using mach build mobile/android/base or your IDE.

Your updated string should appear. Here's an example patch that changes several strings, including renaming tab_queue_notification_text_singular to tab_queue_notification_text_singular2.

Why is this necessary? Mozilla's localization process only recognizes new string entities, not modified string entities. (The old, unused entity is automatically ignored and eventually deleted.)

Add a new Robocop test

1. Add a Java test file named like mobile/android/tests/browser/robocop/testMyThing.java. This will get your test compiled into the Robocop APK.
2. Add your test file/name section like [testMyThing] to mobile/android/tests/browser/robocop/robocop.ini. Without this, the Robocop test harness will not know about your test!
3. Optionally add HTML, JS, and CSS resources to folder mobile/android/tests/browser/robocop.
4. Run mach build mobile/android to get them built/installed before running your test.
5. Make sure you have host binaries downloaded and configured, following Host Builds (MOZ_HOST_BIN).
6. Run mach robocop testMyThing to run your new test on your device.
7. Iterate!

Here's an example patch that adds a fairly complicated new testSelectionCarets test.

See also some tips on writing UITests, or you can read about Testing on Firefox for Android.

Copy a profile from your phone

E.g., to explore with sqlite3. Use Copy Profile.

Add new Android ids that identify resources that are only included in some builds

If you add a resource that you refer to by ID in code, your build will fail if that resource isn't present in a build that excludes that resource. You'll typically see this when adding a resource that's only used in v11+ builds, which aren't included in resource-constrained builds for Gingerbread.

For example, you'll see log output like:

 14:15:27     INFO -  /builds/slave/…/build/src/mobile/android/base/preferences/GeckoPreferenceFragment.java:122: error: cannot find symbol
 14:15:27     INFO -              return R.id.pref_header_general;

To fix this, you should should add a stub for the new id in mobile/android/base/resources/values/ids.xml.

You should also make sure that code that needs a valid resource id is behind a version check.

Add a new table to browser.db

To follow along with code, see Bug 1250707.

• Capture a current version of the database (before your changes!) with some browsing data from your device using the Copy Profile add-on. Put this in mobile/android/tests/browser/robocop/assets/browser_db_upgrade/v<#>.db. It is used to test your upgrade changes in testBrowserDatabaseHelperUpgrades
• Add your table name & schema as a new static class in BrowserContract
• Increment the DATABASE_VERSION in BrowserDatabaseHelper and update the related bug # comment
• Implement a create method to create your table
  • Add a call to it in BrowserDatabaseHelper.onCreate
  • Add a method to upgrade the database from the old version to the new version (which likely calls your create table method) and add it to BrowserDatabaseHelper.onUpgrade
• Register your new table with BrowserProvider by adding your table to the URI_MATCHER in the BrowserProvider constructor (pattern match the other values). Note the TABLE_* constant, the constants assigned to ints, and the *_PROJECTION_MAP constant.
• Add to the BrowserProvider.query method (pattern match!) by setting the projection map and table in the SQLiteQueryBuilder object.
• Add to the BrowserProvider.insertInTransaction method (pattern match!) by calling out to your own method to insert into the DB
• Test insert!

Explanation of classes

• BrowserContract
• BrowserDatabaseHelper

External how-to's

• Updating the search engine icons
• Updating the Android SDK on the builders