Migrating from kivy-ios version 2023.08.24 to 2024.03.17

[misl6]

Introduction

With the release of kivy-ios version 2024.03.17, the project has embarked on a new direction for artifacts format (libname.a --> libname.xcframework). This change aims to better accommodate additional platforms, such as ARM64 Simulator, empowering developers who utilize Apple Silicon during their everyday work to leverage the extra boost.

Moreover, this transition will facilitate support for future platforms like VisionOS and other Apple platforms that may emerge down the line.

However, if you already have a project created with a version equal to or prior to 2023.08.24, you will need to migrate your project to the new format, and this guide will assist you in doing so.

For new projects, the toolchain create command generates projects in the new format, eliminating the need for migration concerns.

Preparing for Migration

⚠️ Before starting the migration, ensure to have a backup of your project.

Step 1: Install the Latest Version of kivy-ios

Ensure you have the latest version of kivy-ios installed. Execute the following command:

pip install -U kivy-ios

⚠️ If using a virtual environment, activate it before running the command.

Step 2: Clean Previous Builds

Navigate to the directory where you typically build your project (the one containing dist, build, and .cache folders) and execute the following command:

toolchain distclean

This command will delete the dist, build, and .cache folders, ensuring that the subsequent build starts from scratch.

Step 3: Rebuild from Scratch and Add Extra Dependencies

Rebuild your project from scratch using the following command:

toolchain build python3 kivy <any-other-recipe>

Additionally, if you have any non-plain-python dependencies, re-add them to your project with:

toolchain pip install <any-other-dependency>

Migrating the Project

Step 1: Remove Old Artifacts and System Frameworks Links

In Xcode, open your project and remove all kivy-ios managed references under the "Frameworks" folder.

Refer to the example below:

Step 2: Remove "EXCLUDED_ARCHS[sdk=iphonesimulator*]" = arm64; from Build Settings

Navigate to the Build Settings tab, locate EXCLUDED_ARCHS, and remove arm64 from EXCLUDED_ARCHS[sdk=iphonesimulator*].

Refer to the example below (before and after):

Step 3: Set ONLY_ACTIVE_ARCH to YES for the Debug Configuration

In the Build Settings tab, set ONLY_ACTIVE_ARCH to YES for the Debug configuration.

Refer to the example below:

Step 5: Update the Site-Packages Path in main.m

In Xcode, open the main.m file and update all references to the old Python version to the new one.

For example, if previously using Python 3.10, update the following line:

NSString *python_path = [NSString stringWithFormat:@"PYTHONPATH=%@:%@/lib/python3.10/:%@/lib/python3.10/site-packages:.", resourcePath, resourcePath, resourcePath, nil];

to:

NSString *python_path = [NSString stringWithFormat:@"PYTHONPATH=%@:%@/lib/python3.11/:%@/lib/python3.11/site-packages:.", resourcePath, resourcePath, resourcePath, nil];

Step 6: Update Include Paths in "Build Settings" to the New Python Version

In the Build Settings tab, update Header Search Paths to reflect the new Python version (3.11)

Refer to the image below for guidance.

Step 7: Update Library and Frameworks Search Paths in "Build Settings"

In the Build Settings tab, delete any old references in Library Search Paths and Framework Search Paths.

Refer to the images below for guidance.

Step 8: Add the New Artifacts to Your Project

You can add the new artifacts to your project by executing the following command:

toolchain update name-of-your-project

Step 9: Rebuild Your Project and Enjoy the Updated Apps

Finally, rebuild your project to enjoy the updated apps.