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..9d8496ba953e09eca9f744ce95485cc9fe652177
--- /dev/null
+++ b/components/cronet/android/sample/README
@@ -0,0 +1,124 @@
+
+How to set up and run the sample app as an android studio project.

[pauljensen, 2015/02/05 15:23:58]

android studio -> Android Studio

[dougk, 2015/02/05 21:56:24]

Done.

+
+Linux (studio version 0.8.11 beta)

[pauljensen, 2015/02/05 15:23:58]

studio -> Android Studio

[dougk, 2015/02/05 21:56:24]

Done.

+=====
+(1) Launch Android Studio

[mef, 2015/02/05 17:02:46]

Should line items be complete sentences with periods?

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

In theory the outline form itself need not have a period one the single-line
pieces,
but it's hard to say since I've made some paragraph-length pieces which are
technically no longer outline form.
And there's the question of period inside (grammatically correct) or outside of
a trailing final quote.
I'll be a little more generous with the periods, and start with a capital letter
though.

+
+(2) Choose "Import project"
+    - navigate to chromium/src/components/cronet/android/sample

[mef, 2015/02/05 17:02:46]

Conceivably Sample app source code is / could be packaged with Cronet build. 

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

Is that a suggested addition to the text?

[mef, 2015/02/05 22:56:12]

Yeah, I'd say something like 'navigate to location of sample source code'.

[dougk, 2015/02/06 17:35:15]

Done.

+    - 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

[mef, 2015/02/05 17:02:46]

I like elaborate explanation!

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

Acknowledged.

+        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"

[pauljensen, 2015/02/05 15:23:58]

Should we explain where these files come from and provide a pointer for how to
build them? (perhaps a link to another README about building cronet)

[mef, 2015/02/05 17:02:46]

I think link to another README about building is fine, but this README I would
target towards app developers who would want to try/use pre-built Cronet.

[dougk, 2015/02/05 21:56:24]

yes, we should. Would it be ok to have the initial checkin of this make some
assumptions about what you already have rather than explain how to do a strictly
bottom-up assembly of all constituent pieces?

+
+(4) Inform the IDE about the Jar files

[mef, 2015/02/05 17:02:46]

Is step 3c required if we are doing 4? I mean, could you just inform IDE about
jars that sit elsewhere?

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

Yes, it's fine to have the jars sitting next to '.java' files.  I tried that. I
wasn't sure what was canonical.
But I'm fairly certain it is not idiomatic to point at places in the filesystem
outside the project, with the exception of network-accessible packages. I'll say
something about "you can leave them where you like"

+    (a) Shift+click both files
+    (b) Right mouse

[mef, 2015/02/05 17:02:46]

FWIW Mac doesn't have right mouse.

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

Indeed, it is control+click on the Mac. Not only that, I could not even find a
keyboard equivalent for this step. I could add a parenthetical remark -
[Note: the keyboard equivalent for these steps seems to be nonexistent. You may
replace this step with the resolution advice for Problem #2 under "If the
project does not build"]

Wdyt?

[mef, 2015/02/05 22:56:12]

I expect target audience to be familiar with UI patterns specific to their
platform, so maybe 'select both files, pick "Add as Library" from context menu'
is sufficient?

[dougk, 2015/02/06 17:35:14]

Done.

+    (c) Pick "Add as Library"
+    (d) Confirm "OK" at the "Add to module" dialog
+    (e) If you wish, confirm that you can navigate
+        into the jar files and see their interfaces.
+Note: This should have added into build.gradle the following:
+dependencies {
+   compile file('libs/cronet.jar')
+   compile file('libs/cornet_stub.jar')
+}   
+enabling the IDE to see the classes and interfaces in the jars.
+"compile" as used here means package those jars into the apk.
+You could also add those lines by hand.
+
+(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,

[mef, 2015/02/05 17:02:46]

Should this be a 'troubleshooting' section?

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

yes, will rename.

+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.
+
+If it 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

[pauljensen, 2015/02/05 15:23:58]

Should we provide a pointer for what to do if the files aren't present?

[dougk, 2015/02/05 21:56:24]

I'll explain that the jniLibs directory should have a slightly different icon
from the icon for a "plain old directory" in the tree view, which gives it the
magic behavior of stuffing its contents as-is into the 'apk' Unfortunately if it
doesn't have that behavior, I don't actually know what to do myself.

+
+MacOS (studio version 1.0.1)
+=====
+(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) Ignore the instructions below,
+    here and proceed from step (3) for Linux.
+
+Alternate instructions
+(Don't do these, they're screwy)

[pauljensen, 2015/02/05 15:23:58]

Why are we including these if they aren't a good idea?

[dougk, 2015/02/05 21:56:24]

Well, I thought it strange that the steps above involved dropping to a shell
prompt. Surely there's a UI for it, right? Or so I thought.  But ultimately it
is no more more convenient unless you have a particular fondness for menu
choices and an aversion to shell commands.

So, pick your poison: whip out a shell command, or use the menu and manually
override what it would do by default.  That was my rationale but I'm ok with
removing this section entirely, or calling it "If you prefer to use menu
selections"

Incidentally, this is a known problem - I chatted with a developer of the
Android Studio about it, and he says that the UI lacks polish that would make
this feel less clunky. The flaw is that the obvious menu choices "Add JNI" and
"Add resource" mean "I want to _produce_ these", and not "I want to _use_
these".
But you can coerce one into the other by counteracting the default behavior
through renaming of the directory that it creates. 

+
+- 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.
+
+- 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.
+
+- Select both jar files that you added (Shift+click)
+  and pull up the menu for them (Ctrl+click).
+  Select "Add as library"
+
+- Choose "File -> New -> Folder -> JNI Folder"
+  Choose "Change Folder Location"
+  and change the name to "src/main/jniLibs"

[mef, 2015/02/05 17:02:46]

I like this explanation, maybe there should be a FYI / Reference section?

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

Will move this to a Footnotes section.

+  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

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

subject/verb agreement: it will complain.

+  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.
+  See for example http://www.shaneenishry.com/blog/2014/08/17/ndk-with-android-studio/
+
+Ideally the two .jar files and one .so file could be delivered as one .aar

[pauljensen, 2015/02/05 15:23:58]

Should we put this under a "SIDE NOTE" title indicating this isn't applicable to
the typical user?

[mef, 2015/02/05 17:02:46]

I think it is more of TODO items for ourselves to make it more friendly.

[dougk, 2015/02/05 21:56:24]

Done.

+(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