components/cronet/android/sample/README

   1
   2 How to set up and run the sample app as an Android Studio project.
   3
   4 Linux (Android Studio version 0.8.11 beta)
   5 =====
   6 (1) Launch Android Studio.
   7
   8 (2) Choose "Import project".
   9     - Navigate to the location of the sample soure code.
  10       You should be looking at a directory named "sample"
  11       containing a file named "AndroidManifest.xml".
  12     - Pick a new destination for it.
  13
  14 (3) Copy in the '.jar' files.
  15     (a) Directly under the "app" directory of your project,
  16         create a "libs" directory. Use a shell command if you like,
  17         or use "File|New|Directory" from the menu. But note that
  18         you only get "Directory" as an option if you are in
  19         "Project" view, not "Android" view. "Project" models
  20         the local machine's filesystem, but Android is a virtual
  21         layout of files corresponding to the deployed hierarchy.
  22         That is to say, do step (b) before step (a) if you're inclined.
  23     (b) Toggle the view from "Android" to "Project"
  24         in the selection list above the file hierarchy.
  25         Otherwise you won't see "libs".
  26     (c) Copy 'cronet.jar' and 'cronet_stub.jar' to "libs".
  27
  28     [Also note that it is possible to leave the '.jar' files
  29     in their original locations, though this seems to be
  30     somewhat discouraged by convention]
  31
  32 (4) Inform the IDE about the '.jar' files.
  33     (a) Select both files at once.
  34     (b) Bring up the context menu and choose "Add as Library".
  35     (d) Confirm "OK" at the "Add to module" dialog.
  36         [Note: the keyboard shortcut and/or main menu selection
  37         for these steps seems to be missing from Android Studio.
  38         If you prefer, the advice under problem #2
  39         in "Troubleshooting" below will perform the same thing
  40         without reliance on menu selections]
  41
  42 (5) Copy in the '.so' file.
  43     (a) Under "app/src/main" create a directory named "jniLibs"
  44     (b) Copy armeabi and ameabi-v7a into jniLibs, which should
  45         contain only subdirectories, not directly a '.so' file
  46     (c) The IDE will automatically know about these.
  47
  48 (6) Click "Run".
  49
  50 Troubleshooting:
  51
  52 If you have vast swaths of red text (errors) in the edit window
  53 for CronetSampleActivity, you should confirm that the requisite
  54 jar files are present in 'build.gradle'. There are at least 2
  55 files which are named 'build.gradle'. Check them both.
  56 You should observe the following lines [see footnote 1]
  57
  58 dependencies {
  59    compile file('libs/cronet.jar')
  60    compile file('libs/cronet_stub.jar')
  61 }
  62
  63 If absent, the lines may be added by hand to the gradle file
  64 which corresponds to the module named "app", and not the project
  65 s a whole. You might have to press a "Sync" button in the IDE
  66 which tells it to re-scan the 'build.gradle' files.
  67
  68 (II) If the project builds but doesn't run, verify that the '.so' files
  69 are present in your Android package (which is just a jar file in disguise):
  70 % jar tf build/outputs/apk/app-debug.apk
  71 AndroidManifest.xml
  72 res/layout/cronet_sample_activity.xml
  73 resource.arsc
  74 classes.dex
  75 lib/armeabi/libcronet.so
  76 lib/armeabi-v7/libcronet.so
  77 META-INF
  78 etc
  79
  80 If the '.so' files are not present, it is likely that Android Studio
  81 misinterpreted the containing folder as "ordinary" source code,
  82 which, due to lack of any special directive pertaining to it, failed
  83 to be copied to the apk. One thing to check for is the spelling
  84 of "jniLibs" - it must literally be that, with a capital "L" or
  85 it won't work. This is a bit of magic that allows users without
  86 the NDK (Native Development Kit) to deploy '.so' files.
  87 [With the NDK, things are different because in that case you have to
  88 produce the '.so' files, and create build rules to do so,
  89 so the setup is naturally more flexible to begin with.]
  90 As a visual cue that the folder has been recognized as special,
  91 its icon should match that of the "res" (resources) folder
  92 which resembles a tabbed manila folder with some extra cross-hatches
  93 on the front, and not the icon of the "java" folder.
  94 The marking on the icon signifies that its contents land on the
  95 the target device. But to keep things interesting, the icon is
  96 distinct visually only in "Android" view, not "Project" view.
  97
  98 MacOS (Android Studio version 1.0.1)
  99 =====
 100 (0) You might or might not have to set a magic environment
 101     variable as follows [see footnote 3]:
 102     export STUDIO_JDK=/Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk
 103
 104 (1) Launch Android Studio, which can be achieved from the command
 105     line with
 106     % open '/Applications/Android Studio.app'
 107
 108 (2) Choose "Import Non-Android Studio Project"
 109    (a) Navigate to the path containing "sample"
 110    (b) Pick a place to put it, and choose "Finish"
 111
 112 (3) If you are comfortable using shell commands to create directories,
 113     you may proceed to step (3) for Linux above.
 114     Otherwise, if you prefer to create directories from the UI,
 115     proceed with the following steps.
 116
 117 (4) Choose "File -> New -> Folder -> Assets Folder".
 118     Check "Change Folder Location" and delete the entire
 119     pathname that was there. Change it to 'libs'
 120     which is conventional for pre-built jar files.
 121
 122 (5) Copy and paste the two pre-built '.jar' files into 'assets'.
 123     When you do this, it will say that the destination is
 124     "app/libs".  This is right.  If you prefer to see
 125     the file hierarchy as it really exists, you can change
 126     the dropdown above the tree view from "android view"
 127     to "project view". Or just keep in mind that assets = libs
 128     at this level of the hierarchy.
 129
 130 (6) Select both jar files that you added (Shift+click).
 131     and pull up the menu for them (Ctrl+click).
 132     Select "Add as library"
 133
 134 (7) Choose "File -> New -> Folder -> JNI Folder".
 135     Choose "Change Folder Location"
 136     and change the name to "src/main/jniLibs" [see footnote 2]
 137
 138 ----
 139
 140 Footnotes:
 141 [1] "compile file" as used in a dependency line means to package the
 142     named jars into the apk, and not to make those files.
 143     The opposite of this is "provided file" which assumes that the
 144     jars exist on the device already (in whatever the standard
 145     location is for systemwide jar files), and not that a file
 146     has been externally provided to Android Studio.
 147
 148 [2] The menu option to add JNI files assumes that you have the
 149     NDK (Native Development Kit) installed and want to produce
 150     files into the named directory. This is triggered by an
 151     automatic rule that tries to look for C++ source code
 152     and the NDK based on the existence of "src/main/jni".
 153     Changing this directory to "src/main/jniLibs" is magical
 154     in a different way: it informs Android Studio that you will
 155     place precompiled binaries into that directory.
 156
 157 [3] This has to do with differences between the JDK that the studio
 158     runs in as distinct from the JDK that the studio understands
 159     to be present on the target machine.
 160     There is discussion of the issue in
 161     https://code.google.com/p/android/issues/detail?id=82378
 162
 163 Additional notes:
 164
 165 Ideally the two .jar files and one .so file could be delivered as one .aar
 166 (Android Archive) file, but Android Studio will try to pull aar files from
 167 a Maven repository without some workarounds that are about as much trouble
 168 as adding in three separate files.
 169 See https://code.google.com/p/android/issues/detail?id=55863
 170
 171 Additionally, it is unclear how to automate the creation of a '.aar' file
 172 outside of Android Studio and Gradle. If the entire workflow were controlled
 173 by Gradle, it would be one thing; but presently the cronet jars are
 174 produced as artifacts of the Chromium build which uses Ninja.