| 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. |