michael@0: .. _build_androideclipse:
michael@0: 
michael@0: ========================
michael@0: Android Eclipse Projects
michael@0: ========================
michael@0: 
michael@0: The build system contains alpha support for generating Android Eclipse
michael@0: project files to aid with development.
michael@0: 
michael@0: To generate Android Eclipse project files, you'll need to have a fully
michael@0: built and packaged tree::
michael@0: 
michael@0:    mach build && mach package
michael@0: 
michael@0: (This is because Eclipse itself packages an APK containing
michael@0: ``omni.ja``, and ``omni.ja`` is only assembled during packaging.)
michael@0: 
michael@0: Then, simply generate the Android Eclipse build backend::
michael@0: 
michael@0:    mach build-backend -b AndroidEclipse
michael@0: 
michael@0: If all goes well, the path to the generated projects should be
michael@0: printed (currently, ``$OBJDIR/android_eclipse``).
michael@0: 
michael@0: To use the generated Android Eclipse project files, you'll need to
michael@0: have a recent version of Eclipse (see `Tested Versions`_) with the
michael@0: `Eclipse ADT plugin
michael@0: <http://developer.android.com/tools/sdk/eclipse-adt.html>`_
michael@0: installed. You can then import all the projects into Eclipse using
michael@0: *File > Import ... > General > Existing Projects into Workspace*.
michael@0: 
michael@0: Updating Project Files
michael@0: ======================
michael@0: 
michael@0: As you pull and update the source tree, your Android Eclipse files may
michael@0: fall out of sync with the build configuration. The tree should still
michael@0: build fine from within Eclipse, but source files may be missing and in
michael@0: rare circumstances Eclipse's index may not have the proper build
michael@0: configuration.
michael@0: 
michael@0: To account for this, you'll want to periodically regenerate the
michael@0: Android Eclipse project files. You can do this by running ``mach build
michael@0: && mach package && mach build-backend -b AndroidEclipse`` from the
michael@0: command line. It's a good idea to refresh and clean build all projects
michael@0: in Eclipse after doing this.
michael@0: 
michael@0: In future, we'd like to include an Android Eclipse run configuration
michael@0: or build target that integrates updating the project files.
michael@0: 
michael@0: Currently, regeneration rewrites the original project files. **If
michael@0: you've made any customizations to the projects, they will likely get
michael@0: overwritten.** We would like to improve this user experience in the
michael@0: future.
michael@0: 
michael@0: Troubleshooting
michael@0: ===============
michael@0: 
michael@0: If Eclipse's builder gets confused, you should always refresh and
michael@0: clean build all projects. If Eclipse's builder is continually
michael@0: confused, you can see a log of what is happening at
michael@0: ``$OBJDIR/android_eclipse/build.log``.
michael@0: 
michael@0: If you run into memory problems executing ``dex``, you should
michael@0: `Increase Eclipse's memory limits <http://stackoverflow.com/a/11093228>`_.
michael@0: 
michael@0: The produced Android Eclipse project files are unfortunately not
michael@0: portable. Please don't move them around.
michael@0: 
michael@0: Structure of Android Eclipse projects
michael@0: =====================================
michael@0: 
michael@0: The Android Eclipse backend generates several projects spanning Fennec
michael@0: itself and its tests. You'll mostly interact with the *Fennec* project
michael@0: itself.
michael@0: 
michael@0: In future, we'd like to expand this documentation to include some of
michael@0: the technical details of how the Eclipse integration works, and how to
michael@0: add additional Android Eclipse projects using the ``moz.build``
michael@0: system.
michael@0: 
michael@0: Tested Versions
michael@0: ===============
michael@0: 
michael@0: ===============    ====================================    =================
michael@0: OS                 Version                                 Working as of
michael@0: ===============    ====================================    =================
michael@0: Mac OS X           Luna (Build id: 20130919-0819)          February 2014
michael@0: Mac OS X           Kepler (Build id: 20131219-0014)        February 2014
michael@0: Mac OS X 10.8.5    Kepler (Build id: 20130919-0819)        February 2014
michael@0: ===============    ====================================    =================