Skip to content

Add support for Android/iOS wheels#135

Merged
hajimes merged 23 commits intomasterfrom
feature/mobile-os
Jul 28, 2025
Merged

Add support for Android/iOS wheels#135
hajimes merged 23 commits intomasterfrom
feature/mobile-os

Conversation

@hajimes
Copy link
Copy Markdown
Owner

@hajimes hajimes commented Jul 28, 2025

This PR adds support for Android / iOS wheels, thanks to the excellent updates of cibuildwheel 3.0.0 and 3.1.0 (specifically, PR #2349 for Android and PR #2286 for iOS).

Updating the GitHub Actions workflow to accommodate these platforms was a bit challenging, so I'm sharing my experience here. I hope it may help other engineers in the future, when they face similar issues. My own code is available at https://github.com/hajimes/mmh3/blob/master/.github/workflows/wheels.yml.

  1. Start with the official documentation
    See the cibuildwheel platforms and options guides:

    Also, consult their YAML example:

  2. Explicitly declare platform (usually in the build matrix)
    For standard platforms (linux, windows, macos), cibuildwheel infers this automatically from runner's OS. But for android and ios, you must declare it manually. Then, set CIBW_PLATFORM: ${{ matrix.platform || 'auto' }} to ensure proper platform selection. This instructs cibuildwheel to use the platform value specified in the build matrix when available; otherwise, it falls back to the runner's OS.

  3. Configure Android/iOS-specific environment variables for testing
    For example, if using pytest and your tests are under ./tests, define:

    CIBW_TEST_SOURCES_ANDROID: "./tests"
    CIBW_TEST_SOURCES_IOS: "./tests"
    CIBW_TEST_COMMAND_ANDROID: "python -m pytest ./tests"
    CIBW_TEST_COMMAND_IOS: "python -m pytest ./tests"

    Standard platforms usually use pytest {project} as the testing command with cibuildwheel. However, Android/iOS builds cannot resolve the {project} placeholder, so explicit paths are required. Also note: CIBW_TEST_SOURCES_* must be defined, even if test file paths are stated within CIBW_TEST_COMMAND_*.

  4. For Android-Intel builds (that is, *-android_x86_64), use a Linux runner (e.g., ubuntu-latest) and enable the kernel-based virtual machine (KVM) for testing.
    If you don't specify this, testing will fail (as of cibuildwheel 3.1.1). You can just copy and paste the code from https://github.blog/changelog/2024-04-02-github-actions-hardware-accelerated-android-virtualization-now-available/. Also, see https://github.com/pypa/cibuildwheel/blob/v3.1.1/examples/github-deploy.yml#L55-L61 for the real-world example.

  5. For Android-ARM builds (that is, *-android_arm64_v8a), the canonical approach is to use an Apple Silicon runner (e.g., macos-latest) and skip testing.
    As of cibuildwheel 3.1.1, macOS runners on GitHub Actions do not support testing under Android emulation. Therefore, you must explicitly skip tests using CIBW_TEST_SKIP: "*-android_arm64_v8a". Alternatively, you can build on Intel Linux (e.g., ubuntu-latest), where tests are automatically skipped due to emulator limitations (no need to set CIBW_TEST_SKIP). This results in one fewer configuration line. However, from a code maintanability perspective, I recommend using macos for future extensions and support.

  6. For iOS builds,
    Use:

    • macos-13 (Intel Mac runner) for x86_64_iphonesimulator
    • macos-14or macos-latest (Apple Silicon runners) for arm64_iphoneos and arm64_iphonesimulator architectures

@hajimes hajimes changed the title Feature/mobile os Add support for Android/iOS wheels Jul 28, 2025
@hajimes hajimes merged commit c0a5022 into master Jul 28, 2025
52 checks passed
@hajimes hajimes deleted the feature/mobile-os branch September 23, 2025 08:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant