Bug 1234629 - Post: Add simple bouncer APK docs. r=me a=sylvestre
authorNick Alexander <nalexander@mozilla.com>
Mon, 14 Mar 2016 14:41:44 -0700
changeset 319306 2a62a6f3237ecda90639ec803e6a89d27fe448e5
parent 319305 a2d5576923fe2606ab7abc357c4b7c3000b6d451
child 319307 100db9ea57a6e906aca2e2da8a4582e3d84b3efe
child 326486 ba934d8ed3cf84dd42e2966d540e976d3a01f5ff
push id1079
push userjlund@mozilla.com
push dateFri, 15 Apr 2016 21:02:33 +0000
treeherdermozilla-release@575fbf6786d5 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersme, sylvestre
bugs1234629
milestone46.0
Bug 1234629 - Post: Add simple bouncer APK docs. r=me a=sylvestre MozReview-Commit-ID: Bzv33pwm8og
mobile/android/docs/bouncer.rst
mobile/android/docs/defaultdomains.rst
mobile/android/docs/gradle.rst
mobile/android/docs/index.rst
new file mode 100644
--- /dev/null
+++ b/mobile/android/docs/bouncer.rst
@@ -0,0 +1,38 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+=========================================
+ The Firefox for Android install bouncer
+=========================================
+
+`Bug 1234629 <https://bugzilla.mozilla.org/show_bug.cgi?id=1234629>`_ and `Bug 1163082
+<https://bugzilla.mozilla.org/show_bug.cgi?id=1163082>`_ combine to allow building a very small
+Fennec-like "bouncer" APK that redirects (bounces) a potential Fennec user to the marketplace of
+their choice -- usually the Google Play Store -- to install the real Firefox for Android application
+APK.
+
+The real APK should install seamlessly over top of the bouncer APK.  Care is taken to keep the
+bouncer and application APK <permission> manifest definitions identical, and to have the bouncer APK
+<activity> manifest definitions look similar to the application APK <activity> manifest definitions.
+
+In addition, the bouncer APK can carry a Fennec distribution, which it copies onto the device before
+redirecting to the marketplace.  The application APK recognizes the installed distribution and
+customizes itself accordingly on first run.
+
+The motivation is to allow partners to pre-install the very small bouncer APK on shipping devices
+and to have a smooth path to upgrade to the full application APK, with a partner-specific
+distribution in place.
+
+Technical details
+=================
+
+To build the bouncer APK, define ``MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER``.  To pack a distribution
+into the bouncer APK (and *not* into the application APK), add a line like::
+
+  ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample
+
+to your ``mozconfig`` file.  See the `general distribution documentation on the wiki
+<https://wiki.mozilla.org/Mobile/Distribution_Files>`_ for more information.
+
+The ``distribution`` directory should end up in the ``assets/distribution`` directory of the bouncer
+APK.  It will be copied into ``/data/data/$ANDROID_PACKAGE_NAME/distribution`` when the bouncer
+executes.
--- a/mobile/android/docs/defaultdomains.rst
+++ b/mobile/android/docs/defaultdomains.rst
@@ -67,16 +67,17 @@ list of domains:
 * Remove any URL shorteners and redirecters.
 * Remove any content/CDN domains. Some sites use separate domains to store images and other static
   content.
 
 Guidelines for Adult Content
 ============================
 
 Generally the Adult category includes sites whose dominant theme is either:
+
 * To appeal to the prurient interest in sex without any serious literary, artistic, political, or
   scientific value
 * The depiction or description of nudity, including sexual or excretory activities or organs in a
   lascivious way
 * The depiction or description of sexually explicit conduct in a lascivious way (e.g. for
   entertainment purposes)
 
 For a more complete definition and guidelines of adult content, use the full DMOZ guidelines at
deleted file mode 100644
--- a/mobile/android/docs/gradle.rst
+++ /dev/null
@@ -1,97 +0,0 @@
-.. -*- Mode: rst; fill-column: 80; -*-
-
-======================
- Building with Gradle
-======================
-
-Instructions
-============
-
-.. code-block:: shell
-
-  ./mach build && ./mach package
-  ./mach gradle build
-
-The debug APK will be at
-``$OBJDIR/mobile/android/gradle/app/build/outputs/apk/app-debug.apk``.
-
-The ``$OBJDIR/mobile/android/gradle`` directory can be imported into IntelliJ as
-follows:
-
-- File > Import Project...
-- [select ``$OBJDIR/mobile/android/gradle``]
-- Import project from external model > Gradle
-- [select Use customizable Gradle wrapper]
-
-When prompted, do not add any files to git.  You may need to re-open the
-project, or restart IntelliJ, to pick up a compiler language-level change.
-
-Technical overview
-==================
-
-Caveats
--------
-
-* The Gradle build will "succeed" but crash on start up if the object directory
-  has not been properly packaged.
-* Changes to preprocessed source code and resources (namely, ``strings.xml.in``
-  and the accompanying DTD files) may not be recognized.
-* There's minimal support for editing JavaScript.
-* There's no support for editing C/C++.
-
-How the Gradle project is laid out
-----------------------------------
-
-To the greatest extent possible, the Gradle configuration lives in the object
-directory.
-
-At the time of writing, there are three main sub-modules: *app*, *base*, and
-*thirdparty*, and several smaller sub-modules.
-
-*app* is the Fennec wrapper; it generates the **org.mozilla.fennec.R** resource
-package.  *base* is the Gecko code; it generates the **org.mozilla.gecko.R**
-resource package.  Together, *app* and *base* address the "two package
-namespaces" that has plagued Fennec from day one.
-
-Due to limitations in the Android Gradle plugin, all test code is shoved into
-the *app* module.  (The issue is that, at the time of writing, there is no
-support for test-only APKs.)  For no particular reason, the compiled C/C++
-libraries are included in the *app* module; they could be included in the *base*
-module.  I expect *base* to rebuilt slightly more frequently than *app*, so I'm
-hoping this choice will allow for faster incremental builds.
-
-*thirdparty* is the external code we use in Fennec; it's built as an Android
-library but uses no resources.  It's separate simply to allow the build system
-to cache the compiled and pre-dexed artifacts, hopefully allowing for faster
-incremental builds.
-
-Recursive make backend details
-------------------------------
-
-The ``mobile/android/gradle`` directory writes the following into
-``$OBJDIR/mobile/android/gradle``:
-
-1) the Gradle wrapper;
-2) ``gradle.properties``;
-3) symlinks to certain source and resource directories.
-
-The Gradle wrapper is written to make it easy to build with Gradle from the
-object directory.  The wrapper is `intended to be checked into version
-control`_.
-
-``gradle.properties`` is the single source of per-object directory Gradle
-configuration, and provides the Gradle configuration access to
-configure/moz.build variables.
-
-The symlinks are not necessary for the Gradle build itself, but they prevent
-nested directory errors and incorrect Java package scoping when the Gradle
-project is imported into IntelliJ.  Because IntelliJ treats the Gradle project
-as authoritative, it's not sufficient to fix these manually in IntelliJ after
-the initial import -- IntelliJ reverts to the Gradle configuration after every
-build.  Since there aren't many symlinks, I've done them in the Makefile rather
-than at a higher level of abstraction (like a moz.build definition, or a custom
-build backend).  In future, I expect to be able to remove all such symlinks by
-making our in-tree directory structures agree with what Gradle and IntelliJ
-expect.
-
-.. _intended to be checked into version control: http://www.gradle.org/docs/current/userguide/gradle_wrapper.html
--- a/mobile/android/docs/index.rst
+++ b/mobile/android/docs/index.rst
@@ -1,24 +1,25 @@
 .. Firefox for Android documentation master file, created by
    sphinx-quickstart on Fri Dec  4 22:51:57 2015.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Firefox for Android's documentation!
-===============================================
+Firefox for Android
+===================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
    localeswitching
    uitelemetry
    adjust
    defaultdomains
+   bouncer
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`