Quick-start instructions for Cronet Sample Application

BUG=none

Review URL: https://codereview.chromium.org/864663004

Cr-Commit-Position: refs/heads/master@{#315102}

components/cronet/android/sample/README

+
+How to set up and run the sample app as an Android Studio project.
+
+Linux (Android Studio version 0.8.11 beta)
+=====
+(1) Launch Android Studio.
+
+(2) Choose "Import project".
+    - Navigate to the location of the sample soure code.
+      You should be looking at a directory named "sample"
+      containing a file named "AndroidManifest.xml".
+    - Pick a new destination for it.
+
+(3) Copy in the '.jar' files.
+    (a) Directly under the "app" directory of your project,
+        create a "libs" directory. Use a shell command if you like,
+        or use "File|New|Directory" from the menu. But note that
+        you only get "Directory" as an option if you are in
+        "Project" view, not "Android" view. "Project" models
+        the local machine's filesystem, but Android is a virtual
+        layout of files corresponding to the deployed hierarchy.
+        That is to say, do step (b) before step (a) if you're inclined.
+    (b) Toggle the view from "Android" to "Project"
+        in the selection list above the file hierarchy.
+        Otherwise you won't see "libs".
+    (c) Copy 'cronet.jar' and 'cronet_stub.jar' to "libs".
+    
+    [Also note that it is possible to leave the '.jar' files
+    in their original locations, though this seems to be
+    somewhat discouraged by convention]
+     
+(4) Inform the IDE about the '.jar' files.
+    (a) Select both files at once.
+    (b) Bring up the context menu and choose "Add as Library".
+    (d) Confirm "OK" at the "Add to module" dialog.
+        [Note: the keyboard shortcut and/or main menu selection
+        for these steps seems to be missing from Android Studio.
+        If you prefer, the advice under problem #2
+        in "Troubleshooting" below will perform the same thing
+        without reliance on menu selections]
+
+(5) Copy in the '.so' file.
+    (a) Under "app/src/main" create a directory named "jniLibs"
+    (b) Copy armeabi and ameabi-v7a into jniLibs, which should
+        contain only subdirectories, not directly a '.so' file
+    (c) The IDE will automatically know about these.
+ 
+(6) Click "Run".
+
+Troubleshooting:
+
+(I) If the project doesn't build, there are two typical problems:
+#1 - make sure that you have the correct 'cronet.jar'.
+There is one that is part of the Chromium build which 
+does not include org.chromium.base (and so will be missing PathUtil,
+at least) and one that is part of the cronet build.
+
+#2 - If you have vast swaths of red text (errors) in the edit window
+for CronetSampleActivity, you should confirm that the requisite
+jar files are present in 'build.gradle'. There are at least 2
+files which are named 'build.gradle'. Check them both.
+You should observe the following lines [see footnote 1]
+
+dependencies {
+   compile file('libs/cronet.jar')
+   compile file('libs/cornet_stub.jar')
+}   
+
+If absent, the lines may be added by hand to the gradle file
+which corresponds to the module named "app", and not the project
+s a whole. You might have to press a "Sync" button in the IDE
+which tells it to re-scan the 'build.gradle' files.
+
+(II) If the project builds but doesn't run, verify that the '.so' files
+are present in your Android package (which is just a jar file in disguise):
+% jar tf build/outputs/apk/app-debug.apk
+AndroidManifest.xml
+res/layout/cronet_sample_activity.xml
+resource.arsc
+classes.dex
+lib/armeabi/libcronet.so
+lib/armeabi-v7/libcronet.so
+META-INF
+etc
+
+If the '.so' files are not present, it is likely that Android Studio
+misinterpreted the containing folder as "ordinary" source code,
+which, due to lack of any special directive pertaining to it, failed
+to be copied to the apk. One thing to check for is the spelling
+of "jniLibs" - it must literally be that, with a capital "L" or
+it won't work. This is a bit of magic that allows users without
+the NDK (Native Development Kit) to deploy '.so' files.
+[With the NDK, things are different because in that case you have to
+produce the '.so' files, and create build rules to do so,
+so the setup is naturally more flexible to begin with.]
+As a visual cue that the folder has been recognized as special,
+its icon should match that of the "res" (resources) folder
+which resembles a tabbed manila folder with some extra cross-hatches
+on the front, and not the icon of the "java" folder.
+The marking on the icon signifies that its contents land on the
+the target device. But to keep things interesting, the icon is
+distinct visually only in "Android" view, not "Project" view.
+
+MacOS (Android Studio version 1.0.1)
+=====
+(0) You might or might not have to set a magic environment
+    variable as follows [see footnote 3]:
+    export STUDIO_JDK=/Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk
+
+(1) Launch Android Studio, which can be achieved from the command
+    line with
+    % open '/Applications/Android Studio.app'
+
+(2) Choose "Import Non-Android Studio Project"
+   (a) Navigate to the path containing "sample"
+   (b) Pick a place to put it, and choose "Finish"
+
+(3) If you are comfortable using shell commands to create directories,
+    you may proceed to step (3) for Linux above.
+    Otherwise, if you prefer to create directories from the UI,
+    proceed with the following steps.
+
+(4) Choose "File -> New -> Folder -> Assets Folder".
+    Check "Change Folder Location" and delete the entire
+    pathname that was there. Change it to 'libs'
+    which is conventional for pre-built jar files.
+
+(5) Copy and paste the two pre-built '.jar' files into 'assets'.
+    When you do this, it will say that the destination is
+    "app/libs".  This is right.  If you prefer to see
+    the file hierarchy as it really exists, you can change
+    the dropdown above the tree view from "android view" 
+    to "project view". Or just keep in mind that assets = libs
+    at this level of the hierarchy.
+
+(6) Select both jar files that you added (Shift+click).
+    and pull up the menu for them (Ctrl+click).
+    Select "Add as library"
+
+(7) Choose "File -> New -> Folder -> JNI Folder".
+    Choose "Change Folder Location"
+    and change the name to "src/main/jniLibs" [see footnote 2]
+
+----
+
+Footnotes:
+[1] "compile file" as used in a dependency line means to package the
+    named jars into the apk, and not to make those files.
+    The opposite of this is "provided file" which assumes that the
+    jars exist on the device already (in whatever the standard
+    location is for systemwide jar files), and not that a file
+    has been externally provided to Android Studio.
+
+[2] The menu option to add JNI files assumes that you have the
+    NDK (Native Development Kit) installed and want to produce
+    files into the named directory. This is triggered by an
+    automatic rule that tries to look for C++ source code
+    and the NDK based on the existence of "src/main/jni".
+    Changing this directory to "src/main/jniLibs" is magical
+    in a different way: it informs Android Studio that you will
+    place precompiled binaries into that directory.
+
+[3] This has to do with differences between the JDK that the studio
+    runs in as distinct from the JDK that the studio understands
+    to be present on the target machine.
+    There is discussion of the issue in
+    https://code.google.com/p/android/issues/detail?id=82378
+
+Additional notes:
+
+Ideally the two .jar files and one .so file could be delivered as one .aar
+(Android Archive) file, but Android Studio will try to pull aar files from
+a Maven repository without some workarounds that are about as much trouble
+as adding in three separate files.
+See https://code.google.com/p/android/issues/detail?id=55863
+
+Additionally, it is unclear how to automate the creation of a '.aar' file
+outside of Android Studio and Gradle. If the entire workflow were controlled
+by Gradle, it would be one thing; but presently the cronet jars are
+produced as artifacts of the Chromium build which uses Ninja.