xref: /aosp_15_r20/external/sl4a/README.md (revision 456ef56af69dcf0481dd36cc45216c4002d72fa3)
1*456ef56aSSadaf EbrahimiScripting Layer For Android
2*456ef56aSSadaf Ebrahimi=============================
3*456ef56aSSadaf Ebrahimi
4*456ef56aSSadaf Ebrahimi### Introduction
5*456ef56aSSadaf EbrahimiOriginally authored by Damon Kohler, Scripting Layer for Android, SL4A, is an automation toolset
6*456ef56aSSadaf Ebrahimifor calling Android APIs in a platform-independent manner. It supports both remote automation via
7*456ef56aSSadaf EbrahimiADB as well as execution of scripts from on-device via a series of lightweight translation layers.
8*456ef56aSSadaf Ebrahimi
9*456ef56aSSadaf Ebrahimi### Build Instructions
10*456ef56aSSadaf EbrahimiDue to its inclusion in AOSP as a privileged app, building SL4A requires a system build.
11*456ef56aSSadaf Ebrahimi
12*456ef56aSSadaf EbrahimiFor the initial build of Android:
13*456ef56aSSadaf Ebrahimi
14*456ef56aSSadaf Ebrahimi    cd <ANDROID_SOURCE_ROOT>
15*456ef56aSSadaf Ebrahimi    source build/envsetup.sh
16*456ef56aSSadaf Ebrahimi    lunch aosp_<TARGET>
17*456ef56aSSadaf Ebrahimi    make [-j15]
18*456ef56aSSadaf Ebrahimi
19*456ef56aSSadaf Ebrahimi*where `<ANDROID_SOURCE_ROOT>` is the root directory of the android tree and `<TARGET>` is the lunch
20*456ef56aSSadaf Ebrahimitarget name*
21*456ef56aSSadaf Ebrahimi
22*456ef56aSSadaf EbrahimiThen Build SL4A:
23*456ef56aSSadaf Ebrahimi
24*456ef56aSSadaf Ebrahimi    cd <ANDROID_SOURCE_ROOT>/external/sl4a
25*456ef56aSSadaf Ebrahimi    mm [-j15]
26*456ef56aSSadaf Ebrahimi
27*456ef56aSSadaf Ebrahimi### Adding SL4A Builds to Android Builds by Default
28*456ef56aSSadaf Ebrahimi1) If you are not using a custom buildspec, create one as follows:
29*456ef56aSSadaf Ebrahimi
30*456ef56aSSadaf Ebrahimi        cp <ANDROID_SOURCE_ROOT>/build/buildspec.mk.default <ANDROID_SOURCE_ROOT>/buildspec.mk
31*456ef56aSSadaf Ebrahimi
32*456ef56aSSadaf Ebrahimi2) Modify the buildspec to build SL4A as a custom module by editing
33*456ef56aSSadaf Ebrahimi    the line '#CUSTOM_MODULES:=' to 'CUSTOM_MODULES:=sl4a':
34*456ef56aSSadaf Ebrahimi
35*456ef56aSSadaf Ebrahimi        sed -i 's/#CUSTOM_MODULES:=/CUSTOM_MODULES:=sl4a/' <ANDROID_SOURCE_ROOT>/buildspec.mk
36*456ef56aSSadaf Ebrahimi
37*456ef56aSSadaf Ebrahimi### Install Instructions
38*456ef56aSSadaf EbrahimiRun the following command:
39*456ef56aSSadaf Ebrahimi
40*456ef56aSSadaf Ebrahimi    adb install -r <ANDROID_SOURCE_ROOT>/out/target/product/<TARGET>/testcases/sl4a/arm64/sl4a.apk
41*456ef56aSSadaf Ebrahimi
42*456ef56aSSadaf Ebrahimi### Run Instructions
43*456ef56aSSadaf Ebrahimia) SL4A may be launched from Android as a normal App; or
44*456ef56aSSadaf Ebrahimib) To enable RPC access from the command prompt:
45*456ef56aSSadaf Ebrahimi
46*456ef56aSSadaf Ebrahimi    adb forward tcp:<HOST_PORT_NUM> tcp:<DEVICE_PORT_NUM>
47*456ef56aSSadaf Ebrahimi    adb shell "am start -a com.googlecode.android_scripting.action.LAUNCH_SERVER \
48*456ef56aSSadaf Ebrahimi               --ei com.googlecode.android_scripting.extra.USE_SERVICE_PORT <DEVICE_PORT_NUM> \
49*456ef56aSSadaf Ebrahimi               com.googlecode.android_scripting/.activity.ScriptingLayerServiceLauncher"
50*456ef56aSSadaf Ebrahimi*where `<HOST_PORT_NUM>` and `<DEVICE_PORT_NUM>` are the tcp ports on the host computer and device.*
51*456ef56aSSadaf Ebrahimi
52*456ef56aSSadaf Ebrahimi### Generate the API Documentation
53*456ef56aSSadaf EbrahimiFrom SL4A source directory run this command:
54*456ef56aSSadaf Ebrahimi
55*456ef56aSSadaf Ebrahimi        python Docs/generate_api_reference_md.py
56*456ef56aSSadaf Ebrahimi
57*456ef56aSSadaf EbrahimiIn the Docs directory there should now be an ApiReference.md file that
58*456ef56aSSadaf Ebrahimicontains which RPC functions are available in SL4A as well as documentation
59*456ef56aSSadaf Ebrahimifor the RPC functions.
60*456ef56aSSadaf Ebrahimi
61