From 4ec0be17d595097102bdc03b8652c785aafdf8cb Mon Sep 17 00:00:00 2001 From: Julian-o Date: Tue, 5 Dec 2023 02:39:10 +1100 Subject: [PATCH 1/3] Make doc structure consistent and up-to-date This is part of an effort to make the Kivy sibling projects' documentation structure consistent and up-to-date. Unrelated fixes: * Documentation version number now fetched from `buildozer/__init__.py`. Addresses #1738 * Implemented many/all of the formatting changes from #1708. * Copy-edit of documents. * Contents of Contributing.rst moved to CONTRIBUTING.md * Removed installation intructions from README.md, so there is only one version. * Added Recipes description to RST documentation * Removed broken index page CHECKLIST * CONTRIBUTING.md [x] If repo takes user contributions, is present [x] In root dir (not .github dir) [x] Explains relationship to Kivy, if unclear. [x] Refers to kivy/kivy Contribution Guidelines. * LICENSE [X] If repo takes user contributions, is present. [X] Acknowledges the range of years to 2023. [X] Acknowledges Kivy Team and other contributors [X] Mentions it is an MIT License. * CODE_OF_CONDUCT.md [X] If repo takes user contributions or hosts discussions, is present. [X] Refers to kivy/kivy CODE_OF_CONDUCT.md * CONTACT.md [X] Refers to kivy/kivy CONTACT.md * FAQ.md [x] If repo is big enough for RST documentation, is present. * README: [x] Is a Markdown file. [x Describes the project. [x] Describes its place in the Kivy sibling projects. [x] If Documentation exists, mention it. [x] If CONTRIBUTING exists, mentions it. [x] If LICENSE exists, mentions it. [x] If CODE_OF_CONDUCT exists, mentions it. [x] Mentions kivy/kivy CONTACT.md [NA] Uses Python syntax colouring for embedded Python code. [x] Uses badges to display current status, including: [x] Backers [x] Sponsors [x] GitHub contributors [x] Contributor Covenant [x] PyPI Version [x] PyPI Python Version [x] Build/Test status [x] Displays all contributors to the repo. [x] Displays backers [x] Displays top sponsors. * RST documentation, if present [x] Describes the project. [x] Describes its place in the Kivy sibling projects. [x] Mentions (Kivy/Kivy) Contact Us link. [x] Mentions LICENSE. [x] Mentions CONTRIBUTING [x] Mentions FAQ [x] conf.py mentioned Kivy Team and other contributors - copyright, latex_documents, man_pages, texinfo documents * WORKFLOWS [x] NO_RESPONSE.yml is present if the repo has awaiting_reply tag. [x] NO_RESPONSE uses latest script versions. [x] SUPPORT.yml is present if the repo has a `support` tag. [x] SUPPORT.yml refers to repo's CONTACT.md * setup.py/cfg, if present and on PyPI [x] Supplies description to PyPI [x] Supplies Python versions to PyPI [x] Supplies Documentation, if any, to PyPI --- .github/workflows/support.yml | 2 +- CODE_OF_CONDUCT.md | 8 ++ CONTACT.md | 6 + CONTRIBUTING.md | 67 ++++++++++ FAQ.md | 31 +++++ README.md | 225 ++++++++++++++++++++-------------- docs/source/conf.py | 33 +++-- docs/source/contact.rst | 8 ++ docs/source/contribute.rst | 56 ++------- docs/source/faq.rst | 5 + docs/source/index.rst | 58 ++++----- docs/source/installation.rst | 76 +++++++----- docs/source/quickstart.rst | 9 +- docs/source/recipes.rst | 33 +++++ setup.py | 9 +- 15 files changed, 415 insertions(+), 211 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTACT.md create mode 100644 CONTRIBUTING.md create mode 100644 FAQ.md create mode 100644 docs/source/contact.rst create mode 100644 docs/source/faq.rst create mode 100644 docs/source/recipes.rst diff --git a/.github/workflows/support.yml b/.github/workflows/support.yml index 1b11c479a..ae5437298 100644 --- a/.github/workflows/support.yml +++ b/.github/workflows/support.yml @@ -16,7 +16,7 @@ jobs: action: runs-on: ubuntu-latest steps: - - uses: dessant/support-requests@v3 + - uses: dessant/support-requests@v4 with: github-token: ${{ github.token }} support-label: 'support' diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..29d18faa2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. + +Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md). + diff --git a/CONTACT.md b/CONTACT.md new file mode 100644 index 000000000..16dafa0c7 --- /dev/null +++ b/CONTACT.md @@ -0,0 +1,6 @@ +# Contacting the Kivy Team + +If you are looking to contact the Kivy Team (who are responsible for managing +the Buildozer project), including looking for support, please see our +latest [Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md) +document. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..7f452b345 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contribution Guidelines + +Buildozer is part of the [Kivy](https://kivy.org) ecosystem - a large group of +products used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. + +Contributions can come in many forms. See the latest +[Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md) +for general guidelines of how you can help us. + +--- + +If you would like to work on Buildozer, you can set up a development build: +```bash +git clone https://github.com/kivy/buildozer +cd buildozer +python setup.py build +pip install -e . +``` +--- + +Buildozer uses python-for-android, that is architected to be extensible with +new recipes and new bootstraps. + +If you do develop a new recipe on python-for-android, here is how to test it: + +#. Fork `Python for Android `_, and + clone your own version (this will allow easy contribution later):: + +```bash +git clone https://github.com/YOURNAME/python-for-android +``` + +#. Change your `buildozer.spec` to reference your version:: + + p4a.source_dir = /path/to/your/python-for-android + +#. Copy your recipe into `python-for-android/recipes/YOURLIB/recipe.sh` + +#. Rebuild. + +When your recipe works, you can ask us to +include it in the python-for-android project, by issuing a Pull Request: + +#. Create a branch:: + +```bash +git checkout --track -b recipe-YOURLIB origin/master +``` + +#. Add and commit:: + +```bash +git add python-for-android/recipes/YOURLIB/* +git commit -am 'Add support for YOURLIB` +``` + +#. Push to GitHub + +```bash +git push origin master +``` + +#. Go to `https://github.com/YOURNAME/python-for-android`, and you should see + your new branch and a button "Pull Request" on it. Use it, write a + description about what you did, and Send! \ No newline at end of file diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 000000000..7ec244ed6 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,31 @@ +# FAQ for Buildozer + +## Introduction + +Buildozer is a development tool for turning [Python](https://www.python.org/) +applications into binary packages ready for installation on any of a number of +platforms, including mobile devices. + +The app developer provides a single "buildozer.spec" file, which describes the +application's requirements and settings, such as title and icons. Buildozer can +then create installable packages for Android, iOS, Windows, macOS and/or Linux. + +Buildozer is managed by the [Kivy Team](https://kivy.org/about.html). It relies +on its sibling projects: +[python-for-android](https://github.com/kivy/python-for-android/) and +[Kivy for iOS](https://github.com/kivy/kivy-ios/). It has features to make +building apps using the [Kivy framework](https://github.com/kivy/kivy) easier, +but it can be used independently - even with other GUI frameworks. + +## How do I write my own recipes? + +Instructions on how to write your own recipes is available in the +[Kivy for iOS](https://github.com/kivy/kivy-ios/) and +[python-for-android documentation](https://python-for-android.readthedocs.io/en/latest/recipes/). + +Instructions on how to test your own recipes from Buildozer is available in the +[Buildozer Contribution Guidelines](CONTRIBUTING.md). + +> [!NOTE] +> This document is very short at the moment. Please contribute some FAQ +> questions and answers. diff --git a/README.md b/README.md index 9b74d5c24..3652febaa 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,59 @@ -Buildozer -========= +# Buildozer -[![Tests](https://github.com/kivy/buildozer/workflows/Tests/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3ATests) -[![Android](https://github.com/kivy/buildozer/workflows/Android/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3AAndroid) -[![iOS](https://github.com/kivy/buildozer/workflows/iOS/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3AiOS) -[![Coverage Status](https://coveralls.io/repos/github/kivy/buildozer/badge.svg)](https://coveralls.io/github/kivy/buildozer) -[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) -[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) +Buildozer is a development tool for turning [Python](https://www.python.org/) +applications into binary packages ready for installation on any of a number of +platforms, including mobile devices. -Buildozer is a tool for creating application packages easily. +The app developer provides a single "buildozer.spec" file, which describes the +application's requirements and settings, such as title and icons. Buildozer can +then create installable packages for Android, iOS, Windows, macOS and/or Linux. -The goal is to have one "buildozer.spec" file in your app directory, describing -your application requirements and settings such as title, icon, included modules -etc. Buildozer will use that spec to create a package for Android, iOS, Windows, -OSX and/or Linux. - -Buildozer currently supports packaging for Android via the [python-for-android](https://github.com/kivy/python-for-android/) -project, and for iOS via the kivy-ios project. iOS and OSX are still under work. +Buildozer is managed by the [Kivy Team](https://kivy.org/about.html). It relies +on its sibling projects: +[python-for-android](https://github.com/kivy/python-for-android/) and +[Kivy for iOS](https://github.com/kivy/kivy-ios/). It has features to make +building apps using the [Kivy framework](https://github.com/kivy/kivy) easier, +but it can be used independently - even with other GUI frameworks. For Android, buildozer will automatically download and prepare the build dependencies. For more information, see -[Android-SDK-NDK-Information](https://github.com/kivy/kivy/wiki/Android-SDK-NDK-Information). -Note that only Python 3 is supported. +[Android SDK NDK Information](https://github.com/kivy/kivy/wiki/Android-SDK-NDK-Information). -Note that this tool has nothing to do with the eponymous online build service -[buildozer.io](https://buildozer.io). +> [!NOTE] +> This tool is unrelated to the online build service, +> [buildozer.io](https://buildozer.io). -## Installing Buildozer with target Python 3 (default): +[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) +[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) +[![GitHub contributors](https://img.shields.io/github/contributors-anon/kivy/buildozer)](https://github.com/kivy/buildozer/graphs/contributors) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) -- Install buildozer: +![PyPI - Version](https://img.shields.io/pypi/v/buildozer) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/buildozer) + +[![Tests](https://github.com/kivy/buildozer/workflows/Tests/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3ATests) +[![Android](https://github.com/kivy/buildozer/workflows/Android/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3AAndroid) +[![iOS](https://github.com/kivy/buildozer/workflows/iOS/badge.svg)](https://github.com/kivy/buildozer/actions?query=workflow%3AiOS) +[![Coverage Status](https://coveralls.io/repos/github/kivy/buildozer/badge.svg)](https://coveralls.io/github/kivy/buildozer) - # via pip (latest stable, recommended) - # if you use a virtualenv, don't use the `--user` option - pip install --user buildozer - # latest dev version - # if you use a virtualenv, don't use the `--user` option - pip install --user https://github.com/kivy/buildozer/archive/master.zip +## Installation - # git clone, for working on buildozer - git clone https://github.com/kivy/buildozer - cd buildozer - python setup.py build - pip install -e . +Buildozer -- Check buildozer is in your path +## Installing Buildozer with target Python 3 (default): - `which buildozer` - # if there is no result, and you installed with --user, add this line at the end of your `~/.bashrc` file. - export PATH=~/.local/bin/:$PATH - # and then run - . ~/.bashrc +Buildozer incorporates a number of technologies, and has a complicated +dependencies, including platform dependencies outside of Python. -- Go into your application directory and run: +This means installation is more than a simple `pip install`; many of our support +requests are related to missing dependencies. - buildozer init - # edit the buildozer.spec, then - buildozer android debug deploy run +So, it is important to follow the instructions carefully. +Please see the +[Installation documentation](https://buildozer.readthedocs.io/en/latest/installation.html) +specific to this version. ## Buildozer Docker image @@ -65,17 +61,26 @@ A Dockerfile is available to use buildozer through a Docker environment. - Build with: - docker build --tag=buildozer . +```bash +docker build --tag=buildozer . +``` - Run with: - docker run --volume "$(pwd)":/home/user/hostcwd buildozer --version +```bash +docker run --volume "$(pwd)":/home/user/hostcwd buildozer --version +``` +> [!WARNING] +> [DockerHub](https://hub.docker.com/) contains an obsolete Docker image for +> Buildozer. It is deprecated. Build your own. ### Example Build with Caching - Build and keep downloaded SDK and NDK in `~/.buildozer` directory: - docker run -v $HOME/.buildozer:/home/user/.buildozer -v $(pwd):/home/user/hostcwd kivy/buildozer android debug +```bash +docker run -v $HOME/.buildozer:/home/user/.buildozer -v $(pwd):/home/user/hostcwd kivy/buildozer android debug +``` ## Buildozer GitHub action @@ -84,28 +89,12 @@ Use [ArtemSBulgakov/buildozer-action@v1](https://github.com/ArtemSBulgakov/build to build your packages automatically on push or pull request. See [full workflow example](https://github.com/ArtemSBulgakov/buildozer-action#full-workflow). - -## Examples of Buildozer commands - -``` -# buildozer target command -buildozer android clean -buildozer android update -buildozer android deploy -buildozer android debug -buildozer android release - -# or all in one (compile in debug, deploy on device) -buildozer android debug deploy - -# set the default command if nothing set -buildozer setdefault android debug deploy run -``` - +> [!WARNING] +> This GitHub action may use an obsolete version of Buildozer; use with caution. ## Usage -``` +```yml Usage: buildozer [--profile ] [--verbose] [target] ... buildozer --version @@ -143,78 +132,128 @@ Target "android" commands: to make an alias ``` +## Examples of Buildozer commands + +```bash +# buildozer target command +buildozer android clean +buildozer android update +buildozer android deploy +buildozer android debug +buildozer android release + +# or all in one (compile in debug, deploy on device) +buildozer android debug deploy + +# set the default command if nothing set +buildozer setdefault android debug deploy run +``` ## `buildozer.spec` -See [buildozer/default.spec](https://raw.github.com/kivy/buildozer/master/buildozer/default.spec) for an up-to-date spec file. +Run `buildozer init` to have a new `buildozer.spec` file copied into the current +working directory. Edit it before running your first build. +See [buildozer/default.spec](https://raw.github.com/kivy/buildozer/master/buildozer/default.spec) for the template. ## Default config -You can override the value of *any* `buildozer.spec` config token by +You can override the value of any `buildozer.spec` config token by setting an appropriate environment variable. These are all of the -form ``$SECTION_TOKEN``, where SECTION is the config file section and +form `$SECTION_TOKEN`, where SECTION is the config file section and TOKEN is the config token to override. Dots are replaced by underscores. For example, here are some config tokens from the [app] section of the config, along with the environment variables that would override them. -- ``title`` -> ``$APP_TITLE`` -- ``package.name`` -> ``$APP_PACKAGE_NAME`` -- ``p4a.source_dir`` -> ``$APP_P4A_SOURCE_DIR`` +- `title` -> `$APP_TITLE` +- `package.name` -> `$APP_PACKAGE_NAME` +- `p4a.source_dir` -> `$APP_P4A_SOURCE_DIR` -## Support +## License + +Buildozer is [MIT licensed](LICENSE), actively developed by a great +community and is supported by many projects managed by the +[Kivy Organization](https://www.kivy.org/about.html). -If you need help, please feel free to seek assistance through our support channels: +## Documentation -Join the [Kivy Users Google Group](https://groups.google.com/group/kivy-users). -Participate in discussions on [Discord](https://chat.kivy.org). +[Documentation for this repository](https://buildozer.readthedocs.io/). -Additionally, for troubleshooting Android-related issues, you can utilize ADB to obtain logs for your application. Detailed instructions can be found in the [debugging on Android](https://python-for-android.readthedocs.io/en/latest/troubleshooting/?highlight=adb#debugging-on-android) documentation. +## Support + +Are you having trouble using Buildozer or any of its related projects in the Kivy +ecosystem? +Is there an error you don’t understand? Are you trying to figure out how to use +it? We have volunteers who can help! +The best channels to contact us for support are listed in the latest +[Contact Us](https://github.com/kivy/buildozer/blob/master/CONTACT.md) document. ## Contributing -We love pull requests and discussing novel ideas. Check out our -[contribution guide](https://kivy.org/docs/contribute.html) and -feel free to improve buildozer. +Buildozer is part of the [Kivy](https://kivy.org) ecosystem - a large group of +products used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. -The following mailing list and IRC channel are used exclusively for -discussions about developing the Kivy framework and its sister projects: +Contributions can come in many forms. See the latest +[Contribution Guidelines](https://github.com/kivy/buildozer/blob/master/CONTRIBUTING.md) +for how you can help us. -* Dev Group : https://groups.google.com/group/kivy-dev -* Email : kivy-dev@googlegroups.com +## Code of Conduct -We also have a Discord channel: +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. -* Server : https://chat.kivy.org -* Channel : #dev +Please consult the [latest Code of Conduct](https://github.com/kivy/buildozer/blob/master/CODE_OF_CONDUCT.md). -## License +## Contributors -Buildozer is released under the terms of the MIT License. Please refer to the -LICENSE file. +This project exists thanks to +[all the people who contribute](https://github.com/kivy/buildozer/graphs/contributors). +[[Become a contributor](CONTRIBUTING.md)]. + ## Backers -Thank you to all our backers! πŸ™ [[Become a backer](https://opencollective.com/kivy#backer)] - - +Thank you to [all of our backers](https://opencollective.com/kivy)! +πŸ™ [[Become a backer](https://opencollective.com/kivy#backer)] + ## Sponsors -Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/kivy#sponsor)] +Special thanks to +[all of our sponsors, past and present](https://opencollective.com/kivy). +Support this project by +[[becoming a sponsor](https://opencollective.com/kivy#sponsor)]. +Here are our top current sponsors. Please click through to see their websites, +and support them as they support us. + + + + + + + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py index 0410a3c55..f7fb734a2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import os +import re # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -41,16 +42,30 @@ # General information about the project. project = u'Buildozer' -copyright = u'2014, Kivy\'s Developers' +copyright = u'2014-2023, Kivy Team and other contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # + +# Lookup the version from the Buildozer module, without installing it +# since readthedocs.org may have issue to install it. +# Read the version from the __init__.py file, without importing it. +def get_version(): + with open( + os.path.join(os.path.abspath("../.."), "buildozer", "__init__.py") + ) as fp: + for line in fp: + m = re.search(r'^\s*__version__\s*=\s*([\'"])([^\'"]+)\1\s*$', line) + if m: + return m.group(2) + + # The short X.Y version. -version = '0.11' +version = get_version() # The full version, including alpha/beta/rc tags. -release = '0.11' +release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -187,7 +202,7 @@ # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Buildozer.tex', u'Buildozer Documentation', - u'Kivy\'s Developers', 'manual'), + u'Kivy Team and other contributors', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -216,8 +231,8 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'buildozer', u'Buildozer Documentation', - [u'Kivy\'s Developers'], 1) + ('index', 'buildozer', 'Buildozer Documentation', + ['Kivy Team and other contributors'], 1) ] # If true, show URL addresses after external links. @@ -231,7 +246,9 @@ # dir menu entry, description, category) texinfo_documents = [ ('index', 'Buildozer', u'Buildozer Documentation', - u'Kivy\'s Developers', 'Buildozer', 'One line description of project.', + 'Kivy Team and other contributors', 'Buildozer', + 'Turns Python applications into binary packages ready for ' + 'installation on a number of platforms.', 'Miscellaneous'), ] diff --git a/docs/source/contact.rst b/docs/source/contact.rst new file mode 100644 index 000000000..f081a705c --- /dev/null +++ b/docs/source/contact.rst @@ -0,0 +1,8 @@ +.. _contact: + +Contact Us +========== + +If you are looking to contact the Kivy Team (who are responsible for managing the +Buildozer project), including looking for support, please see our +`latest contact details `_. \ No newline at end of file diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst index 0ce90ba44..ac420c92e 100644 --- a/docs/source/contribute.rst +++ b/docs/source/contribute.rst @@ -1,49 +1,13 @@ -Contribute -========== +.. _contribute: +Contribution Guidelines +======================= -Write your own recipe ---------------------- +Buildozer is part of the `Kivy `_ ecosystem - a large group of +products used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. -A recipe allows you to compile libraries / python extension for the mobile. -Most of the time, the default compilation instructions doesn't work for the -target, as ARM compiler / Android NDK introduce specificities that the library -you want doesn't handle correctly, and you'll need to patch. Also, because the -Android platform cannot load more than 64 inline dynamic libraries, we have a -mechanism to bundle all of them in one to ensure you'll not hit this -limitation. - -To test your own recipe via Buildozer, you need to: - -#. Fork `Python for Android `_, and - clone your own version (this will allow easy contribution later):: - - git clone https://github.com/YOURNAME/python-for-android - -#. Change your `buildozer.spec` to reference your version:: - - p4a.source_dir = /path/to/your/python-for-android - -#. Copy your recipe into `python-for-android/recipes/YOURLIB/recipe.sh` - -#. Rebuild. - -When you correctly get the compilation and your recipe works, you can ask us to -include it in the python-for-android project, by issuing a Pull Request: - -#. Create a branch:: - - git checkout --track -b recipe-YOURLIB origin/master - -#. Add and commit:: - - git add python-for-android/recipes/YOURLIB/* - git commit -am 'Add support for YOURLIB` - -#. Push to Github - - git push origin master - -#. Go to `https://github.com/YOURNAME/python-for-android`, and you should see - your new branch and a button "Pull Request" on it. Use it, write a - description about what you did, and Send! +Contributions can come in many forms. See the latest +`Contribution Guidelines `_ +for general guidelines of how you can help us. diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 000000000..e921782b0 --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,5 @@ +FAQ +=== + +Buildozer has an `online FAQ `_. It contains the answers to +questions that repeatedly come up. diff --git a/docs/source/index.rst b/docs/source/index.rst index 01c1b3104..8c173b7d8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,34 +1,38 @@ -.. Buildozer documentation master file, created by - sphinx-quickstart on Sun Apr 20 16:56:31 2014. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to Buildozer's documentation! ===================================== -Buildozer is a tool that aim to package mobiles application easily. It -automates the entire build process, download the prerequisites like -python-for-android, Android SDK, NDK, etc. +Buildozer is a development tool for turning Python +applications into binary packages ready for installation on any of a number of +platforms, including mobile devices. It automates the entire build process. + +The app developer provides a single "buildozer.spec" file, which describes the +application's requirements and settings, such as title and icons. Buildozer can +then create installable packages for Android, iOS, Windows, macOS and/or Linux. + +Buildozer has features to make +building apps using the `Kivy framework `_ easier, +but it can be used independently - even with other GUI frameworks. -Buildozer manages a file named `buildozer.spec` in your application directory, -describing your application requirements and settings such as title, icon, -included modules etc. It will use the specification file to create a package -for Android, iOS, and more. +.. note:: + python-for-android only runs on Linux or macOS. (On Windows, a Linux emulator is + required.) -Currently, Buildozer supports packaging for: + Kivy for iOS only runs on macOS. -- Android: via `Python for Android - `_. You must have a Linux or OSX - computer to be able to compile for Android. +Buildozer is managed by the `Kivy Team `_. It relies +on its sibling projects: +`python-for-android `_ for +Android packaging, and +`Kivy for iOS `_ for iOS packaging. -- iOS: via `Kivy iOS `_. You must have an OSX - computer to be able to compile for iOS. +Buildozer is released and distributed under the terms of the MIT license. You should have received a +copy of the MIT license alongside your distribution. Our +`latest license `_ +is also available. -- Supporting others platform is in the roadmap (such as .exe for Windows, .dmg - for OSX, etc.) -If you have any questions about Buildozer, please refer to the `Kivy's user -mailing list `_. +.. note:: + This tool is unrelated to the online build service, `buildozer.io `_. .. toctree:: :maxdepth: 2 @@ -36,12 +40,8 @@ mailing list `_. installation quickstart specifications + recipes + faq contribute - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + contact diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 2fb5b3a37..f5a7b00f4 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,12 +1,22 @@ - Installation ============ -Depending the platform you want to target, you might need a few dependencies installed. -Buildozer tries to give you hints and tries to install few things for +Buildozer is tested on Python 3.8 and above. +Depending the platform you want to target, you might need more tools installed. +Buildozer tries to give you hints or tries to install few things for you, but it doesn't cover every situation. -Buildozer is tested on Python 3.8 and above. +First, install the buildozer project. + +The most-recently released version can be installed with:: + + pip install --user --upgrade buildozer + +Add the `--user` option if you are not using a virtual environment (not recommended). + +If you would like to install the latest version still under development:: + + pip install https://github.com/kivy/buildozer/archive/master.zip Targeting Android @@ -15,10 +25,12 @@ Targeting Android Android on Ubuntu 20.04 and 22.04 (64bit) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -(Buildozer is expected to work in later versions of Ubuntu, but it is only regularly tested on the latest LTS version -of Ubuntu.) +.. note:: + Later versions of Ubunti are expected to work. However only the latest + `Long Term Support (LTS) release `_ + is regularly tested. -:: +Additional installation required to support Android:: sudo apt update sudo apt install -y git zip unzip openjdk-17-jdk python3-pip autoconf libtool pkg-config zlib1g-dev libncurses5-dev libncursesw5-dev libtinfo5 cmake libffi-dev libssl-dev automake @@ -26,7 +38,8 @@ of Ubuntu.) # add the following line at the end of your ~/.bashrc file export PATH=$PATH:~/.local/bin/ -If openjdk-17 is not compatible with other installed programs, for Buildozer the minimum compatible openjdk version is 11. +If `openjdk-17 `_ is not compatible with other installed programs, +for Buildozer the minimum compatible openjdk version is 11. Then install the buildozer project with:: @@ -36,37 +49,44 @@ Then install the buildozer project with:: Android on Windows 10 or 11 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To use buildozer in Windows you need first to enable Windows Subsystem for Linux (WSL) and install a Linux distribution: https://docs.microsoft.com/en-us/windows/wsl/install. - -These instructions were tested with WSL 1 and Ubuntu 18.04 LTS, and WSL2 with Ubuntu 20.04 and 22.04. +To use Buildozer on Windows, you need first to enable Windows Subsystem for Linux (WSL) and +`install a Linux distribution `_. -After installing WSL and Ubuntu on your Windows machine, open Ubuntu, run the commands listed in the previous section, and restart your WSL terminal to enable the path change. +These instructions were tested with WSL 1 and Ubuntu 18.04 LTS, and WSL2 with Ubuntu 20.04 and 22.04. -Install the buildozer project with:: +After installing WSL and Ubuntu on your Windows machine, open Ubuntu, run the commands listed in the previous section, +and restart your WSL terminal to enable the path change. - pip3 install --user --upgrade buildozer +Copy your Kivy project directory from the Windows partition to the WSL partition. -Copy your Kivy project directory from the Windows partition to the WSL partition, and follow the Quickstart Instructions. **Do not** change to the project directory on the Windows partition and build there, this may give unexpected and obscure fails. +.. warning:: + It is important to use the WSL partition. The Android SDK for Linux does not work on Windows' NTFS drives. + This will lead to obscure failures. -For debugging, WSL does not have direct access to USB. Copy the .apk file to the Windows partition and run ADB (Android Debug Bridge) from a Windows prompt. ADB is part of Android Studio, if you do not have this installed you can install just the platform tools which also contain ADB. +For debugging, WSL does not have direct access to USB. Copy the .apk file to the Windows partition and run ADB +(Android Debug Bridge) from a Windows prompt. ADB is part of Android Studio, if you do not have this installed +you can install just the platform tools which also contain ADB. -- Go to https://developer.android.com/studio/releases/platform-tools and click on "Download SDK Platform-Tools for Windows". +- Visit the `Android SDK Platform Tools `_ page, and + select "Download SDK Platform-Tools for Windows". -- Unzip the downloaded file to a new folder. For example, "C:\\platform-tools". +- Unzip the downloaded file to a new folder. For example, `C:\\platform-tools\\` Before Using Buildozer ~~~~~~~~~~~~~~~~~~~~~~ If you wish, clone your code to a new folder where the build process will run. -You don't need to create a virtualenv for your code requirements. But just add these requirements to a configuration file called buildozer.spec as you will see in the following sections. +You don't need to create a virtualenv for your code requirements. But just add these requirements to a configuration +file called `buildozer.spec` as you will see in the following sections. -Before running buildozer in your code folder, remember to go into the buildozer folder and activate the buildozer virtualenv. +Before running Buildozer in your code folder, remember to go into the Buildozer folder and activate the Buildozer +virtualenv. Android on macOS ~~~~~~~~~~~~~~~~ -:: +Additional installation required to support macOS:: python3 -m pip install --user --upgrade buildozer # the --user should be removed if you do this in a venv @@ -91,6 +111,8 @@ Buildozer didn't install a necessary package Then press "y" then enter to accept the license. +Alternatively, the Android SDK license can be automatically accepted - see `build.spec` for details. + python-for-android related errors """"""""""""""""""""""""""""""""" @@ -101,16 +123,14 @@ See the dedicated `p4a troubleshooting documentation Targeting IOS ------------- -Install XCode and command line tools (through the AppStore) - -Install homebrew (https://brew.sh) +Additional installation required to support iOS: -:: +* Install XCode and command line tools (through the AppStore) +* Install `Homebrew `_:: brew install pkg-config sdl2 sdl2_image sdl2_ttf sdl2_mixer gstreamer autoconf automake -Install Buildozer and its ios dependencies +* Install pip, virtualenv and Kivy for iOS:: -:: + python -m pip install --user --upgrade pip virtualenv kivy-ios - python3 -m pip install --user --upgrade buildozer[ios] diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 128b9fc8c..988a2748f 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -66,8 +66,8 @@ To see your running application's print() messages and python's error messages, buildozer -v android deploy run logcat | grep python -Run my application from Windows 10 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Run my application from Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Plug your Android device on a USB port. @@ -84,9 +84,8 @@ Run my application from Windows 10 buildozer -v android deploy run -It is important to notice that Windows ADB and Buildozer installed ADB must be the same version. To check the versions, open PowerShell and type: - -:: +It is important to notice that Windows ADB and Buildozer-installed ADB must be the same version. To check the versions, +open PowerShell and type:: cd C:\platform-tools\ .\adb.exe version diff --git a/docs/source/recipes.rst b/docs/source/recipes.rst new file mode 100644 index 000000000..de3054ce2 --- /dev/null +++ b/docs/source/recipes.rst @@ -0,0 +1,33 @@ +Recipes +======= + +Python apps may depend on third party packages and extensions. + +Most packages are written in pure Python, and Buildozer can generally used them +without any modification. + +However, some packages and Python extensions require modification to work on +mobile platforms. + +For example, for extensions and packages that depend on C or other programming +languages, the default compilation instructions may not work for the target; +The ARM compiler and Android NDK introduce special requirements that the library +may not handle correctly + +For such cases, a "recipe" is required. A recipe allows you to compile libraries +and Python extension for the mobile by patching them before use. + +python-for-android and Kivy for iOS come, batteries included, with a number of +recipes for the most popular packages. + +However, if you use a novel package - and there are no pure Python equivalents that +you can substitute in - you may need to write (or commission) your own recipe. We +would welcome your recipe as a contribution to the project to help the next developer +who wants to use the same library. + +More instructions on how to write your own recipes is available in the +`Kivy for iOS `_ and +`python-for-android documentation `_. + +Instructions on how to test your own recipes from Buildozer is available in the +`latest Buildozer Contribution Guidelines `_. diff --git a/setup.py b/setup.py index 928d7a16a..25f2bcc00 100644 --- a/setup.py +++ b/setup.py @@ -51,12 +51,19 @@ def find_version(*file_paths): setup( name='buildozer', version=find_version('buildozer', '__init__.py'), - description='Generic Python packager for Android / iOS and Desktop', + description='Turns Python applications into binary packages ready for ' + 'installation on a number of platforms.', long_description=readme + "\n\n" + changelog, long_description_content_type='text/markdown', author='Mathieu Virbel', author_email='mat@kivy.org', url='https://github.com/kivy/buildozer', + project_urls={ + 'Website': "https://kivy.org", + 'Documentation': "https://buildozer.readthedocs.io/en/stable/#", + 'Source': "https://github.com/kivy/buildozer", + 'Bug Reports': "https://github.com/kivy/buildozer/issues", + }, license='MIT', packages=[ 'buildozer', 'buildozer.targets', 'buildozer.libs', 'buildozer.scripts' From 7334a4d01fee0c643e83100a7d9edcb3c091f834 Mon Sep 17 00:00:00 2001 From: Julian-o Date: Tue, 5 Dec 2023 02:54:03 +1100 Subject: [PATCH 2/3] Buildozer.io is a broken link --- README.md | 2 +- docs/source/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3652febaa..2a2235809 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ build dependencies. For more information, see > [!NOTE] > This tool is unrelated to the online build service, -> [buildozer.io](https://buildozer.io). +> `buildozer.io`. [![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8c173b7d8..6c1b223f3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -32,7 +32,7 @@ is also available. .. note:: - This tool is unrelated to the online build service, `buildozer.io `_. + This tool is unrelated to the online build service, `buildozer.io`. .. toctree:: :maxdepth: 2 From f280123ddd8e1e22c7a4b8fbbb325564908a43f3 Mon Sep 17 00:00:00 2001 From: Julian Date: Tue, 5 Dec 2023 04:45:26 +1100 Subject: [PATCH 3/3] Update docs/source/installation.rst Co-authored-by: Mirko Galimberti --- docs/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index f5a7b00f4..8b1ad68da 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -26,7 +26,7 @@ Android on Ubuntu 20.04 and 22.04 (64bit) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: - Later versions of Ubunti are expected to work. However only the latest + Later versions of Ubuntu are expected to work. However only the latest `Long Term Support (LTS) release `_ is regularly tested.