Apple: Enable building as an Apple Framework

[dgovil]

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:

1. User drags the Framework directory into their project target. This automatically sets up linkage.
2. User sets it to Embed and Sign in the app

It is based on the Embedded Imaging PR #3215 and so requires that be merged first.

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 initial work by Maddy Adams and @meshula . The changes are largely non-invasive and are listed below:

Core Code Changes

1. Adds a post build step with a zsh script that will construct the Framework bundle.
2. Changes to the Plugin and usdMtlx registry to find their respective resources within the Framework
3. Enable building statically against TBB and OpenSubdiv.
4. New options in the CMake to handle framework build configuration

Build Script Changes

1. Added argument to build as Framework (or disable) with --build-apple-framework and --no-build-apple-framework
2. Added the ability to build for Apple simulators (--build-simulator)
3. Allow shared/monolithic builds arg to allow a default based on other args.
4. Build Dependencies (MaterialX, TBB) as static when building monolithic
5. Allow users to pass in code signing ID manually
6. Improved Codesigning identity lookup speeds+reliability for both framework and non-framework builds
7. Setup signing for dependencies automatically when using Xcode target

Header Notes
Framework headers are automatically discovered when prefixed by the framework name.
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 .

• I have verified that all unit tests pass with the proposed changes

• I have submitted a signed Contributor License Agreement

[jesschimein]

Filed as internal issue #USD-9360

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[meshula]

@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
...

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[meshula]

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.

[dgovil]

@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.

[meshula]

Thanks for fixing the mishap and adding the Mx bits!

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Pull request contains merge conflicts.

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Pull request contains merge conflicts.

[dgovil]

Currently refactoring this on top of the iOS imaging branch and the latest dev, so in flux for the moment.

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Pull request contains merge conflicts.

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Pull request contains merge conflicts.

[dgovil]

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.

[meshula]

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.

[dgovil]

Yep, added a link to the main body above but also adding it here #3215

[meshula]

Thanks!!

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Pull request contains merge conflicts.

[dgovil]

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.

[dgovil]

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 #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.

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[dgovil]

After talking with Maddy, I actually managed to put in a post process in the zsh file that will change the headers. So now users just need to drop the framework into their project and they're off to the races.

[jesschimein]

/AzurePipelines run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).