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:

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/cronet_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.