Quick-start instructions for Cronet Sample Application

components/cronet/android/sample/README

Index: components/cronet/android/sample/README
diff --git a/components/cronet/android/sample/README b/components/cronet/android/sample/README
new file mode 100644
index 0000000000000000000000000000000000000000..7e909ae1f55c72826b4e12f032f0c33c1c9ee9b8
--- /dev/null
+++ b/components/cronet/android/sample/README
@@ -0,0 +1,157 @@
+
+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 chromium/src/components/cronet/android/sample
+    - pick a 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"
+
+(4) Inform the IDE about the Jar files
+    (a) Shift+click both files
+    (b) Right mouse
+    (c) Pick "Add as Library"
+    (d) Confirm "OK" at the "Add to module" dialog
+
+(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"
+
+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 that. Look in them both.
+You should observe the following lines:
+
+dependencies {
+   compile file('libs/cronet.jar')
+   compile file('libs/cornet_stub.jar')
+}   
+"compile" as used here means to package those jars into the apk,
+and not to make those files.
+
+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.
+
+If the project builds but doesn't run, verify that the '.so' files
+re 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 (studio version 1.0.1)

[dougk, 2015/02/05 22:42:36]

oh forgot this "Android Studio"

+=====
+(0) you might have to set a magic environment variable as follows:
+  export STUDIO_JDK=/Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk
+
+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.
+
+(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"
+       I'll use "~/my_example"
+
+(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,
+    the following approach will work:
+
+(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"
+    The reason you have to change the name is that Gradle has an automatic
+    rule that tries to build binary libraries in src/main/jni.
+    But you don't want to trigger that rule because it will complains if
+    you don't have the Native Development Kit.
+    The magic name of "jniLibs" tells Android Studio that you only
+    want to depend on the libraries therein.
+
+----
+
+Internal note:
+
+Ideally the two .jar files and one .so file could be delivered as one .aar
+(Android Archive) file, but 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.