Differences

This shows you the differences between two versions of the page.

--- doc:appunti:prog:kivy_debian_12_android_11 [2023/10/04 17:56] – [Writing the buildozer.spec file] niccolo
+++ doc:appunti:prog:kivy_debian_12_android_11 [2025/11/16 18:08] (current) – [Writing the buildozer.spec file] niccolo
@@ Line 78: / Line 78: @@
 ==== Using the new venv install method ====
-FIXME Instead of disabling the externally-managed-environment flag or instead of using the pip3 ''%%--user%%'' install method, it should be possible to use the venv pip3 install method. You need to install the **python3-venv** Debian package. This recipe did not work for me, but should be investigated further:
+:!: **WARNING**: Till now we did not use this new preferred method, because the package **python-for-android** uses the old ''pip install'' method. See below about the //[[#installation_in_user_space|user method]]// install.
+Instead of disabling the externally-managed-environment flag or instead of using the pip3 ''%%--user%%'' install method, it should be possible to use the venv pip3 install method. You need to install the **python3-venv** Debian package. This recipe did not work for me, but should be investigated further:
 <code bash>
@@ Line 121: / Line 123: @@
 ==== Prepare the Kivy project in user space ====
+:!: **INFO**: This procedure is **required only once** when we start a new projec.
 Now it is time to prepare the Kivy project directory for the build of the Android package. You must check the following:
@@ Line 132: / Line 136: @@
 <code>
+mkdir openolyimageshare
 cd openolyimageshare
 buildozer init
@@ Line 181: / Line 186: @@
 You can use **presplash.filename** and **icon.filename** to include two artwork in your app. The //presplash// will be displayed at startup, during the initialization of the environment (unfortunately it is rather time consuming). The //icon// is instead what you can imagine. Use PNG graphics at least 512 x 512 pixels, you can use transparency too.
-In **android.permissions** you must list all the permissions that your app will require from the operating system. If you forget to declare something your app simply will not be able to do that operation. Beware that starting from Android 10 the access to the external storae (basically the space into the SD card or into the device memory) has undergone a drastic change, see the table below for a basic overview.
+In **android.permissions** you must list all the permissions that your app will require from the operating system. If you forget to declare something your app simply will not be able to do that operation. Beware that starting from Android 10 the access to the external storage (basically the space into the SD card or into the device memory) has undergone a drastic change, see the table below for a basic overview.
-^ READ_EXTERNAL_STORAGE   | This was the long-established permission required by the apps to read the [[https://android.googlesource.com/platform/docs/source.android.com/+/android-4.2.1_r1.1/src/tech/storage/index.md|external storage]] (a permissionless filesystem residing into the SD card or into a dedicated partition of the device internal storage). This is not longer true starting from **Android 10** (API level 29) which introduced the **scoped storage**, designed to protect app and user data and reduce file clutter; requesting ''READ_EXTERNAL_STORAGE'' in Android 10 actually means requesting access only to **photos and media**. Afterwards **Android 11** (API level 30) fixed several problems with that implementation; in Android 11 and above requesting ''READ_EXTERNAL_STORAGE'' does not give you any actual permission. Generally, in Android 11, an app cannot access the root directory of the SD card and the Download directory, it can access only its ASD (App Specific Directory).  |
+^ READ_EXTERNAL_STORAGE   | This was the long-established permission required by the apps to read the [[https://android.googlesource.com/platform/docs/source.android.com/+/android-4.2.1_r1.1/src/tech/storage/index.md|external storage]] (a permissionless filesystem residing into the SD card or into a dedicated partition of the device internal storage). If you want e.g. to read the pictures from the DCIM folder of an **Android 8** device, you must grant this permission. This is not longer true starting from **Android 10** (API level 29) which introduced the **scoped storage**, designed to protect app and user data and reduce file clutter; requesting ''READ_EXTERNAL_STORAGE'' in Android 10 actually means requesting access only to **photos and media**. Afterwards **Android 11** (API level 30) fixed several problems with that implementation; in Android 11 and above requesting ''READ_EXTERNAL_STORAGE'' does not give you any actual permission. Generally, in Android 11, an app cannot access the root directory of the SD card and the Download directory, it can access only its ASD (App Specific Directory).  |
 ^ WRITE_EXTERNAL_STORAGE  | The same as ''READ_EXTERNAL_STORAGE'', but for write permission.  |
-^ CAMERA                  | With this permission an app can use the external storage even with Android 10 and above, but limited to the shared folders like **Pictures**, **DCIM**, etc. FIXME Check if this is true! May be accessing a ''DCIM/SUBFOLDER/'' is always granted if files are .jpg or similar media files.  |
+^ CAMERA                  | Writing .jpg or similar media files under the Android shared folders **DCIM** or **Pictures** (or subfolders therein), is always permitted; no particular permission is required even in Android 11. Requesting the CAMERA permission allow to use the camera itself, the flash, etc.  |
 ^ MANAGE_EXTERNAL_STORAGE  | Starting from Android 11, this is the permission required to access all the files into the storage. The app should also provide an ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION intent. App requesting this permission may have trouble getting into the Google Play Store.  |
@@ Line 203: / Line 208: @@
 </file>
-By setting a **target API** lower than your SDK can support, you can declare what will be the highest Android version that your app is designed to be compatible with. At the moment Buildozer will try to target API 31 (Android 12).
+By setting a **target API** lower than your SDK can support, you can declare what will be the highest Android version that your app is designed to be compatible with. In November 2025 the Google Play Store requires the SDK target 35 (Android 15).
-Declaring a **minimum API** you can tell what is the minimum Android version required by your app.
+Declaring a **minimum API** you can tell what is the minimum Android version required by your app. We did not declared the android.minapi, so Buildozer choosed API 21 (**Android 5.0.2**).
-The **compile SDK** is the environment you want to use to create the app, i.e. the SDK you downloaded from Google (which generally support the higher API available at the moment). This will affects what functions and constructs you can use in your program. If you do not specify a version, Buildozer should detect the highest SDK downloaded and use it. In our case only one SDK was downloaded, and it was SDK API 31.
+The **compile SDK** is the environment you want to use to create the app, i.e. the SDK you downloaded from Google (which generally support the higher API available at the moment). This will affects what functions and constructs you can use in your program. If you do not specify a version, Buildozer should detect the highest SDK downloaded and use it.
-==== Compiling the package ====
+The Android API supported by your Buildozer installation depends upon the version of **python-for-android** (**p4a**) downloaded and installed during your setup. To know what is the **target API supported by your Buildozer installation**, check the messages log during a build, you will find a line like this:
+<code>
+[INFO]:    Available Android APIs are (31, 34)
+</code>
+To know what is the **Android SDK versions available**, look into the directory downloaded during the Buildozer installation:
+<code>
+ls $HOME/.buildozer/android/platform/android-sdk/platforms/
+android-31  android-34
+</code>
+^ Android Version  ^ API  ^
+| Android 15       |  35 |
+| Android 14       |  34 |
+| Android 13       |  33 |
+| Android 12L      |  32 |
+| Android 12       |  31 |
+| Android 11       |  30 |
+| Android 10       |  29 |
+| Android 9        |  28 |
+| Android 8.1      |  27 |
+| Android 8.0      |  26 |
+| Android 7.1      |  25 |
+| Android 7.0      |  24 |
+| Android 6.0      |  23 |
+| Android 5.1      |  22 |
+| Android 5.0      |  21 |
+==== Compiling the package (debug or release) ====
+:!: **INFO**: This is **the only procedure** to be executed whenever you want to compile a new version; the **version number** must be updated into the **main.py** source code.
+Enter the project directory and edit the **main.py** source code updating the definition of the **%%__version__%%** variable (the **buildozer.spec** will refer this value to create the package name). Then choose to make a debug build:
 <code>
-# Choose debug or release build:
 buildozer android debug
-#buildozer android release
 </code>
+During this step the directory **$HOME/project-name/.buildozer/** will be populated by files and directories in the order of 3-4 Gb,
+The package will be created into the **bin/** subdirectory, using a name like **packagename-version-arm64-v8a_armeabi-v7a-debug.apk**.
+When you are ready to **publish** your package, you must create the //release// binary:
+<code>
+buildozer android release
+</code>
+In this case the package created into the **bin/** subdirectory will be named like **packagename-version-arm64-v8a_armeabi-v7a-release.aab**, which is not directly installable into the device.
+===== Upgrading the build tools (Android SDK) =====
+As per November 2025, the **Google Play** requires that new packages uploaded to the store are compiled using the **SDK target 35**, this means that you have to declare ''android.api = 35'' in **buildozer.spec** file and that you have downloaded the relative Android SDK.
+To check **Buildozer version** installed:
+<code>
+buildozer --version
+pip3 install --user --upgrade buildozer
+</code>
+To check the **python-for-android (p4a) version** installed by your Buildozer setup, enter the ''.buildozer'' subdirectory of your project:
+<code>
+cd $HOME/openolyimageshare/.buildozer/android/platform/python-for-android
+</code>
+and check the **pythonforandroid** Pyton module version:
+<code>
+python3
+Python 3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import pythonforandroid
+>>> print(pythonforandroid.__version__)
+.01.21
+</code>
+Update the the **Android dependencies** inside the project subdirectory **$HOME/openolyimageshare/buildozer/android/platform/python-for-android**:
+<code>
+cd $HOME/openolyimageshare/
+vi buildozer.spec
+# In the spec file set e.g. android.api = 35
+buildozer android update
+buildozer android clean
+</code>
+The above command **does not update Buildozer** nor **python-for-android**, but it downloads the **new Android SDK/API** into your **$HOME/.buildozer/** hierarchy (not into the project directory).
+Once you recompiled the app, look into the project **$HOME/openolyimageshare/** for the file **.buildozer/android/platform/build-.../dists/openolyimageshare/AndroidManifest.xml** and verify that it has:
+<code xml>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="35" />
+</manifest>
+</code>
+If the **targetSdkVersion** did not upgrade as expected, verify you issued the command
+<code>
+buildozer android clean
+</code>
+Other generally unnecessary cleaning commands are:
+<code>
+buildozer android clean_dists
+buildozer android clean_builds
+buildozer android clean_apk
+rm -rf .buildozer/
+</code>
 ===== Web Resources =====
@@ Line 237: / Line 350: @@
   * **[[https://community.appinventor.mit.edu/t/how-to-access-non-media-media-files-on-android-11/54828|How to access non-media & media files on Android 11+]]**
   * **[[https://community.appinventor.mit.edu/t/asd-app-specific-directory-vs-private-folder/19154|ASD (app specific directory) vs Private folder]]**
+  * **[[https://developer.android.com/training/data-storage/shared/media|Access media files from shared storage]]**