Debian Codegraph @

Android/README.md

raw
1 # Python for Android
2
3 If you obtained this README as part of a release package, then the only
4 applicable sections are "Prerequisites", "Testing", and "Using in your own app".
5
6 If you obtained this README as part of the CPython source tree, then you can
7 also follow the other sections to compile Python for Android yourself.
8
9 However, most app developers should not need to do any of these things manually.
10 Instead, use one of the tools listed
11 [here](https://docs.python.org/3/using/android.html), which will provide a much
12 easier experience.
13
14
15 ## Prerequisites
16
17 If you already have an Android SDK installed, export the `ANDROID_HOME`
18 environment variable to point at its location. Otherwise, here's how to install
19 it:
20
21 * Download the "Command line tools" from <https://developer.android.com/studio>.
22 * Create a directory `android-sdk/cmdline-tools`, and unzip the command line
23 tools package into it.
24 * Rename `android-sdk/cmdline-tools/cmdline-tools` to
25 `android-sdk/cmdline-tools/latest`.
26 * `export ANDROID_HOME=/path/to/android-sdk`
27
28 The `android.py` script will automatically use the SDK's `sdkmanager` to install
29 any packages it needs.
30
31 The script also requires the following commands to be on the `PATH`:
32
33 * `curl`
34 * `java` (or set the `JAVA_HOME` environment variable).
35 Java versions 17, 21 and 25 are supported.
36
37
38 ## Building
39
40 Python can be built for Android on any POSIX platform supported by the Android
41 development tools, which currently means Linux or macOS.
42
43 First we'll make a "build" Python (for your development machine), then use it to
44 help produce a "host" Python for Android. So make sure you have all the usual
45 tools and libraries needed to build Python for your development machine.
46
47 The easiest way to do a build is to use the `android.py` script. You can either
48 have it perform the entire build process from start to finish in one step, or
49 you can do it in discrete steps that mirror running `configure` and `make` for
50 each of the two builds of Python you end up producing.
51
52 The discrete steps for building via `android.py` are:
53
54 ```sh
55 ./android.py configure-build
56 ./android.py make-build
57 ./android.py configure-host HOST
58 ./android.py make-host HOST
59 ```
60
61 `HOST` identifies which architecture to build. To see the possible values, run
62 `./android.py configure-host --help`.
63
64 To do all steps in a single command, run:
65
66 ```sh
67 ./android.py build HOST
68 ```
69
70 In the end you should have a build Python in `cross-build/build`, and a host
71 Python in `cross-build/HOST`.
72
73 You can use `--` as a separator for any of the `configure`-related commands –
74 including `build` itself – to pass arguments to the underlying `configure`
75 call. For example, if you want a pydebug build that also caches the results from
76 `configure`, you can do:
77
78 ```sh
79 ./android.py build HOST -- -C --with-pydebug
80 ```
81
82
83 ## Packaging
84
85 After building an architecture as described in the section above, you can
86 package it for release with this command:
87
88 ```sh
89 ./android.py package HOST
90 ```
91
92 `HOST` is defined in the section above.
93
94 This will generate a tarball in `cross-build/HOST/dist`, whose structure is
95 similar to the `Android` directory of the CPython source tree.
96
97
98 ## Testing
99
100 The Python test suite can be run on Linux, macOS, or Windows.
101
102 On Linux, the emulator needs access to the KVM virtualization interface. This may
103 require adding your user to a group, or changing your udev rules. On GitHub
104 Actions, the test script will do this automatically using the commands shown
105 [here](https://github.blog/changelog/2024-04-02-github-actions-hardware-accelerated-android-virtualization-now-available/).
106
107 You can run the test suite either:
108
109 * Within the CPython repository, after doing a build as described above. On
110 Windows, you won't be able to do the build on the same machine, so you'll have
111 to copy the `cross-build/HOST/prefix` directory from somewhere else.
112
113 * Or by taking a release package built using the `package` command, extracting
114 it wherever you want, and using its own copy of `android.py`.
115
116 The test script supports the following modes:
117
118 * In `--connected` mode, it runs on a device or emulator you have already
119 connected to the build machine. List the available devices with
120 `$ANDROID_HOME/platform-tools/adb devices -l`, then pass a device ID to the
121 script like this:
122
123 ```sh
124 ./android.py test --connected emulator-5554
125 ```
126
127 * In `--managed` mode, it uses a temporary headless emulator defined in the
128 `managedDevices` section of testbed/app/build.gradle.kts. This mode is slower,
129 but more reproducible.
130
131 We currently define two devices: `minVersion` and `maxVersion`, corresponding
132 to our minimum and maximum supported Android versions. For example:
133
134 ```sh
135 ./android.py test --managed maxVersion
136 ```
137
138 By default, the only messages the script will show are Python's own stdout and
139 stderr. Add the `-v` option to also show Gradle output, and non-Python logcat
140 messages.
141
142 Any other arguments on the `android.py test` command line will be passed through
143 to `python -m test` – use `--` to separate them from android.py's own options.
144 See the [Python Developer's
145 Guide](https://devguide.python.org/testing/run-write-tests/) for common options
146 – most of them will work on Android, except for those that involve subprocesses,
147 such as `-j`.
148
149 Every time you run `android.py test`, changes in pure-Python files in the
150 repository's `Lib` directory will be picked up immediately. Changes in C files,
151 and architecture-specific files such as sysconfigdata, will not take effect
152 until you re-run `android.py make-host` or `build`.
153
154 The testbed app can also be used to test third-party packages. For more details,
155 run `android.py test --help`, paying attention to the options `--site-packages`,
156 `--cwd`, `-c` and `-m`.
157
158
159 ## Using in your own app
160
161 See https://docs.python.org/3/using/android.html.