Skip to content

gh-116622: Complete Android documentation #124259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AA-Turner merged 15 commits into from
Sep 23, 2024
Merged

gh-116622: Complete Android documentation #124259

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
8015ef4
Add Android to docs of unsupported features it shares with iOS
mhsmith Sep 19, 2024
2e08c09
Add additional markers for unsupported features on Android
mhsmith Sep 19, 2024
0f8c9da
Clarify emulator RAM size instructions
mhsmith Sep 19, 2024
879c805
Add Android platform guide
mhsmith Sep 19, 2024
98d7216
Update whatsnew and ACKS
mhsmith Sep 19, 2024
2c6ec29
Various fixes
mhsmith Sep 19, 2024
35384ab
Updates from code review.
freakboy3742 Sep 23, 2024
023598c
Correct markup
freakboy3742 Sep 23, 2024
9803d40
Merge branch 'main' into android-docs
freakboy3742 Sep 23, 2024
a5190e5
List more recommended Android tools
mhsmith Sep 23, 2024
e241163
Merge branch 'main' into android-docs
Yhg1s Sep 23, 2024
99e4c12
Apply suggestions from code review
mhsmith Sep 23, 2024
eabbf45
Improve formatting
mhsmith Sep 23, 2024
7fd73d1
Use consistent order in wasm-mobile-notavail.rst
mhsmith Sep 23, 2024
33efbf0
List Android under "Build Changes" in whatsnew
mhsmith Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Various fixes
  • Loading branch information
@mhsmith
mhsmith committed Sep 20, 2024
commit 2c6ec299622b75eedf3f60446e0385254748cbb4
5 changes: 2 additions & 3 deletions Android/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# 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. If you're looking to
use Python on Android, one of the following tools will provide a much more
approachable user experience:
Android yourself. Most users should *not* need to do this. Instead, use one of
the following tools, which will provide a much easier experience:

* [Briefcase](https://briefcase.readthedocs.io), from the BeeWare project
* [Buildozer](https://buildozer.readthedocs.io), from the Kivy project
Expand Down
5 changes: 2 additions & 3 deletions Doc/includes/wasm-mobile-notavail.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@

.. availability:: not WASI, not Android, not iOS.
Comment thread
mhsmith marked this conversation as resolved.
Outdated

This module does not work or is not available on WebAssembly or mobile
platforms. For more information, see :ref:`wasm-availability` and
:ref:`mobile-availability`.
This module is not supported on :ref:`WebAssembly platforms
<wasm-availability>` or :ref:`mobile platforms <mobile-availability>`.
7 changes: 3 additions & 4 deletions Doc/library/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,13 +127,12 @@ Mobile platforms

Android and iOS are, in most respects, POSIX operating systems. File I/O, socket handling,
and threading all behave as they would on any POSIX operating system. However,
there are several major differences.
there are several major differences:

* Mobile platforms can only use Python in "embedded" mode. There is no Python
REPL, and no ability to use separate executables such as :program:`python` or
:program:`pip`. To add Python code to your mobile app, you must use
the :ref:`Python embedding API <embedding>` to add a Python interpreter to an
app created with the platform's own build tools. For more details, see
the :ref:`Python embedding API <embedding>`. For more details, see
:ref:`using-android` and :ref:`using-ios`.

* Subprocesses:
Expand Down Expand Up @@ -172,5 +171,5 @@ there are several major differences.
keyboard, this is a software feature, not something that is attached to
``stdin``.

As a result, Python libraries that involve console manipulation (such as
As a result, Python modules that involve console manipulation (such as
:mod:`curses` and :mod:`readline`) are not available on mobile platforms.
17 changes: 8 additions & 9 deletions Doc/using/android.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,37 +28,36 @@ Adding Python to an Android app
-------------------------------

These instructions are only needed if you're planning to compile Python for
Android yourself. Most users should *not* need to do this. If you're looking to
use Python on Android, one of the following tools will provide a much more
approachable user experience:
Android yourself. Most users should *not* need to do this. Instead, use one of
the following tools, which will provide a much easier experience:

* `Briefcase <https://briefcase.readthedocs.io>`__, from the BeeWare project
* `Buildozer <https://buildozer.readthedocs.io>`__, from the Kivy project
* `Chaquopy <https://chaquo.com/chaquopy>`__
Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Sep 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are affiliated with this, right? I do not think there is a problem here, taking into account open-sourcing Chaquopy and your contribution in CPython.

Copy link
Copy Markdown
Contributor

@freakboy3742 freakboy3742 Sep 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct - Malcolm is the founder of Chaquopy.

Copy link
Copy Markdown
Member Author

@mhsmith mhsmith Sep 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've expanded this list to include all the production-quality Python-on-Android tools that I'm aware of.


If you're sure you want to do all this manually, read on. You can use the
If you're sure you want to do all of this manually, read on. You can use the
:source:`testbed app <Android/testbed>` as a guide; each step below contains a
link to the relevant file.

* Build Python by following the instructions in :source:`Android/README.md`.

* Add code to your :source:`build.gradle <Android/testbed/app/build.gradle.kts>`
file to copy the following items into your project. All except your own Python
code can be copied from ``cross-build/HOST/prefix/lib``.
code can be copied from ``cross-build/HOST/prefix/lib``:

* In your JNI libs:
Comment thread
mhsmith marked this conversation as resolved.
Outdated

* ``libpython*.*.so``
* ``lib*_python.so`` (external libraries such as OpenSSL)

* In your assets:

* ``python*.*`` (the Python standard library)
* ``python*.*/site-packages`` (your own Python code)

* Add code to your app to :source:`extract the assets to the filesystem
<Android/testbed/app/src/main/java/org/main/python/testbed/MainActivity.kt>`.
<Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt>`.

* Add code to your app to :source:`start Python in embedded mode
<Android/testbed/app/src/main/c/main_activity.c>`. This will need to be C code
called via JNI.