| blob | 97bee9d560c3e14b08af8aab33bd66a5d2b13754 |
2 How to set up and run the sample app as an Android Studio project.
4 Linux (Android Studio version 0.8.11 beta)
5 =====
6 (1) Launch Android Studio.
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.
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".
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]
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]
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.
48 (6) Click "Run".
50 Troubleshooting:
52 (I) If the project doesn't build, there are two typical problems:
53 #1 - make sure that you have the correct 'cronet.jar'.
54 There is one that is part of the Chromium build which
55 does not include org.chromium.base (and so will be missing PathUtil,
56 at least) and one that is part of the cronet build.
58 #2 - If you have vast swaths of red text (errors) in the edit window
59 for CronetSampleActivity, you should confirm that the requisite
60 jar files are present in 'build.gradle'. There are at least 2
61 files which are named 'build.gradle'. Check them both.
62 You should observe the following lines [see footnote 1]
64 dependencies {
65 compile file('libs/cronet.jar')
66 compile file('libs/cornet_stub.jar')
67 }
69 If absent, the lines may be added by hand to the gradle file
70 which corresponds to the module named "app", and not the project
71 s a whole. You might have to press a "Sync" button in the IDE
72 which tells it to re-scan the 'build.gradle' files.
74 (II) If the project builds but doesn't run, verify that the '.so' files
75 are present in your Android package (which is just a jar file in disguise):
76 % jar tf build/outputs/apk/app-debug.apk
77 AndroidManifest.xml
78 res/layout/cronet_sample_activity.xml
79 resource.arsc
80 classes.dex
81 lib/armeabi/libcronet.so
82 lib/armeabi-v7/libcronet.so
83 META-INF
84 etc
86 If the '.so' files are not present, it is likely that Android Studio
87 misinterpreted the containing folder as "ordinary" source code,
88 which, due to lack of any special directive pertaining to it, failed
89 to be copied to the apk. One thing to check for is the spelling
90 of "jniLibs" - it must literally be that, with a capital "L" or
91 it won't work. This is a bit of magic that allows users without
92 the NDK (Native Development Kit) to deploy '.so' files.
93 [With the NDK, things are different because in that case you have to
94 produce the '.so' files, and create build rules to do so,
95 so the setup is naturally more flexible to begin with.]
96 As a visual cue that the folder has been recognized as special,
97 its icon should match that of the "res" (resources) folder
98 which resembles a tabbed manila folder with some extra cross-hatches
99 on the front, and not the icon of the "java" folder.
100 The marking on the icon signifies that its contents land on the
101 the target device. But to keep things interesting, the icon is
102 distinct visually only in "Android" view, not "Project" view.
104 MacOS (Android Studio version 1.0.1)
105 =====
106 (0) You might or might not have to set a magic environment
107 variable as follows [see footnote 3]:
108 export STUDIO_JDK=/Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk
110 (1) Launch Android Studio, which can be achieved from the command
111 line with
112 % open '/Applications/Android Studio.app'
114 (2) Choose "Import Non-Android Studio Project"
115 (a) Navigate to the path containing "sample"
116 (b) Pick a place to put it, and choose "Finish"
118 (3) If you are comfortable using shell commands to create directories,
119 you may proceed to step (3) for Linux above.
120 Otherwise, if you prefer to create directories from the UI,
121 proceed with the following steps.
123 (4) Choose "File -> New -> Folder -> Assets Folder".
124 Check "Change Folder Location" and delete the entire
125 pathname that was there. Change it to 'libs'
126 which is conventional for pre-built jar files.
128 (5) Copy and paste the two pre-built '.jar' files into 'assets'.
129 When you do this, it will say that the destination is
130 "app/libs". This is right. If you prefer to see
131 the file hierarchy as it really exists, you can change
132 the dropdown above the tree view from "android view"
133 to "project view". Or just keep in mind that assets = libs
134 at this level of the hierarchy.
136 (6) Select both jar files that you added (Shift+click).
137 and pull up the menu for them (Ctrl+click).
138 Select "Add as library"
140 (7) Choose "File -> New -> Folder -> JNI Folder".
141 Choose "Change Folder Location"
142 and change the name to "src/main/jniLibs" [see footnote 2]
144 ----
146 Footnotes:
147 [1] "compile file" as used in a dependency line means to package the
148 named jars into the apk, and not to make those files.
149 The opposite of this is "provided file" which assumes that the
150 jars exist on the device already (in whatever the standard
151 location is for systemwide jar files), and not that a file
152 has been externally provided to Android Studio.
154 [2] The menu option to add JNI files assumes that you have the
155 NDK (Native Development Kit) installed and want to produce
156 files into the named directory. This is triggered by an
157 automatic rule that tries to look for C++ source code
158 and the NDK based on the existence of "src/main/jni".
159 Changing this directory to "src/main/jniLibs" is magical
160 in a different way: it informs Android Studio that you will
161 place precompiled binaries into that directory.
163 [3] This has to do with differences between the JDK that the studio
164 runs in as distinct from the JDK that the studio understands
165 to be present on the target machine.
166 There is discussion of the issue in
167 https://code.google.com/p/android/issues/detail?id=82378
169 Additional notes:
171 Ideally the two .jar files and one .so file could be delivered as one .aar
172 (Android Archive) file, but Android Studio will try to pull aar files from
173 a Maven repository without some workarounds that are about as much trouble
174 as adding in three separate files.
175 See https://code.google.com/p/android/issues/detail?id=55863
177 Additionally, it is unclear how to automate the creation of a '.aar' file
178 outside of Android Studio and Gradle. If the entire workflow were controlled
179 by Gradle, it would be one thing; but presently the cronet jars are
180 produced as artifacts of the Chromium build which uses Ninja.