Convention for packages to declare their own native (Android/iOS) requirements?

[ElliotGarbus]

I've been building a packaging tool for the Kivy ecosystem — KivyForge — that makes use of the Android and iOS platform-tagged wheel PEPs (738/730) for native binaries (thanks for your leadership!). Working on that surfaced a gap, and it looks like one Briefcase, Chaquopy, p4a, and KivyForge all share: there's no way for a package to declare what it needs from the native build — Gradle deps, permissions, entitlements, manifest entries, Info.plist keys — so app authors end up hand-transcribing that out of each package's README, and it silently drifts on every version bump.

I've drafted a spec for it: a package ships a small TOML sidecar in its wheel declaring its native requirements, a build tool discovers it via an entry point and reads it without importing the package. Deliberately toolchain-neutral, no new packaging standard, no build-backend plugin.

https://github.com/ElliotGarbus/native-integration

Don't start with the spec — it's ~17k words. README first, then one example: pystripe to see both halves of one integration. Appendix D is a one-line description of every key if you'd rather scan the surface.

I'd value your feedback on the concept itself — is this the right shape for the problem? @freakboy3742

[freakboy3742]

@ElliotGarbus Thanks for putting this together, and for reaching out.

First impressions - this looks great. I'm sure when I pull out the fine-toothed comb, I'll have quibbles over details, but from what I've seen the broad direction looks solid to me. At the very least, I can completely agree there's a gap here - a library (such as pystripe) should be able to declare that it has requirements on the deployment environment; At the very least, Toga would be able to make use of this sort of capability to simplify deployment. A single (or small number) of files included as part of the packaging process are an effective way to communicate that detail.

Some initial thoughts based on what I've seen so far:

• My personal expertise is much stronger on iOS; I know enough Android to be dangerous, but we really want @mhsmith's take on this for the deep Android perspective. He's on holiday right now; he should be back and able to give feedback in early September.

• While iOS and Android are obviously the platforms where this has the highest impact, it would also have use on macOS (when code is deployed as a full app) - the macOS sandbox requires permissions for location tracking, camera access, and any number of other properties.

• There's also an overlap with Web deployment. I've taken a very similar approach in how Briefcase handles Web deployment - Toga's web backend can specify some requirements (such as dependencies on PyScript versions) and content that needs to be included on the site page (stylesheets, other web resources etc); but it's done in such as way that any package can contribute other requirements to the deployment process.

• While you have presented this as a "no changes to existing standards required" - and I completely agree that's a desirable property for initial development - in the longer term, I think the aim should be to get this in the form of a PEP (under the Packaging Council's jurisdiction). That doesn't need to happen right away (or even "soon") - but when the time comes, and we've converged on a spec that works for all involved, I'd be happy to sponsor that effort in my capacity as a CPython core team and PyPA member.

• My immediate question about standardisation is how we should go about defining (and maintaining) platform-specific details - what happens if (and, lets be honest... when :-) ) iOS changes their packaging/permission/etc requirements? How can we keep the standards up to date and sufficiently flexible to adapt to those changes?

I'm sure I'll have more thoughts when I've had a chance to dig deeper into the example and spec; but I wanted to get you an initial response.

From a logistical perspective - I'm happy to continue having a conversation here; but is there anywhere else that might be a more helpful/central location for this sort of discussion? This seems like the sort of conversation that should be centralised as much as possible.

[ElliotGarbus]

@freakboy3742
Thanks for the feedback. I look forward to continuing the discussion. I created a discussion forum on the repo. This seems like a natural place to centralize this dialog. https://github.com/ElliotGarbus/native-integration/discussions

I agree with the direction to eventually move this into a PEP. My thinking was if we could get a few tools using it, the process would go smoother.

As for keeping up with the changes to the standard, the "contract" is versioned, that is the sidecar toml file carries a contract number. A tool that does not support that contract number will reject the sidecar. https://github.com/ElliotGarbus/native-integration/blob/main/SPEC.md#43-contract-version

The platform attribute is a list, so the current model is easily extended to support the web and macOS.

Thanks for your enthusiastic response. I look forward to working on this together.
For my next steps I will work on a reference reader library and a conformance test suite continuing on the current focus on ios and android. I'll then integrate this into KivyForge and build out a few libraries for evaluation.

[freakboy3742]

@freakboy3742 Thanks for the feedback. I look forward to continuing the discussion. I created a discussion forum on the repo. This seems like a natural place to centralize this dialog. https://github.com/ElliotGarbus/native-integration/discussions

I'll take any further comments to that thread. I hope to find some time next week for a deep dive into this.

I agree with the direction to eventually move this into a PEP. My thinking was if we could get a few tools using it, the process would go smoother.

Completely agreed on this. Going to the steering council with a "Here's a standard that every relevant player in the space is already using" will turn the approval process into more of a rubber stamp than an ordeal :-)