[3.13] gh-131531: Add android.py package command (GH-131532) (#131960)

Adds a `package` entry point to the `android.py` build script to support
creating an Android distribution artefact.
(cherry picked from commit fe5c4c5)

Co-authored-by: Malcolm Smith <[email protected]>

Author: miss-islington

Android/README.md

@@ -1,19 +1,22 @@
 # Python for Android
 
-These instructions are only needed if you're planning to compile Python for
-Android yourself. Most users should *not* need to do this. Instead, use one of
-the tools listed in `Doc/using/android.rst`, which will provide a much easier
-experience.
+If you obtained this README as part of a release package, then the only
+applicable sections are "Prerequisites", "Testing", and "Using in your own app".
 
+If you obtained this README as part of the CPython source tree, then you can
+also follow the other sections to compile Python for Android yourself.
+
+However, most app developers should not need to do any of these things manually.
+Instead, use one of the tools listed
+[here](https://docs.python.org/3/using/android.html), which will provide a much
+easier experience.
 
-## Prerequisites
 
-First, make sure you have all the usual tools and libraries needed to build
-Python for your development machine.
+## Prerequisites
 
-Second, you'll need an Android SDK. If you already have the SDK installed,
-export the `ANDROID_HOME` environment variable to point at its location.
-Otherwise, here's how to install it:
+If you already have an Android SDK installed, export the `ANDROID_HOME`
+environment variable to point at its location. Otherwise, here's how to install
+it:
 
 * Download the "Command line tools" from <https://developer.android.com/studio>.
 * Create a directory `android-sdk/cmdline-tools`, and unzip the command line
@@ -27,15 +30,16 @@ The `android.py` script also requires the following commands to be on the `PATH`
 * `curl`
 * `java` (or set the `JAVA_HOME` environment variable)
 * `tar`
-* `unzip`
 
 
 ## Building
 
 Python can be built for Android on any POSIX platform supported by the Android
-development tools, which currently means Linux or macOS. This involves doing a
-cross-build where you use a "build" Python (for your development machine) to
-help produce a "host" Python for Android.
+development tools, which currently means Linux or macOS.
+
+First we'll make a "build" Python (for your development machine), then use it to
+help produce a "host" Python for Android. So make sure you have all the usual
+tools and libraries needed to build Python for your development machine.
 
 The easiest way to do a build is to use the `android.py` script. You can either
 have it perform the entire build process from start to finish in one step, or
@@ -60,8 +64,8 @@ To do all steps in a single command, run:
 ./android.py build HOST
 ```
 
-In the end you should have a build Python in `cross-build/build`, and an Android
-build in `cross-build/HOST`.
+In the end you should have a build Python in `cross-build/build`, and a host
+Python in `cross-build/HOST`.
 
 You can use `--` as a separator for any of the `configure`-related commands –
 including `build` itself – to pass arguments to the underlying `configure`
@@ -73,14 +77,27 @@ call. For example, if you want a pydebug build that also caches the results from
 ```
 
 
+## Packaging
+
+After building an architecture as described in the section above, you can
+package it for release with this command:
+
+```sh
+./android.py package HOST
+```
+
+`HOST` is defined in the section above.
+
+This will generate a tarball in `cross-build/HOST/dist`, whose structure is
+similar to the `Android` directory of the CPython source tree.
+
+
 ## Testing
 
-The test suite can be run on Linux, macOS, or Windows:
+The Python test suite can be run on Linux, macOS, or Windows:
 
 * On Linux, the emulator needs access to the KVM virtualization interface, and
   a DISPLAY environment variable pointing at an X server.
-* On Windows, you won't be able to do the build on the same machine, so you'll
-  have to copy the `cross-build/HOST` directory from somewhere else.
 
 The test suite can usually be run on a device with 2 GB of RAM, but this is
 borderline, so you may need to increase it to 4 GB. As of Android
@@ -90,9 +107,16 @@ and find `hw.ramSize` in both config.ini and hardware-qemu.ini. Either set these
 manually to the same value, or use the Android Studio Device Manager, which will
 update both files.
 
-Before running the test suite, follow the instructions in the previous section
-to build the architecture you want to test. Then run the test script in one of
-the following modes:
+You can run the test suite either:
+
+* Within the CPython repository, after doing a build as described above. On
+  Windows, you won't be able to do the build on the same machine, so you'll have
+  to copy the `cross-build/HOST/prefix` directory from somewhere else.
+
+* Or by taking a release package built using the `package` command, extracting
+  it wherever you want, and using its own copy of `android.py`.
+
+The test script supports the following modes:
 
 * In `--connected` mode, it runs on a device or emulator you have already
   connected to the build machine. List the available devices with
@@ -133,4 +157,4 @@ until you re-run `android.py make-host` or `build`.
 
 ## Using in your own app
 
-See `Doc/using/android.rst`.
+See https://docs.python.org/3/using/android.html.