View source for 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, [https://developer.mozilla.org/en-US/docs/Tools/Remote_Debugging/Firefox_for_Android 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.

[http://developer.android.com/guide/developing/tools/logcat.html 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, [[Mobile/Fennec/Android/AdvancedTopics#Advanced_Debugging|Advanced Debugging]] is a good place to look.

=== Coding Style ===

The Java style follow the [https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#Java_practices 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 - [https://github.com/mozilla-services/android-sync 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 ===

# Add an XML ''string entity'' to <tt>mobile/android/base/locales/en-US/android_strings.dtd</tt> with the English string you want to add.
# Add a <tt>&lt;string&gt;</tt> element to <tt>mobile/android/base/strings.xml.in</tt>.
# Build using <tt>mach build mobile/android/base</tt> or your IDE.

Your new string should appear in <tt>org.mozilla.gecko.R.string</tt>.  Here's an [https://hg.mozilla.org/mozilla-central/rev/861e4bd9e7fe 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 <tt>strings.xml</tt> itself.  Building prepares the final <tt>strings.xml</tt> for use.  You can be sure your changes are in place by finding your entity and string in <tt>$OBJDIR/mobile/android/base/res/values/strings.xml</tt>.

=== Modify an existing Android string resource ===

# Find the relevant <tt>&lt;string&gt;</tt> element in <tt>mobile/android/base/strings.xml.in</tt>.
# Find the underlying English ''string entity'' in <tt>mobile/android/base/locales/en-US/android_strings.dtd</tt>.  Usually, you'll see <tt>&lt;string&gt;&amp;string_entity&semi;&lt;string&gt;</tt>; the string entity is ''string_entity''.
# If your change is just fixing a typo (spelling error, capitalization, whitespace), just update the <tt>android_strings.dtd</tt>.
# 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''.
# Build using <tt>mach build mobile/android/base</tt> or your IDE.

Your updated string should appear.  Here's an [https://hg.mozilla.org/mozilla-central/rev/1e8c1b79132f 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 ===

# Add a Java test file named like <tt>mobile/android/tests/browser/robocop/testMyThing.java</tt>.  This will get your test compiled into the Robocop APK.
# Add your test file/name section like ''[testMyThing]'' to <tt>mobile/android/tests/browser/robocop/robocop.ini</tt>. Without this, the Robocop test harness will not know about your test!
# Optionally add HTML, JS, and CSS resources to folder <tt>mobile/android/tests/browser/robocop</tt>.
# Run <tt>mach build mobile/android</tt> to get them built/installed before running your test.
# Make sure you have host binaries downloaded and configured, following [[Mobile/Fennec/Android#Host_Builds_.28MOZ_HOST_BIN.29|Host Builds (MOZ_HOST_BIN)]].
# Run <tt>mach robocop testMyThing</tt> to run your new test on your device.
# Iterate!

Here's an [https://hg.mozilla.org/mozilla-central/rev/101feffdaed8 example patch] that adds a fairly complicated new ''testSelectionCarets'' test.

See also some tips on writing [[Mobile/Fennec/Android/UITest|UITest]]s, or you can read about [[Mobile/Fennec/Android/Testing|Testing on Firefox for Android]].

=== Copy a profile from your phone ===

E.g., to explore with <tt>sqlite3</tt>. Use [https://addons.mozilla.org/en-US/android/addon/copy-profile/ 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:

<pre>
 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;
</pre>

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

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

=== External how-to's ===
*[[Mobile/Fennec/Android/Updating search engine icons|Updating the search engine icons]]
*[[Mobile/Fennec/Android/Updating_SDK_on_builders|Updating the Android SDK on the builders]]