1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/androideclipse.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,90 @@
1.4 +.. _build_androideclipse:
1.5 +
1.6 +========================
1.7 +Android Eclipse Projects
1.8 +========================
1.9 +
1.10 +The build system contains alpha support for generating Android Eclipse
1.11 +project files to aid with development.
1.12 +
1.13 +To generate Android Eclipse project files, you'll need to have a fully
1.14 +built and packaged tree::
1.15 +
1.16 + mach build && mach package
1.17 +
1.18 +(This is because Eclipse itself packages an APK containing
1.19 +``omni.ja``, and ``omni.ja`` is only assembled during packaging.)
1.20 +
1.21 +Then, simply generate the Android Eclipse build backend::
1.22 +
1.23 + mach build-backend -b AndroidEclipse
1.24 +
1.25 +If all goes well, the path to the generated projects should be
1.26 +printed (currently, ``$OBJDIR/android_eclipse``).
1.27 +
1.28 +To use the generated Android Eclipse project files, you'll need to
1.29 +have a recent version of Eclipse (see `Tested Versions`_) with the
1.30 +`Eclipse ADT plugin
1.31 +<http://developer.android.com/tools/sdk/eclipse-adt.html>`_
1.32 +installed. You can then import all the projects into Eclipse using
1.33 +*File > Import ... > General > Existing Projects into Workspace*.
1.34 +
1.35 +Updating Project Files
1.36 +======================
1.37 +
1.38 +As you pull and update the source tree, your Android Eclipse files may
1.39 +fall out of sync with the build configuration. The tree should still
1.40 +build fine from within Eclipse, but source files may be missing and in
1.41 +rare circumstances Eclipse's index may not have the proper build
1.42 +configuration.
1.43 +
1.44 +To account for this, you'll want to periodically regenerate the
1.45 +Android Eclipse project files. You can do this by running ``mach build
1.46 +&& mach package && mach build-backend -b AndroidEclipse`` from the
1.47 +command line. It's a good idea to refresh and clean build all projects
1.48 +in Eclipse after doing this.
1.49 +
1.50 +In future, we'd like to include an Android Eclipse run configuration
1.51 +or build target that integrates updating the project files.
1.52 +
1.53 +Currently, regeneration rewrites the original project files. **If
1.54 +you've made any customizations to the projects, they will likely get
1.55 +overwritten.** We would like to improve this user experience in the
1.56 +future.
1.57 +
1.58 +Troubleshooting
1.59 +===============
1.60 +
1.61 +If Eclipse's builder gets confused, you should always refresh and
1.62 +clean build all projects. If Eclipse's builder is continually
1.63 +confused, you can see a log of what is happening at
1.64 +``$OBJDIR/android_eclipse/build.log``.
1.65 +
1.66 +If you run into memory problems executing ``dex``, you should
1.67 +`Increase Eclipse's memory limits <http://stackoverflow.com/a/11093228>`_.
1.68 +
1.69 +The produced Android Eclipse project files are unfortunately not
1.70 +portable. Please don't move them around.
1.71 +
1.72 +Structure of Android Eclipse projects
1.73 +=====================================
1.74 +
1.75 +The Android Eclipse backend generates several projects spanning Fennec
1.76 +itself and its tests. You'll mostly interact with the *Fennec* project
1.77 +itself.
1.78 +
1.79 +In future, we'd like to expand this documentation to include some of
1.80 +the technical details of how the Eclipse integration works, and how to
1.81 +add additional Android Eclipse projects using the ``moz.build``
1.82 +system.
1.83 +
1.84 +Tested Versions
1.85 +===============
1.86 +
1.87 +=============== ==================================== =================
1.88 +OS Version Working as of
1.89 +=============== ==================================== =================
1.90 +Mac OS X Luna (Build id: 20130919-0819) February 2014
1.91 +Mac OS X Kepler (Build id: 20131219-0014) February 2014
1.92 +Mac OS X 10.8.5 Kepler (Build id: 20130919-0819) February 2014
1.93 +=============== ==================================== =================
