PixarAnimationStudios
Apple: Enable building as an Apple Framework
Description of Change(s)
This PR enables building of USD as a Framework. A framework build puts the output files into a directory structure which allows them to be included easily in apps on macOS, iOS and visionOS. The steps to use it are included in the README but are repeated here in brief:
- User drags the Framework directory into their project target. This automatically sets up linkage.
- User sets it to Embed and Sign in the app
Frameworks are enabled automatically for Apple embedded platforms (iOS, visionOS). Framework builds default to Monolithic because a framework may only include one dylib within it. Shared builds can still be enabled for some dev purposes, but aren't officially supported.
Experimental Feature
I request that the feature be marked as Experimental in the README, because I anticipate changes might be needed in the future to streamline how this works, such as not requiring the dependencies to be statically built. I think the current state of the PR will unblock the majority of people asking for this feature however and the changes I anticipate might be quite long term.
This incorporates some work by Maddy Adams and @meshula . The changes are largely non-invasive and are listed below:
Core Code Changes
- Adds a post build step with a zsh script that will construct the Framework bundle.
- Changes to the Plugin and usdMtlx registry to find their respective resources within the Framework
- Enable building statically against TBB and OpenSubdiv.
- New options in the CMake to handle framework build configuration
Build Script Changes
- Added argument to build as Framework (or disable) with
--build-apple-frameworkand--no-build-apple-framework - Added
--prefix-framework-headersto opt-in to prefixing the headers - Added support to
apple_utils.pyto orchestrate anXCFrameworkbuild, that combines multiple targets into one framework. - Added support for Simulator targets
- Allow shared/monolithic builds arg to allow a default based on other args.
- Build Dependencies (MaterialX, TBB) as static when building monolithic
- Allow users to pass in code signing ID manually
- Improved Codesigning identity lookup speeds+reliability for both framework and non-framework builds
- Setup signing for dependencies automatically when using Xcode target
Header Notes
Framework headers are automatically discovered when prefixed by the framework name.
This requires the user to build with --prefix-framework-headers
E.g instead of #include <pxr/pxr.h> you would do #include <OpenUSD/pxr/pxr.h>
If someone wants to avoid the prefixed behavior, they have to manually add the Header directory to their targets SYSTEM_HEADER_SEARCH_PATHS .
- [X] I have verified that all unit tests pass with the proposed changes
- [X] I have submitted a signed Contributor License Agreement
![azure-pipelines[bot] avatar](https://avatars.githubusercontent.com/in/9426?v=4 "Published by a pub.dev verified publisher"){kind=small}
@dgovil Could I ask you to pop in a note that reports when you are building a framework here?
Building with settings:
USD source directory /Users/nick/dev/usd
USD install directory /Users/nick/usd-dyfw-240616
3rd-party source directory /Users/nick/usd-dyfw-240616/src
...
Apologies @dgovil I was meaning to merge locally and got the <- -> icons backwards in the interface. Please force push to overwrite my inadvertent commit when you are ready to update.
@meshula I rebased the latest on top of dev+ios_core PR. I overwrote your changes to my branch.
I added the print out in the build for the Building with settings: section. I already had a description of how to pull in the framework. It also includes the MaterialX copy over as well.
Currently refactoring this on top of the iOS imaging branch and the latest dev, so in flux for the moment.
Rebased this PR on the imaging branch. I've also worked on making this a fully monolithic build so that it is a kosher framework. This means that you get a single (massive) framework that includes OpenUSD/OpenSubdiv/TBB/MaterialX. That may not be to everyones taste, but the alternative would be a framework per dylib which is a fairly sizable uplift to put in USD today (but something we could drive towards longterm)
It is still possible to build as a non-monolithic build, but I am not focusing on that setup because frameworks expect a single dylib per framework and we'd have something like ~70 frameworks going that route. Instead, long term, we can work with each dependency to add monolithic+framework builds to them as well, and then tease things apart here.
It also allows for building for simulator (but isn't super well tested)
My todos before I think this is ready is:
[] Make sure the USD build can load all the plugins that are part of it. Specifically HD etc... [] Make sure that MaterialX can load its shaders from the resources directory
Potentially, I want to see if its possible to modify the headers to avoid needing to add the header search path manually.
Looking promising!
Potentially, I want to see if its possible to modify the headers to avoid needing to add the header search path manually.
If you can solve that one, that would be fantastic!
Could I ask you to drop a link in to point us at
Rebased this PR on the imaging branch.
Given the evolution of the ios + imaging work, it would be helpful to have a link to the branch out here in the main thread.
Yep, added a link to the main body above but also adding it here https://github.com/PixarAnimationStudios/OpenUSD/pull/3215
With the latest changes to the PR, the USD plugins under lib/usd load, as do the MaterialX shader defs when called with
SdrRegistry &shaderReg = SdrRegistry::GetInstance();
auto nodes = shaderReg.GetNodeNames();
I need to now check for loading of the plugins that come under plugin/usd like hdStorm, hioAvif, sdrGlsfx, usdShaders.
I think it's in a good place if folks want to try it out.
I've confirmed that USD is able to register all the plugins like AVIF and Storm.
Both this and https://github.com/PixarAnimationStudios/OpenUSD/pull/3215 are rebased on top of latest dev to remove conflicts.
I've also improved the README to better reflect the setup instructions for frameworks.
After talking to Nick, we decided to punt the modification of the Header includes. This means users will currently need to add a single path manually to their System Header Search Paths. In the future, we may revisit this once some other future changes for dependencies come to fruition.
Feedback is welcome.