1# WebRTC Android development
2
3## Getting the Code
4
5Android development is only supported on Linux.
6
71. Install [prerequisite software][webrtc-prerequisite-sw]
8
92. Create a working directory, enter it, and run:
10
11```
12$ fetch --nohooks webrtc_android
13$ gclient sync
14```
15
16This will fetch a regular WebRTC checkout with the Android-specific parts
17added. Notice that the Android specific parts like the Android SDK and NDK are
18quite large (~8 GB), so the total checkout size will be about 16 GB.
19The same checkout can be used for both Linux and Android development since you
20can generate your [Ninja][ninja] project files in different directories for each
21build config.
22
23See [Development][webrtc-development] for instructions on how to update
24the code, building etc.
25
26
27## Compiling
28
291. Generate projects using GN.
30
31Make sure your current working directory is src/ of your workspace.
32Then run:
33
34```
35$ gn gen out/Debug --args='target_os="android" target_cpu="arm"'
36```
37
38You can specify a directory of your own choice instead of `out/Debug`,
39to enable managing multiple configurations in parallel.
40
41* To build for ARM64: use `target_cpu="arm64"`
42* To build for 32-bit x86: use `target_cpu="x86"`
43* To build for 64-bit x64: use `target_cpu="x64"`
44
452. Compile using:
46
47```
48$ autoninja -C out/Debug
49```
50
51(To list all available targets, run `autoninja -C out/Debug -t targets all`.)
52
53
54## Using the Bundled Android SDK/NDK
55
56In order to use the Android SDK and NDK that is bundled in
57`third_party/android_tools`, run this to get it included in your `PATH` (from
58`src/`):
59
60```
61$ . build/android/envsetup.sh
62```
63
64Then you'll have `adb` and all the other Android tools in your `PATH`.
65
66
67## Running the AppRTCMobile App
68
69AppRTCMobile is an Android application using WebRTC Native APIs via JNI (JNI
70wrapper is documented [here][webrtc-jni-doc]).
71
72For instructions on how to build and run, see
73[examples/androidapp/README][apprtc-doc].
74
75
76## Using Android Studio
77
78*Note: This is known to be broken at the moment. See bug:
79https://bugs.webrtc.org/9282*
80
811. Build the project normally (out/Debug should be the directory you used when
82generating the build files using GN):
83
84```
85$ autoninja -C out/Debug AppRTCMobile
86```
87
882. Generate the project files:
89
90```
91$ build/android/gradle/generate_gradle.py --output-directory $PWD/out/Debug \
92  --target "//examples:AppRTCMobile" --use-gradle-process-resources \
93  --split-projects --canary
94```
95
963. *Import* the project in Android Studio. (Do not just open it.) The project
97is located in `out/Debug/gradle`. If asked which SDK to use, choose to use
98Android Studio's SDK. When asked whether to use the Gradle wrapper, press
99"OK".
100
1014. Ensure target `webrtc > examples > AppRTCMobile` is selected and press Run.
102AppRTCMobile should now start on the device.
103
104If you do any changes to the C++ code, you have to compile the project using
105autoninja after the changes (see step 1).
106
107*Note: Only "arm" is supported as the target_cpu when using Android Studio. This
108still allows you to run the application on 64-bit ARM devices. x86-based devices
109are not supported right now.*
110
111
112## Running Tests on an Android Device
113
114To build APKs with the WebRTC native tests, follow these instructions.
115
1161. Ensure you have an Android device set in Developer mode connected via USB.
117
1182. Compile unit tests and/or instrumentation tests:
119
120```
121$ autoninja -C out/Debug android_instrumentation_test_apk
122$ autoninja -C out/Debug rtc_unittests
123```
124
1253. You can find the generated test binaries in `out/Debug/bin`. To run instrumentation tests:
126
127```
128$ out/Debug/bin/run_android_instrumentation_test_apk -v
129```
130
131To run unit tests:
132
133```
134$ out/Debug/bin/run_rtc_unittests -v
135```
136
137Show verbose output with `-v` and filter tests with `--gtest-filter=SomeTest.*`. For example:
138
139```
140$ out/Debug/bin/run_android_instrumentation_test_apk -v \
141    --gtest_filter=VideoFrameBufferTest.*
142```
143
144For a full list of command line arguments, use `--help`.
145
1465. **NOTICE:** The first time you run a test, you must accept a dialog on
147the device!
148
149If want to run Release builds instead; pass `is_debug=false` to GN (and
150preferably generate the projects files into a directory like `out/Release`).
151Then use the scripts generated in `out/Release/bin` instead.
152
153[webrtc-prerequisite-sw]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/prerequisite-sw/index.md
154[webrtc-jni-doc]: https://webrtc.googlesource.com/src/+/master/sdk/android/README
155[apprtc-doc]: https://webrtc.googlesource.com/src/+/master/examples/androidapp/README
156[ninja]: https://ninja-build.org/
157[prebuilt-libraries]: https://bintray.com/google/webrtc/google-webrtc
158[webrtc-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/index.md
159