kivy-ios

The iOS application model does not support the standard Python multiprocessing or subprocess modules in a cross-platform compatible way due to iOS design constraints focused on power consumption.

If your application requires multiple processes, use PyObjus to leverage native iOS concurrency and functional APIs instead.

Once your recipes are built, use the toolchain to generate an Xcode project from your application directory.

1. Create the project: Run toolchain create <title> <app_directory>. Your app directory must contain a main.py file. This creates a directory named <title>-ios containing the Xcode project.
2. Open the project: Use open <title>-ios/<title>.xcodeproj.
3. Run the app: Click Play in Xcode.

Important: Every time you press Play in Xcode, your application directory is automatically synced to the <title>-ios/YourApp directory. Do not make changes directly inside the -ios directory; make changes in your original application directory.

toolchain create Touchtracer ~/code/kivy/examples/demo/touchtracer
open touchtracer-ios/touchtracer.xcodeproj

A recipe contains the instructions to compile a specific Python extension or C/C++ library for iOS. You must compile all dependencies (like python3 and kivy) before creating an Xcode project.

• List available recipes: toolchain recipes
• Build a single recipe: toolchain build <recipe_name>
• Build multiple recipes at once: toolchain build <recipe1> <recipe2> ...
• Remove a recipe build: toolchain clean <recipe_name>
• Install non-compiled packages: Use the pip command within the toolchain to install packages that don't require compilation into the distribution.

Example: Building Python, OpenSSL, and Kivy:

toolchain build python3 openssl kivy

toolchain build python3 kivy

To use Kivy for iOS, you must be on macOS with Xcode installed. It is strongly advised to use a Python virtual environment.

1. Create and activate a virtual environment:

   python3 -m venv venv
   . venv/bin/activate

2. Install the package via pip:

   pip3 install kivy-ios

3. Install system dependencies via Homebrew:

   brew install autoconf automake libtool pkg-config
   brew link libtool

4. Ensure Xcode command line tools are installed:

   xcode-select --install

After creating the Xcode project, you can customize the application:

• Icons and Launch Images: Set these within Xcode. Note that Xcode requires specific assets per device/iOS version.
• Launch Image Behavior: To prevent the launch image from disappearing immediately when SDL starts, place Default.png and Default-Landscape.png in the Resources folder in Xcode (not in your application folder).
• Environment and Startup: The main.m file created in your Xcode project folder controls application startup and environment variables. You can edit this file to customize the launch environment.
• Orientation: To restrict app orientation, use the export_orientation function in main.m. Ensure Xcode orientation settings are set to support all orientations.

To run this application on an Android device, copy the entire application directory to the following path on your device: /sdcard/kivy/pictures.

# Target path on Android device:
/sdcard/kivy/pictures

The Pictures app is a simple image browser. It is currently configured to only read images from the images/ directory within the application package. To view specific images, place your image files into the images/ directory before starting the app.

# Project structure requirement:
YourApp/
└── images/
    └── your_image.jpg

Bitcode is partially supported in kivy-ios. To enable it, set the Xcode build setting ENABLE_BITCODE to Yes.

Bitcode is currently supported for the following recipes:

• python3
• kivy
• sdl2
• sdl2_image
• sdl2_mixer
• libffi

If you encounter permission errors during execution, it is likely due to an architecture mismatch. Ensure your target device/simulator matches the architectures you have built. Common mismatches include:

• Targeting a simulator when you only have arm64 binaries.
• Targeting an iPad when you only have x86_64 binaries.

This error indicates that your Xcode path is not configured correctly. You must point xcode-select to your actual Xcode installation path (typically /Applications/Xcode.app).

sudo xcode-select --switch <YOUR_XCODEAPP_PATH>
# Example: sudo xcode-select --switch /Applications/Xcode.app

This error occurs when the Xcode Command Line Tools are not installed on your system. You can resolve this by installing them via the terminal.

xcode-select --install

To minimize the size of your distributed .ipa file, follow these steps:

1. Minimize Python modules: Edit the build/pythonX/lib/pythonXX.zip file to remove unused modules (e.g., encodings, xml, email).
2. Check Strip settings: In the settings panel > build, ensure all `