Device & simulator flavors of pre-compiled libraries and frameworks

[pepicrft]

Our dependency graph supports defining dependencies on pre-compiled libraries and frameworks:

.framework(path: "./Framework.framework")
.library(path: "./libLibrary.a, publicHeaders: "./headers")

When generating Xcode projects, we use standard linking build phases for them. In the case of dynamic binaries that need to be copied into a directory from which they can be dynamically linked, we use a script that can strip out the unnecessary architectures. Moreover, we recently added support for multi-platform, which brought the concept of platform conditions, allowing developers to specify linking conditions (e.g., link only Framework.framework if you are building for macOS).

While the model works, it doesn't offer the flexibility to declare different framework versions depending on the SDK (device and simulator). This is a need for caching, where we'd like to include different versions of the binaries for the various SDKs of the platform and conditionally link and embed one or another based on the SDK. Note that there are other methods to approach this problem:

• XCFrameworks: ¹ They can carry the different flavors of the framework, and Xcode can take of integrating the right flavor based on the target destination. However, it proved to be a different format for caching because it requires compiling the targets with a build setting to support binary distribution, which might cause compilation issues.
• Universal binaries: ² This is Carthage's approach for integrating dynamic frameworks. Through a script build phase, they'd strip out the unnecessary architectures when copying the frameworks. While this works with dynamic frameworks, it doesn't with static ones, where there's no "copy framework" build phase where we can run the stripping logic. Because of that, we developers will end up with larger binaries.

We could extend our interface to support passing a binary per SDK. Here's an idea:

.framework(path: [.simulator("./simulator/Framework.framework"), .device("./device/Framework.framework")])

We'd need to adjust the logic configuring all the links to use build settings instead of build phases because build phases can specify platform conditions but not SDK conditions. In build settings, we can define conditional settings based on the SDK:

FRAMEWORK_SEARCH_PATHS[sdk=iphonesimulator] = ...

The logic would need to consider the platform conditions and flat-map them into a set of SDK conditions we'd use in the build settings.

Does this sound reasonable to you? Are there any implications in this change that you think I should be aware of?

Footnotes

1. https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle ↩

2. https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary ↩

[kwridan]

Thanks for surfacing this as an RFC @pepicrft

While the model works, it doesn't offer the flexibility to declare different framework versions depending on the SDK (device and simulator). This is a need for caching, where we'd like to include different versions of the binaries for the various SDKs of the platform and conditionally link and embed one or another based on the SDK.

This is precisely what XCFrameworks are designed to address. We converted all our pre-compiled frameworks to XCFrameworks along with the Apple Silicon transition as fat binaries / frameworks can't support 2 arm64 slices (one for simulator and another for device, taking iOS as an example) whereas XCFrameworks are designed to support this.

XCFrameworks: ... However, it proved to be a different format for caching because it requires compiling the targets with a build setting to support binary distribution, which might cause compilation issues.

Which were the issue? Are they general XCFramework issues or perhaps how caching configures or makes use of them? May be worth exploring solutions to this ahead of abandoning them and taking a step back to frameworks which doesn't seem to be the future direction in Xcode.

Universal binaries

This approach used to work in the past when Macs were primarily on intel and simulator was x86_64 and devices were arm64, but now with Apple Silicon, both are arm64! To my knowledge it isn't possible to make a fat / universal binary with both.

We'd need to adjust the logic configuring all the links to use build settings instead of build phases because build phases can specify platform conditions but not SDK conditions. In build settings, we can define conditional settings based on the SDK:

It would be a shame to move away from leveraging the standard build phases and associated primitives like the new conditions. The main beauty of Tuist is how it generates projects that you would have manually crafted using Xcode UI, just ensures correctness and reproducibility at scale.

If this is a must for caching, perhaps would not expose this as a public API, rather make the caching mappers leverage the build settings as they need rather than add this logic to the generator and enforce it for all projects.

[waltflanagan]

However, it proved to be a different format for caching because it requires compiling the targets with a build setting to support binary distribution, which might cause compilation issues.

I'm also curious to know more since I'm with @kwridan feeling that leaning more into XCFrameworks is the right path since they are designed for just this challenge.

What if we make XCFrameworks the core caching mechanism and potentially include the ability to limit the caching to a specific subset of supported platforms (e.g. allowing end users to pass a flag to exclude simulator builds or a whole platform). We could potentially come up with a way to include these exclusions in hashing logic to resolved what artifacts are cached. I wonder if this is just the default way of operating with tuist cloud. potentially cloud cached artifacts should be required to support all platforms, but local caching could limit things to specific slices.

Generally the more we have to diverge from "standard" solutions in service of caching the more exposure the project has to breaking changes from SPM/Xcode direction.

[shahzadmajeed]

Definitely interested as XCFrameworks are my goto solution for binary distribution (even for dependency cache for non-tuist project) and I didn't see any problem with it

[pepicrft]

It would be a shame to move away from leveraging the standard build phases and associated primitives like the new conditions. The main beauty of Tuist is how it generates projects that you would have manually crafted using Xcode UI, just ensures correctness and reproducibility at scale.

I will make XCFrameworks the default format, including all the supported platforms and architectures in each. In the future, we might give users more fine-grained control over what they want to bundle (e.g., only a subset of the architectures), but for now, I'd keep things simple (for the user and the implementation).

Generally the more we have to diverge from "standard" solutions in service of caching the more exposure the project has to breaking changes from SPM/Xcode direction.

100% and this is not something that we want. I think Tuist is very well positioned in this regard, and I don't want to introduce any regression here. Many organization choose Tuist because it's more future-proof that other solutions that replace the build system.

[pepicrft]

Which were the issue? Are they general XCFramework issues or perhaps how caching configures or makes use of them? May be worth exploring solutions to this ahead of abandoning them and taking a step back to frameworks which doesn't seem to be the future direction in Xcode.

For some reason, I thought building a .xcframework required the build setting BUILD_LIBRARY_FOR_DISTRIBUTION=YES, and that'd cause some compilation issues as detailed here. However, that doesn't seem necessary, so I think it's fine to use .xcframeworks. When we cache the binaries, we hash the complete Swift version tying the binaries to the Swift version that generated them. Therefore we don't need support for library distribution that the build setting would bring.

This approach used to work in the past when Macs were primarily on intel and simulator was x86_64 and devices were arm64, but now with Apple Silicon, both are arm64! To my knowledge it isn't possible to make a fat / universal binary with both.

That's right. That option is out of the equation.

It would be a shame to move away from leveraging the standard build phases and associated primitives like the new conditions. The main beauty of Tuist is how it generates projects that you would have manually crafted using Xcode UI, just ensures correctness and reproducibility at scale.

Agreed. I'm not a big fan of moving some conditional build-time logic to build settings because that makes it harder to reason about a project. I think it's very valuable being able to glance over the build phases and understand what's being linked and embedded into any target of the project.

[fortmarek]

Should we try to move caching of tuist projects to xcframeworks and ask a couple of our users to make the move, too? And for Tuist 4, make xcframeworks the default and remove support for frameworks completely? I do think we should use the chance now to have a single format only, instead of having to support both.

[pepicrft]

Should we try to move caching of tuist projects to xcframeworks and ask a couple of our users to make the move, too? And for Tuist 4, make xcframeworks the default and remove support for frameworks completely? I do think we should use the chance now to have a single format only, instead of having to support both.

Definitively. Once we have support for xcframeworks bundling multi-platform targets, we should get some users to give it a try.
As for dropping frameworks, 100%. This is the opportunity.