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