Revision 1070318 of Simple Firefox for Android build

<div class="note">
<p>This page covers the basic steps needed to build a bleeding-edge, development version of <strong>Firefox for Android</strong>, also known as <strong>Fennec. </strong>Welcome, we're delighted to see you! :)<br />
 <br />
 If you're having trouble following this documentation or hit a roadblock you can't get around, please contact Nick Alexander at <a class="link-mailto" href="mailto:[email protected]" rel="freelink">[email protected]</a> directly so we can solve the problem for you and every new contributor after you.</p>
</div>

<p>For additional, more detailed information, see the <a href="https://wiki.mozilla.org/Mobile/Fennec">Firefox for Android wiki</a> and the general Firefox <a class="internal" href="/en-US/docs/Mozilla/Developer_guide/Build_Instructions" title="/en-US/docs/Developer_Guide/Build_Instructions">build documentation</a>.</p>

<h2 id="Build_prerequisites">Build prerequisites</h2>

<p><strong>Right now it is possible to build Firefox for Android on most UNIX-like systems, including Mac OS X and many flavors of Linux.</strong> Most core developers run Mac OS X; a handful run Linux.</p>

<div class="warning">
<p><strong>Building Firefox for Android on Microsoft Windows is not yet supported.</strong>&nbsp; There is no hard reason that it should not be possible (now; in the past, it was not possible because Google did not release certain parts of the Android toolchain for Windows), but it's also not a priority. If you're interested in building on Windows, or can contribute, please CC yourself onto <a class="external text" href="https://bugzilla.mozilla.org/show_bug.cgi?id=1169873" rel="nofollow">bug 1169873</a>.</p>
</div>

<h3 id="Hardware_requirements">Hardware requirements</h3>

<ul>
 <li>While you can build Firefox on older hardware it can take quite a bit of time to compile on slower machines, and having at least 8GB of RAM is recommended.</li>
 <li>If you have older hardware, it is strongly recommended that you use <a href="#Artifact_mode">artifact mode</a>.</li>
 <li>Fast broadband internet is strongly recommended as well. Both the development environment and the source code repository are quite large. <a href="#Artifact_mode">Artifact mode</a> regularly downloads large (50MB) binary archives.</li>
 <li>You must have a 64-bit operating system. As of early 2015 it is no longer possible to build Firefox on most 32-bit machines.</li>
 <li>If you're going to install Firefox for Android on a physical Android device, you'll need one running Android Ice Cream Sandwich (API 15) or later.</li>
</ul>

<h2 id="Bootstrap_dependencies">Bootstrap dependencies</h2>

<p>Run either of the following in a terminal.&nbsp; You'll need Python version 2.7 or later and <code>curl</code> or <code>wget</code>.&nbsp; If you have <code>curl</code> installed (note that Mac OS X ships curl by default):</p>

<pre>
curl -O <a class="external free" href="https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py" rel="nofollow">https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py</a> &amp;&amp; python bootstrap.py
</pre>

<p>Or, if you have <code>wget</code> installed instead:</p>

<pre>
wget -q <a class="external free" href="https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py" rel="nofollow">https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py</a> &amp;&amp; python bootstrap.py
</pre>

<p>Choose <strong>Firefox for Android</strong> when prompted.&nbsp; The bootstrapping script will install system packages, the Android SDK (and NDK, if required), and the currently required versions of the Android platform and extras.</p>

<p>The bootstrap script will print out configuration options for you when it finishes more on this below.&nbsp; For now, copy this configuration text and continue on.&nbsp; You can re-run the bootstrap script to print this information again later.</p>

<p>Once you have all the dependencies installed, you need to clone the Firefox repository.</p>

<h2 id="Get_the_source">Get the source</h2>

<p>Get the latest source code from Mozilla's Mercurial code repository. This may take a while; it's a lot of code!&nbsp; We recommend that you add the progress extension to your Mercurial configuration.&nbsp; This will provide feedback during the lengthy clone process.&nbsp; See the documentation explaining how to <a href="https://mercurial.selenic.com/wiki/ProgressExtension">enable the Mercurial progress extension</a>.</p>

<pre>
hg clone https://hg.mozilla.org/mozilla-central
</pre>

<p>If you are using a slow or unreliable internet connection, <code>hg clone</code> might fail because it gets interrupted. In that case, you are strongly encouraged to download a <a href="/en-US/docs/Mozilla/Developer_guide/Source_Code/Mercurial/Bundles" title="/en-US/docs/Developer_Guide/Source_Code/Mercurial/Bundles">Mercurial bundle</a> file instead of waiting for <code>hg clone</code>.</p>

<h2 id="Choose_what_parts_of_Firefox_for_Android_you_want_to_modify">Choose what parts of Firefox for Android you want to modify</h2>

<p>Firefox for Android is built in two layers.&nbsp; The Firefox for Android “front-end” — which includes the home panels, UI for settings, menus, etc., Firefox Sync, and most data storage — is implemented using Java, the Android Platform SDK, JavaScript, HTML, and CSS.&nbsp; Firefox for Android is built on top of the Gecko platform back-end. Gecko is Mozilla's web rendering engine, similar to Edge, Blink, and WebKit, and is responsible for rendering web content, running JavaScript code, and providing web APIs to pages. Gecko is implemented using C++ and JavaScript.</p>

<p>Here is a table summarizing the pros and cons of working on the different parts.</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Configuration</th>
   <th scope="col">Restrictions</th>
   <th scope="col">Implementation languages</th>
   <th scope="col">Build speed</th>
   <th scope="col">Integrated development environment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><strong>front-end</strong></td>
   <td>Can only modify main UI, not web platform</td>
   <td>Java, JavaScript</td>
   <td>Fast builds</td>
   <td>Android Studio or IDEA IntelliJ</td>
  </tr>
  <tr>
   <td><strong>back-end</strong></td>
   <td>None: can modify everything</td>
   <td>C++, JavaScript</td>
   <td>Slow builds</td>
   <td>None: use your text editor</td>
  </tr>
 </tbody>
</table>

<p>Do you want to modify just Firefox for Android, or do you want to modify the Gecko platform?</p>

<ul>
 <li><a href="#Artifact_mode">I want to work on the front-end: the look and feel of Firefox for Android. </a></li>
 <li><a href="#Non_Artifact_Mode">I want to work on the back-end: Web APIs, HTML rendering or other parts of the Gecko platform.</a></li>
</ul>

<div class="note">
<p><strong>If you don't know what you want, start with just the Firefox for Android front-end</strong>: your build times will be much shorter if you don't build the Gecko back-end as well.</p>

<p>But don't worry! You can always add the back-end configuration later, and it's easy to switch between the configurations.</p>
</div>

<h2 id="Prepare_a_Firefox_for_Android_mozconfig"><span class="mw-headline" id="Preparing_a_Fennec_mozconfig">Prepare a Firefox for Android mozconfig</span></h2>

<p>The build scripts will read from the <code>mozconfig</code> file in your source directory (where you cloned the <code>mozilla-central</code> source repository into) to determine what kind of build to produce, <a class="external text" href="https://developer.mozilla.org/en-US/docs/Configuring_Build_Options" rel="nofollow">although you can configure this if you need to</a>.&nbsp; You must use <code>$HOME</code> instead of <code>~</code> in your mozconfig because <code>~</code> does not get expanded.</p>

<p>By default, the build system creates a build of Firefox for Android roughly equivalent to the official Firefox for Android Nightly builds. If that's not exactly what you want, there are many build configuration options to choose from, although it's <strong>strongly</strong> recommended that you only use options that you fully understand.</p>

<h3 id="I_want_to_work_on_the_front-end"><a id="Artifact_mode" name="Artifact_mode"></a>I want to work on the front-end</h3>

<p>Firefox for Android supports a <strong>fast build mode</strong> called <em><a href="/en-US/docs/Artifact_builds">artifact mode</a></em>.&nbsp; (Some mobile team managers call it <em>manager mode </em>since it's particularly helpful if you only write code infrequently.)&nbsp; <em>Artifact mode</em> downloads pre-built C++ components rather than building them locally, trading bandwidth for time.</p>

<p>To use <em>artifact mode</em>, paste the following into your <code>mozconfig</code> file:</p>

<pre>
# Build Firefox for Android:
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi

# With the following Android SDK:
ac_add_options --with-android-sdk="/absolute/path/to/android-sdk"

# Enable artifact building:
ac_add_options --enable-artifact-builds

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend</pre>

<p>You should be ready to build with <em>artifact mode</em>!</p>

<h3 id="I_want_to_work_on_the_back-end"><a id="Non_Artifact_Mode" name="Non_Artifact_Mode"></a>I want to work on the back-end</h3>

<p>Paste the following into your <code>mozconfig</code> file:</p>

<pre>
# Build Firefox for Android:
ac_add_options --enable-application=mobile/android
<code>ac_add_options --target=arm-linux-androideabi</code>

# With the following Android SDK and NDK:
ac_add_options --with-android-sdk="/absolute/path/to/android-sdk"
ac_add_options --with-android-ndk="/absolute/path/to/android-ndk-r10e" 

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-droid</pre>

<p>If you're planning on hacking the C/C++ code, you probably want to create a debug build instead of a release build.&nbsp; Add the following lines to your <code>mozconfig</code>:</p>

<pre>
ac_add_options --enable-debug
ac_add_options --disable-optimize
</pre>

<h3 id="Configuration_options">Configuration options</h3>

<h4 id="I_want_to_build_an_x86_version_of_Firefox_for_Android">I want to build an x86 version of Firefox for Android</h4>

<div class="warning">
<p>Note: Only API 15+ are supported on x86 architecture.</p>
</div>

<div class="warning">
<p>Note: Hardware acceleration for Android emulators may not work within virtual machine even if nested virtualization is enabled.</p>
</div>

<p>Version 23 and later Android x86 emulators with hardware acceleration are fast enough for local development.&nbsp; They're an attractive alternative if you have recent hardware and an old Android device (or no Android device).&nbsp; Both artifact mode and regular mode support building APKs for x86 architectures.&nbsp; Just replace the line <code>ac_add_options --target=arm-linux-androideabi</code> with:</p>

<pre>
ac_add_options --target=i386-linux-android</pre>

<p>(You probably want to change the <code>MOZ_OBJDIR</code> directory, too.)&nbsp; Now when you build, you should produce an x86 version of Firefox for Android!</p>

<p>For more configuration options, see the general Firefox documentation on <a href="/en-US/docs/Configuring_Build_Options" title="/en-US/docs/Configuring_Build_Options">configuring build options</a>.</p>

<h2 id="Deploy_Firefox_to_an_Android_device">Deploy Firefox to an Android device</h2>

<h3 id="Quick_start">Quick start</h3>

<p>The bare minimum: run these commands to build, package, install, and run a fresh Firefox for Android on your Andorid device.</p>

<pre>
./mach build
./mach package
./mach install
./mach run</pre>

<h3 id="Build">Build</h3>

<p>Enter the <code>mozilla-central </code>subdirectory (created by the <code>hg clone</code> command).</p>

<p>To build Firefox for Android (compile and link all C/C++, Java, and JavaScript source code), run:</p>

<pre>
./mach build
</pre>

<p>Building can take a significant amount of time, depending on your hardware, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but builds on a slow machine may take several hours. <strong>If you're using <em>artifact mode</em>, builds should take less than five minutes.</strong> See <a href="/en-US/docs/Developer_Guide/Mozilla_build_FAQ#Making_builds_faster" title="/en-US/docs/Developer_Guide/Mozilla_build_FAQ#Making_builds_faster">tips for making builds faster</a>.</p>

<div class="note">
<p>The first time you run <code>mach build</code>, <code>mach</code> will ask you if you'd like to create a <code>.mozbuild</code> directory in your home folder and wait 20 seconds for your answer. This a good default location and you should allow it to create the directory.</p>
</div>

<h3 id="Rebuild">Rebuild</h3>

<p>To build after making changes, run</p>

<pre>
./mach build
</pre>

<p>again. This will only rebuild what is necessary for these changes. It is also possible to use</p>

<pre>
./mach build mobile/android
</pre>

<p>to build only changed Firefox for Android front-end code. If you are using <em>artifact mode</em>, this should always work.<em> </em>If you are building the Gecko back-end, this may yield incorrect results, so it is <strong>not recommended</strong>.</p>

<h3 id="Package">Package</h3>

<p>Running an Android application on a device is a little more involved than running a Desktop Firefox binary.&nbsp; First, we need to package everything into an Android package. &nbsp;To produce an APK, run</p>

<p>If you're using <em>artifact mode</em>, run</p>

<pre>
./mach package</pre>

<p>The produced APK file can be found in your <code>$OBJDIR/dist</code> folder, and will be called something like <code>fennec-45.0a1.en-US.android-arm.apk</code>.</p>

<h3 id="Install_and_run">Install and run</h3>

<p>To install the Android package to your device and launch it, <a class="external text" href="https://developer.android.com/guide/developing/device.html" rel="nofollow">connect your Android device and enable USB debugging</a>, and then run</p>

<pre>
./mach install
./mach run</pre>

<p>The name of the App that appears on your Android device will be "Fennec $USER", where $USER is the username under which you built the code.</p>

<p>Note that you will need a device running Android Ice Cream Sandwich (API 15) or later.</p>

<h2 id="Developing_Firefox_for_Android_in_Android_Studio_or_IDEA_IntelliJ">Developing Firefox for Android in Android Studio or IDEA IntelliJ</h2>

<p>The Firefox for Android front-end team develop the product in IDEA IntelliJ (both Community and Ultimate Editions) and Android Studio.&nbsp; There is a Gradle build configuration, parallel to the <code>mach build</code> configuration.&nbsp; Eventually, we intend to use Gradle in the <code>mach build</code> configuration.</p>

<p>The Gradle configuration is now "in the source directory".&nbsp; To verify that everything is working, ensure that you've built and packaged successfully, and then run:</p>

<pre>
./gradlew clean app:assembleDebug</pre>

<p>Next, simply import the top source directory (<code>mozilla-central</code>, as produced by <code>hg clone</code>) into your IDE.&nbsp; This depends on the IDE; in Android Studio, it looks like:</p>

<div class="threecolumns">
<p><img alt="Choose &quot;Import from Gradle&quot;." src="https://mdn.mozillademos.org/files/12061/Screen%20Shot%202015-12-06%20at%201.58.14%20PM.png" style="height:300px; width:378px" /></p>

<p><img alt="Choose the top source directory." src="https://mdn.mozillademos.org/files/12063/Screen%20Shot%202015-12-06%20at%201.59.14%20PM.png" style="height:300px; width:378px" /></p>

<p><img alt="The IDE shows several projects after importing the top source directory." src="https://mdn.mozillademos.org/files/12065/Screen%20Shot%202015-12-06%20at%202.00.06%20PM.png" style="height:300px; width:507px" /></p>

<p>&nbsp;</p>
</div>

<p>In IDEA IntelliJ, it looks like:</p>

<ul>
 <li><em>File</em> &gt;<em> Import Project...</em> and select <code>/path/to/mozilla-central</code>.</li>
 <li>Select <em>Import project from external model</em> &gt; <em>Gradle</em> &gt;<em> Next</em>.</li>
 <li>Select <em>Use default gradle wrapper</em> &gt;<em> Finish</em>.</li>
</ul>

<p>You should have a shiny new Gradle-based project in your IDE! Try it out by choosing<em> Build</em> &gt; <em>Rebuild project</em>.</p>

<h3 id="Setting_the_RunDebug_Configuration_and_Build_Variant"><a id="Build_Variant" name="Build_Variant"></a>Setting the Run/Debug Configuration and Build Variant</h3>

<p>The Gradle build configuration may contain more than one Gradle module, which can define many Run/Debug Configurations.&nbsp; You want the "app" Run Configuration:</p>

<p><img alt="Choose &quot;app&quot; from the Run Configurations list." src="https://mdn.mozillademos.org/files/12431/IDE.Modules.png" style="height:241px; width:600px" /></p>

<p>See the <a href="https://www.jetbrains.com/idea/help/run-debug-configuration-android-application.html">IntelliJ documentation</a> for more.</p>

<p>The configuration also defines multiple Product Flavors, which contribute to Build Variants.&nbsp; You want:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Testing device or emulator Android API</th>
   <th scope="col">Product Flavor</th>
   <th scope="col">Build Variant</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>&gt;=21</td>
   <td>local</td>
   <td>localDebug</td>
  </tr>
  <tr>
   <td>&lt;21</td>
   <td>localOld</td>
   <td>localOldDebug</td>
  </tr>
 </tbody>
</table>

<p><img alt="Choose &quot;local&quot; if you have an Android 21+ device; choose &quot;localOld&quot; if you have an Android &lt;21 device." src="https://mdn.mozillademos.org/files/12433/IDE.Build.Variants.png" style="height:600px; width:352px" /></p>

<p>See the <a href="https://tools.android.com/tech-docs/new-build-system/user-guide#TOC-Build-Variants">Google build documentation</a> for more.</p>

<h3 id="Things_that_are_supported_in_the_IDE">Things that are supported in the IDE</h3>

<ul>
 <li>Running, debugging, and profiling Firefox for Android in the IDE.&nbsp; The <em>app</em> project defines the Android Application.</li>
 <li>Editing Java source code under <code>mobile/android</code>.&nbsp; Modifications to any of the Java code should prompt a fresh build and install.</li>
 <li>Editing Android resources under <code>mobile/android</code>, including in <code>mobile/android/base/resources</code>.&nbsp; In many cases the Android Layout Editor is fully functional.</li>
 <li>Modifying the Android string definitions in <code>mobile/android/base/strings.xml.in</code> and <code>mobile/android/base/locales/en-US/*.dtd</code>.&nbsp; Modifications should be picked up at the next build; they may not be noticed automatically.&nbsp; (This is because the Android <code>strings.xml</code> file is generated, and the generation only happens in response to a build.)</li>
 <li>Editing "omnijar" JavaScript source code under <code>mobile/android</code>, including in <code>mobile/android/content</code>, <code>mobile/android/components</code>, and <code>mobile/android/modules</code>, and under <code>toolkit/</code>.&nbsp; Modifications to JavaScript code should be picked up at the next build.&nbsp; Such modifications should rebuild the omnijar and prompt a fresh build and install.</li>
 <li>Editing "omnijar" chrome XHTML, CSS, and JS resources under <code>mobile/android</code>, including in <code>mobile/android/content</code>, and under <code>toolkit/</code>.</li>
</ul>

<h3 id="Things_that_are_not_supported_in_the_IDE">Things that are not supported in the IDE</h3>

<ul>
 <li>Modifying build system configuration and definitions and modifying <code>mobile/android/base/AndroidManifest.xml.in</code> or the sub-manifests.&nbsp; See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1221344">bug 1221344</a> for an example of what can go wrong here.</li>
 <li>Modifying generate Java code such as <code>mobile/android/base/java/org/mozilla/gecko/AppConstants.java.in</code>.</li>
 <li>Modifying C++ source code anywhere in the tree.</li>
 <li>Modifying "omnijar" JavaScript source code outside of <code>mobile/android</code>.&nbsp; (If you modify JavaScript outside of <code>mobile/android</code>, say under <code>dom/</code>, the changes will be recognized the next time "omnijar" files inside <code>mobile/android</code> are edited.)</li>
 <li>Running Robocop tests.&nbsp; (Use <code>mach robocop</code> to run these tests locally.)</li>
 <li>Running <code>mochitest-chrome</code> tests.&nbsp; (Use <code>mach test</code> to run these tests locally.)</li>
</ul>

<h3 id="Troubleshooting">Troubleshooting</h3>

<ul>
 <li>
  <p>First, check if the Gradle configuration is working.&nbsp; Make sure</p>

  <pre>
./gradlew clean app:assembleDebug</pre>

  <p>completes successfully.</p>
 </li>
 <li>
  <p>Second, check that you're building the correct Gradle module and the correct build variant. If you see a runtime error like</p>

  <pre>
A/GeckoLoader: Couldn't load mozglue. Trying native library dir.
A/GeckoLoader: Library doesn't exist when it should.
</pre>
  then you are probably running the "automation" Build Variant.&nbsp; See the documentation on <a href="#Build_Variant">Build Variants</a> and the discussion in <a class="external text" href="https://bugzilla.mozilla.org/show_bug.cgi?id=1246055" rel="nofollow">bug 1246055</a>.</li>
 <li>
  <p>Third, ensure that you can install the APK to your device.&nbsp; Make sure</p>

  <pre>
./gradlew clean app:install{Local,LocalOld}Debug</pre>

  <p>completes successfully, where you choose "Local" or "LocalOld" depending on your target device.&nbsp; See the documentation on <a href="#Build_Variant">Build Variants</a>.</p>
 </li>
 <li>It's possible to confuse the IDE about the state of the source directory.&nbsp; To recover, try the following:
  <ul>
   <li>Select the <em>root project</em> and refresh everything in the IDE.</li>
   <li>Open the root <code>build.gradle</code> file. If the IDE warns that the Gradle configuration has changed, accept the offer to <em>Sync now</em>.</li>
   <li>Refresh the Gradle model manually: select <em>View &gt; Tool Windows &gt; Gradle</em> and click the blue <em>Sync</em> button in the top left.&nbsp; In Android Studio, there's an icon to do this in the main toolbar -- it's labeled <em>Sync Project with Gradle Files</em>.</li>
   <li>Clear the IDE cache manually:&nbsp; select <em>File &gt; Invalidate caches</em> and then restart the IDE.&nbsp; (This should never be necessary.)</li>
  </ul>
 </li>
</ul>

<h2 id="Required_Android_SDK_and_NDK_versions"><span class="mw-headline" id="Android_NDK_and_SDK_version_notes">Required Android SDK and NDK versions</span></h2>

<p>The Fennec build system requires the following versions:</p>

<p>If your build fails because you're missing one of the Android or Google requirements, your first step should be to run <code>mach bootstrap</code>. If you don't want to run the bootstrapper, you can manually install by running the Android SDK manager: try <code>mach android</code>, or <code>$ANDROID_SDK/tools/android</code>.</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Requirement</th>
   <th scope="col">Version required</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>Android SDK Platform</td>
   <td><strong>Android 6.0 (API 23)</strong></td>
  </tr>
  <tr>
   <td>SDK Build Tools</td>
   <td><strong>23.0.3</strong></td>
  </tr>
  <tr>
   <td>SDK Platform Tools</td>
   <td><strong>23.0.1</strong></td>
  </tr>
  <tr>
   <td>Android SDK Tools</td>
   <td><strong>23.0.1</strong></td>
  </tr>
  <tr>
   <td>Android Support Repository</td>
   <td><strong>21</strong> (or later)</td>
  </tr>
  <tr>
   <td>Google Repository</td>
   <td><strong>22</strong> (or later)</td>
  </tr>
  <tr>
   <td>Android NDK</td>
   <td><strong>r11b</strong></td>
  </tr>
 </tbody>
</table>

<p><a class="external text" href="https://bugzilla.mozilla.org/show_bug.cgi?id=1207680" rel="nofollow">bug 1207680</a> tracks listing these version requirements in one place in the source code.</p>