MozillaWiki

Mobile/Fennec/Android/IDEs: Difference between revisions

< Mobile‎ | Fennec‎ | Android
(→‎Really quick start: Add warning that 'mach ide intellij' doesn't seem to work for mach artifact)
 
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
There is support for building Fennec using Eclipse or IntelliJ in the tree.
There is support for building Fennec using IntelliJ or Android Studio in the tree.


= IntelliJ with Gradle =
= IntelliJ or Android Studio with Gradle =
This is currently the preferred direction that IDE support will be moving towards.


nalexander has a [http://www.ncalexander.net/blog/2014/10/23/building-fennec-with-gradle-and-intellij-first-steps/ blog post] for getting a basic setup with IntelliJ.
This is the direction that IDE support is moving towards. Most Android front-end developers are using IntelliJ with Gradle today. We support building, running, and debugging Java and Android resources with IntelliJ.  We support editing JavaScript (but not debugging) JavaScript as well.


(There is also a detailed but outdated [http://perplexedturnip.wordpress.com/2013/07/31/bludgeoning-intellij-idea-into-being-useful-for-mobile-firefox-development/ blog post] by ckitching.)
== Pre-requisites ==


= Eclipse =
The Gradle build requires the following additional Android packages:
'''Building Fennec with Eclipse requires a custom Eclipse plugin'''.


The preliminary Eclipse support landed in {{bug|853045}}, and further enhancements are tracked at {{bug|924961}}. {{bug|1029232}} landed the changes that require the custom Eclipse plugin.
* Android Support Repository
* Google Repository  


== Prerequisities ==
Install them by navigating to the ''Extras'' section of the SDK list shown by the <tt>android</tt> tool (shipped with the Android SDK).


* [http://eclipse.org/ Eclipse] (Luna 4.4 is recommended; Kepler 4.2 should work as well)
The [http://mxr.mozilla.org/mozilla-central/source/mobile/android/gradle/app/build.gradle gradle config files] also explicitly specify the version (e.g., SDK v21 and build tools v21.1.1), in order to decrease IntelliJ problems in detecting the right version of Android tools to use. See {{bug|1123013}} for details.
* the most recent [https://developer.android.com/tools/sdk/eclipse-adt.html Eclipse ADT plugin]


You'll need a Mozilla source tree, like ''fx-team'' or ''mozilla-central'', and your mozconfig configured to build Fennec (see [Mobile/Fennec/Android#Setup_Fennec_mozconfig]).  You'll probably want to increase Eclipse's memory limits, as described in [http://stackoverflow.com/a/11093228 this stack overflow answer]. If you don't, you might hit GC issues because Android’s <code>dex</code> takes a good deal of memory.
The Gradle/IDE integration requires Android-Gradle plugin version '''1.0.0'''.  This, in turn, mandates either
* IntelliJ '''14.0.3 or higher''' (currently Early Access Preview only!); or
* Android Studio '''1.0.0''' or higher.
: See {{bug|1120032}} for details.


== Install the custom plugin ==
=== Installing specific versions of the Android SDK and build tools ===
To list all Android packages, including those marked Obsolete, use:
  android list sdk --all --extended
You should see entries like:
  id: 6 or "build-tools-21.1.1"
      Type: BuildTool
      Desc: Android SDK Build-tools, revision 21.1.1 (Obsolete)
To install a particular version, use a command like the following:
  android update sdk --all --no-ui --filter "build-tools-21.1.1"


Installing the plugin is easy.  The plugin is available to install from an Eclipse update site at https://people.mozilla.org/~nalexander/eclipse/update-site/.  In Eclipse, navigate to ''Help > Install New Software...''.  Add the update site with ''Name: fennec-eclipse'' and ''Location: https://people.mozilla.org/~nalexander/eclipse/update-site/''.  Select ''OK'', and you should see the ''Fennec Make Build Plugin''.  Check the box and click ''Next...'' to install it.  After you've installed, you may need to restart Eclipse.
== Really quick start ==


== Prepare the Mozilla source tree ==
'''Warning: this doesn't seem to work for a mach artifact build, follow the Quick Start instructions below instead.'''


First, run
Try:
  ./mach ide intellij
or
  ./mach ide androidstudio
That should build and package your tree, prepare the IDE files, and open the project in the IDE of your choice.


  mach build && mach package
Unfortunately, IntelliJ (and maybe Android Studio) follows the symlink, giving the wrong path in the import dialog.  Correct the path manually so that it is <tt>$OBJDIR/mobile/android/gradle</tt>, where <tt>$OBJDIR</tt> is your object directory.  (The correct directory is printed by the <tt>mach ide</tt> command.)  Select ''OK'' to complete the import.  Try it out by choosing ''Build'' > ''Rebuild project''!


That builds all the C/C++ libraries that Fennec needs, and installs them into the correct location.  Then, run
The <tt>mach ide</tt> command always builds and packages your tree, so it can be a little slow.  After you've run it once, you can usually just open the existing project in your IDE directly.


  mach build-backend -b=AndroidEclipse
== Quick start ==


That writes Eclipse project files and other support files needed to build in Eclipse.  Make a note of the path that <code>mach build-backend</code> outputs; that path contains the Eclipse project files, and you'll need it in a moment.
# Build and package your tree:
#: <pre>./mach build && ./mach package</pre>
# Configure Gradle to build Fennec.  '''Do not skip this step: it configures your object directory for Gradle.'''
#: <pre>./mach gradle-install</pre>
# Optionally, verify that Gradle can build Fennec:
#: <pre>./mach gradle build</pre>
# Finally, import the newly created Gradle projects into IntelliJ/Android Studio:
#* ''File'' > ''Import Project...'' and select <tt>$OBJDIR/mobile/android/gradle</tt>, where <tt>$OBJDIR</tt> is your object directory.  (The correct directory is printed by the <tt>mach gradle-install</tt> command.)
#* Select ''Import project from external model'' > ''Gradle'' > ''Next''.
#* Select ''Use customizable gradle wrapper'' > ''Finish''.
# You'll need to configure your Android SDK.  Go to ''File'' > ''Project Structure'', and then
#* Select ''Android API 21 platform'' for the Project SDK (or whatever is appropriate for your configuration).  You may be prompted to add a ''JAVA SDK'' first: your IDE should find a JDK 1.7 or 1.8 install automatically.
#* Select ''7 - Diamonds, ARM, multi-catch etc.'' for the Project language level.


== Import the project files into Eclipse ==
You should have a shiny new Gradle-based project in your IDE!  Try it out by choosing ''Build'' > ''Rebuild project''.


In Eclipse, go to ''File > Import...'' and select ''General > Existing Projects into Workspace''. Enter the path printed by <code>mach build-backend</code>. You should see many projects, including one named ''Fennec''. We want that one, and all its dependencies; at the moment, that means
== Trouble shooting ==
=== General build/SDK problems ===
Before asking in #mobile, check the following:
* Are you running at least IntelliJ 14.0.3, the EAP/preview version. You can change your update channel in IntelliJ > Preferences > (search) Updates, and select "Early Access Program" as your update channel.
* Do you have an Android SDK in your project structure? Make sure that in File > Project Structure > SDKs, you have a JRE as well as an Android SDK. If you don't have the latter, go back to the instructions and try Step 5 to configure your Android SDK.
* Is the Gradle configuration working?
  <code>./mach gradle build</code>
* Do your Android SDK tools match what's required in the [http://mxr.mozilla.org/mozilla-central/source/mobile/android/gradle/app/build.gradle gradle config files]? (<code>compileSdkVersion</code> and <code>buildToolsVersion</code>)
* Is Gradle busted?
  <code>./mach gradle clean assembleDebug</code>
* If you've pulled in changes to the Gradle configuration lately, refresh Gradle: View > Tool Windows > Gradle and click the blue "sync" button in the top left.
* If changes don't seem to be taking, make sure the cache is cleared with File > Invalidate caches. Restart.
* Does your error look like ''Error: Internal error: (java.io.FileNotFoundException) $OBJDIR/mobile/android/gradle/.idea/misc.xml (No such file or directory)''? Try running <tt>mach gradle-install</tt> and re-importing <tt>$OBJDIR/mboile/android/gradle</tt>.


* ''Fennec''
=== Why aren't my JavaScript changes being noticed? ===
* ''FennecOmnijar''
* ''FennecResources''
* ''FennecResourcesBranding''
* ''FennecResourcesGenerated''


== Test your Eclipse configuration ==
The Gradle configuration recognizes JavaScript changes (like ''mobile/android/chrome/content/browser.js'' and ''mobile/android/modules/Messaging.jsm'') underneath the ''mobile/android'' directory.  It does not recognize changes in other places in the tree, including under ''toolkit/''.  To make Gradle pick up your changes, modify a JavaScript file under ''mobile/android''.  Or, if you have a command line handy, run
mach build mobile/android/base/gradle-omnijar
Then re-run Gradle; you should find your changes are noticed.


You should be able to build in Eclipse now!  Try a clean build by selecting ''Project > Clean...''.  If all goes well, you will end up with no errors and a great deal of warnings.
=== Import problems ===


Try to deploy an Eclipse-built Fennec to your device. Right click the ''Fennec'' project, and select ''Run as... > Android Application''. You should see messages about uploading APKs in the ''Android Console'' pane, and you should see Fennec start on your device.
Due to incompatibilities between IntelliJ 14.0.2 and the Android-Gradle plugin version 1.0.0, there's a bug with importing in IntelliJ 14.0.2 that manifests as completed imports with no source directories. IntelliJ 14.0.3 with Android-Gradle plugin version 1.0.0 should not have the issue; Android Studio 1.0.0 should be fine too.  See {{bug|1120032}} for details.


== Frequently asked questions ==
=== Debugging problems ===


* I've run <code>mach build-backend -b=AndroidEclipse</code>. Why do the Eclipse project directories look so empty?
There's a known bug that can make debugging start but fail to stop at breakpoints when using IntelliJ 14.0.2.  It's due to incompatibilities between IntelliJ 14.0.2 and the Android-Gradle plugin version 0.14.4.  IntelliJ 14.0.3 with Android-Gradle plugin version 1.0.0 should not have the issue; Android Studio 1.0.0 should be fine too.


The answer is [http://www.ncalexander.net/blog/2014/07/08/how-the-android-eclipse-integration-works/ complicated], but it's because some of things needed for a working Eclipse project require <code>mach build && mach package</code> to happen first, and (technically) a build backend happens ''before'' build and package time.  The Eclipse project directories are filled during the first Eclipse build (by the custom Eclipse plugin).
=== Memory ===


* I'm getting errors building with Eclipse.  What should I do?
IntelliJ/Android Studio can require a good deal of memory:


Your first step is to go to ''Eclipse > Preferences... > Android > Build'' and set the ''Build output'' setting to ''Normal''.  That will show logging from the custom plugin and from the Eclipse Android integration that can help.
* Optionally, toggle ''Show Memory Indicator'';
* you might need to increase memory in <tt>$INTELLIJ/bin/idea.vmoptions</tt>.  Suggested values for min and max are:
** Xms512m
** Xmx2048m


Your second step is to try refreshing all projects (Right click projects > ''Refresh'') and then doing a clean build (''Project > Clean build ...'').
=== Additional file types ===


* I clobbered and now my Eclipse projects are gone!
You might want to add <tt>*.java.in</tt> and other preprocessed files to ''Settings'' > ''File Types'' > ''Java source files''.  This will help you browse the few preprocessed files remaining, including <tt>AppConstants.java.in</tt>.


The Mozilla build system doesn't have much support for writing to a location that's not the object directory (yet!).  That means that when you clobber (delete the object directory entirely), the Eclipse projects get deleted.  That's okay, though: you can reconstitute them by re-running
== Video tutorial ==


  mach build-backend -b=AndroidEclipse
nalexander has a slightly [http://www.ncalexander.net/blog/2014/10/23/building-fennec-with-gradle-and-intellij-first-steps/ outdated blog post] that describes an earlier version of this basic setup with IntelliJ.  It includes a short video tutorial.
 
* I can import some projects (like ''FennecResources'') but not the main ''Fennec'' project.
 
Make sure you're using ''General > Existing Projects into Workspace'' and '''not''' ''Android > Existing Android Code into Workspace''.  For reasons unknown, the latter doesn't recognize some of the generated projects.
 
== The custom Eclipse plugin ==
 
=== What the plugin does ===
 
The plugin is conceptually simple: as the first step of the Eclipse build for each project, it executes a single shell command (if necessary). Indeed, it replaces a custom ANT build invocation that did exactly the same work. Some of the advantages of the plugin are
 
* error markers in the Eclipse ''Problems'' pane
* build output in the Eclipse ''Android Console''
* faster builds
* it is less likely to cause the build to loop forever.
 
=== Source code ===
 
The source code for the plugin (and the related Eclipse feature and update site) is hosted at
https://github.com/ncalexan/fennec-eclipse.  Pull requests are always welcome!


= Support =
= Support =


The first place to ask questions is #mobile on irc.mozilla.org.  Start there.
The first place to ask questions is [https://wiki.mozilla.org/Mobile/Get_Involved#IRC #mobile on IRC].  nalexander is the architect and implementer of most of the Eclipse integration.  rnewman, mcomella, mhaigh, liuche, and margaret all run the integration as part of their daily development.  bnicholson contributed significantly to earlier versions of this work.
 
nalexander is the architect and implementer of most of the Eclipse integration.  rnewman, mcomella, and liuche all run, or have run, the integration as part of their daily development.  bnicholson contributed significantly to earlier versions of this work.


nalexander's [http://www.ncalexander.net/blog/ blog] is usually the first place to find tutorials, screencasts, and previews of new features.
nalexander's [http://www.ncalexander.net/blog/ blog] is usually the first place to find tutorials, screencasts, and previews of new features.
Line 100: Line 116:
= Additional resources =
= Additional resources =


There is a [http://www.ncalexander.net/blog/2014/06/24/better-fennec-builds-with-an-eclipse-plugin/ getting started screencast].  There is also a [http://www.ncalexander.net/blog/2014/03/24/eclipse-mini-tutorials/ series of video mini-tutorials].
There's a blog post discussing [http://www.ncalexander.net/blog/2014/07/08/how-the-android-eclipse-integration-works/ technical details of how the Eclipse build integration works].


There's a blog post discussing [http://www.ncalexander.net/blog/2014/07/08/how-the-android-eclipse-integration-works/ technical details of how the Eclipse build integration works].
Historically, Fennec supported building with Eclipse. '''Eclipse support is now deprecated''', but the documentation is archived at [[Mobile/Fennec/Android/IDEs/Eclipse]].

Latest revision as of 23:09, 1 December 2015

There is support for building Fennec using IntelliJ or Android Studio in the tree.

IntelliJ or Android Studio with Gradle

This is the direction that IDE support is moving towards. Most Android front-end developers are using IntelliJ with Gradle today. We support building, running, and debugging Java and Android resources with IntelliJ. We support editing JavaScript (but not debugging) JavaScript as well.

Pre-requisites

The Gradle build requires the following additional Android packages:

  • Android Support Repository
  • Google Repository

Install them by navigating to the Extras section of the SDK list shown by the android tool (shipped with the Android SDK).

The gradle config files also explicitly specify the version (e.g., SDK v21 and build tools v21.1.1), in order to decrease IntelliJ problems in detecting the right version of Android tools to use. See bug 1123013 for details.

The Gradle/IDE integration requires Android-Gradle plugin version 1.0.0. This, in turn, mandates either

  • IntelliJ 14.0.3 or higher (currently Early Access Preview only!); or
  • Android Studio 1.0.0 or higher.
See bug 1120032 for details.

Installing specific versions of the Android SDK and build tools

To list all Android packages, including those marked Obsolete, use: 

 android list sdk --all --extended

You should see entries like: 

 id: 6 or "build-tools-21.1.1"
      Type: BuildTool
      Desc: Android SDK Build-tools, revision 21.1.1 (Obsolete)

To install a particular version, use a command like the following: 

 android update sdk --all --no-ui --filter "build-tools-21.1.1"

Really quick start

Warning: this doesn't seem to work for a mach artifact build, follow the Quick Start instructions below instead.

Try: 

 ./mach ide intellij

or 

 ./mach ide androidstudio

That should build and package your tree, prepare the IDE files, and open the project in the IDE of your choice.

Unfortunately, IntelliJ (and maybe Android Studio) follows the symlink, giving the wrong path in the import dialog. Correct the path manually so that it is $OBJDIR/mobile/android/gradle, where $OBJDIR is your object directory. (The correct directory is printed by the mach ide command.) Select OK to complete the import. Try it out by choosing Build > Rebuild project!

The mach ide command always builds and packages your tree, so it can be a little slow. After you've run it once, you can usually just open the existing project in your IDE directly.

Quick start

  1. Build and package your tree: 
    ./mach build && ./mach package
  2. Configure Gradle to build Fennec. Do not skip this step: it configures your object directory for Gradle. 
    ./mach gradle-install
  3. Optionally, verify that Gradle can build Fennec: 
    ./mach gradle build
  4. Finally, import the newly created Gradle projects into IntelliJ/Android Studio:
    • File > Import Project... and select $OBJDIR/mobile/android/gradle, where $OBJDIR is your object directory. (The correct directory is printed by the mach gradle-install command.)
    • Select Import project from external model > Gradle > Next.
    • Select Use customizable gradle wrapper > Finish.
  5. You'll need to configure your Android SDK. Go to File > Project Structure, and then
    • Select Android API 21 platform for the Project SDK (or whatever is appropriate for your configuration). You may be prompted to add a JAVA SDK first: your IDE should find a JDK 1.7 or 1.8 install automatically.
    • Select 7 - Diamonds, ARM, multi-catch etc. for the Project language level.

You should have a shiny new Gradle-based project in your IDE! Try it out by choosing Build > Rebuild project.

Trouble shooting

General build/SDK problems

Before asking in #mobile, check the following:

  • Are you running at least IntelliJ 14.0.3, the EAP/preview version. You can change your update channel in IntelliJ > Preferences > (search) Updates, and select "Early Access Program" as your update channel.
  • Do you have an Android SDK in your project structure? Make sure that in File > Project Structure > SDKs, you have a JRE as well as an Android SDK. If you don't have the latter, go back to the instructions and try Step 5 to configure your Android SDK.
  • Is the Gradle configuration working?
 ./mach gradle build
  • Do your Android SDK tools match what's required in the gradle config files? (compileSdkVersion and buildToolsVersion)
  • Is Gradle busted?
 ./mach gradle clean assembleDebug
  • If you've pulled in changes to the Gradle configuration lately, refresh Gradle: View > Tool Windows > Gradle and click the blue "sync" button in the top left.
  • If changes don't seem to be taking, make sure the cache is cleared with File > Invalidate caches. Restart.
  • Does your error look like Error: Internal error: (java.io.FileNotFoundException) $OBJDIR/mobile/android/gradle/.idea/misc.xml (No such file or directory)? Try running mach gradle-install and re-importing $OBJDIR/mboile/android/gradle.

Why aren't my JavaScript changes being noticed?

The Gradle configuration recognizes JavaScript changes (like mobile/android/chrome/content/browser.js and mobile/android/modules/Messaging.jsm) underneath the mobile/android directory. It does not recognize changes in other places in the tree, including under toolkit/. To make Gradle pick up your changes, modify a JavaScript file under mobile/android. Or, if you have a command line handy, run 

mach build mobile/android/base/gradle-omnijar

Then re-run Gradle; you should find your changes are noticed.

Import problems

Due to incompatibilities between IntelliJ 14.0.2 and the Android-Gradle plugin version 1.0.0, there's a bug with importing in IntelliJ 14.0.2 that manifests as completed imports with no source directories. IntelliJ 14.0.3 with Android-Gradle plugin version 1.0.0 should not have the issue; Android Studio 1.0.0 should be fine too. See bug 1120032 for details.

Debugging problems

There's a known bug that can make debugging start but fail to stop at breakpoints when using IntelliJ 14.0.2. It's due to incompatibilities between IntelliJ 14.0.2 and the Android-Gradle plugin version 0.14.4. IntelliJ 14.0.3 with Android-Gradle plugin version 1.0.0 should not have the issue; Android Studio 1.0.0 should be fine too.

Memory

IntelliJ/Android Studio can require a good deal of memory:

  • Optionally, toggle Show Memory Indicator;
  • you might need to increase memory in $INTELLIJ/bin/idea.vmoptions. Suggested values for min and max are:
    • Xms512m
    • Xmx2048m

Additional file types

You might want to add *.java.in and other preprocessed files to Settings > File Types > Java source files. This will help you browse the few preprocessed files remaining, including AppConstants.java.in.

Video tutorial

nalexander has a slightly outdated blog post that describes an earlier version of this basic setup with IntelliJ. It includes a short video tutorial.

Support

The first place to ask questions is #mobile on IRC. nalexander is the architect and implementer of most of the Eclipse integration. rnewman, mcomella, mhaigh, liuche, and margaret all run the integration as part of their daily development. bnicholson contributed significantly to earlier versions of this work.

nalexander's blog is usually the first place to find tutorials, screencasts, and previews of new features.

Additional resources

There's a blog post discussing technical details of how the Eclipse build integration works.

Historically, Fennec supported building with Eclipse. Eclipse support is now deprecated, but the documentation is archived at Mobile/Fennec/Android/IDEs/Eclipse.

Retrieved from "https://wiki.allizom.org/index.php?title=Mobile/Fennec/Android/IDEs&oldid=1108007"