[OLD] Apple: Enable building as an Apple Framework #2969

dgovil · 2024-02-26T18:41:58Z

Edit: As requested by @meshula , I'll be splitting up this PR into the smaller constituent parts so we can land them individually.

I will list them here so it's easy to follow along with progress. I am listing the proposed bits here, and will link them to actual PRs as they go up. These are listed in no particular order. They will be checked off as they are merged.

They are nested based on their dependencies

TempDirectory fixes : Makes sure that USD operations write to the containerized temp directory locations
Extract TBB Patches : TBB requires patches for each embedded platform. This may not be required after porting to OneTBB (Not sure), but we should move them into Apple Utils to avoid cluttering up the main build code
- Simulator Support : Support for Simulator targets for people testing without devices.
Code Signing Improvements : Improve handling of automatic code signing, especially to handle frameworks
Build as Framework: Enable building targets as frameworks
- Build as XCFramework : Enable building for a combined framework across platforms
- Modify Headers post build: simplifies inclusion of the framework into Xcode projects, or simplifies linking to just -framework OpenUSD
CCache Support : Enables faster builds which is important when building for multiple targets (this is optional but its a huge speedup)

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-framework and --no-build-apple-framework
Added --prefix-framework-headers to opt-in to prefixing the headers
Added support to apple_utils.py to orchestrate an XCFramework build, 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 .

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

I have submitted a signed Contributor License Agreement

jesschimein · 2024-02-28T17:47:45Z

Filed as internal issue #USD-9360

jesschimein · 2024-02-28T17:47:47Z

/AzurePipelines run

azure-pipelines · 2024-02-28T17:47:58Z

Azure Pipelines successfully started running 1 pipeline(s).

jesschimein · 2024-02-29T18:03:32Z

/AzurePipelines run

azure-pipelines · 2024-02-29T18:03:43Z

Azure Pipelines successfully started running 1 pipeline(s).

meshula · 2024-06-17T01:10:42Z

@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 · 2024-06-17T16:55:07Z

/AzurePipelines run

azure-pipelines · 2024-06-17T16:55:19Z

Azure Pipelines successfully started running 1 pipeline(s).

meshula · 2024-06-18T00:13:50Z

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 · 2024-06-18T18:17:08Z

@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 · 2024-06-18T20:19:16Z

Thanks for fixing the mishap and adding the Mx bits!

jesschimein · 2024-08-19T17:25:01Z

/AzurePipelines run

azure-pipelines · 2024-08-19T17:25:06Z

Pull request contains merge conflicts.

jesschimein · 2024-08-20T22:04:02Z

/AzurePipelines run

azure-pipelines · 2024-08-20T22:04:08Z

Pull request contains merge conflicts.

dgovil · 2024-08-21T16:39:44Z

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

jesschimein · 2024-08-21T17:17:09Z

/AzurePipelines run

azure-pipelines · 2024-08-21T17:17:14Z

Pull request contains merge conflicts.

jesschimein · 2024-08-23T15:58:51Z

/AzurePipelines run

azure-pipelines · 2024-08-23T15:58:57Z

Pull request contains merge conflicts.

dgovil · 2024-08-23T22:17:46Z

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 · 2024-08-23T22:50:56Z

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 · 2024-08-23T23:06:51Z

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

jesschimein · 2024-10-15T17:23:49Z

/AzurePipelines run

azure-pipelines · 2024-10-15T17:24:01Z

Azure Pipelines successfully started running 1 pipeline(s).

jesschimein · 2024-10-22T18:04:39Z

/AzurePipelines run

azure-pipelines · 2024-10-22T18:04:50Z

Azure Pipelines successfully started running 1 pipeline(s).

jesschimein · 2024-11-25T17:48:46Z

/AzurePipelines run

azure-pipelines · 2024-11-25T17:48:56Z

Azure Pipelines successfully started running 1 pipeline(s).

jesschimein · 2024-12-02T18:17:21Z

/AzurePipelines run

azure-pipelines · 2024-12-02T18:17:33Z

Azure Pipelines successfully started running 1 pipeline(s).

jesschimein · 2024-12-03T17:46:12Z

/AzurePipelines run

azure-pipelines · 2024-12-03T17:46:24Z

Azure Pipelines successfully started running 1 pipeline(s).

…tor support

jesschimein · 2025-01-30T18:05:20Z

/AzurePipelines run

azure-pipelines · 2025-01-30T18:05:30Z

Azure Pipelines successfully started running 1 pipeline(s).

meshula · 2025-05-22T17:32:30Z

build_scripts/build_usd.py


-        if context.buildTarget == apple_utils.TARGET_VISIONOS:
-            # Create visionOS config from iOS config
+        if MacOSTargetEmbedded(context) and context.buildTarget != apple_utils.TARGET_IOS:


When GCD is available as a work backend let's get rid of this patching on vision os

The GCD work will still require TBB for the data constructs unfortunately

meshula · 2025-05-22T17:32:46Z

build_scripts/build_usd.py

    the file does not match.

-    Returns the absolute path to the directory where files have 
+    Returns the absolute path to the directory where files have


let's get ws fixes out of this pr

meshula · 2025-05-22T17:34:16Z

build_scripts/build_usd.py

-        cmakeOptions = ['-DMATERIALX_BUILD_SHARED_LIBS=ON',
-                        '-DMATERIALX_BUILD_TESTS=OFF'
-        ]
+        cmakeOptions = ['-DMATERIALX_BUILD_TESTS=OFF']


rebase on 25.05 some of this will disappear

meshula · 2025-05-22T17:35:00Z

build_scripts/build_usd.py

                       default=codesignDefault, action="store_true",
                       help=("Enable code signing for macOS builds "
                             "(defaults to enabled on Apple Silicon)"))
+    group.add_argument("--codesign-id", dest="macos_codesign_id", type=str)


can we clean up code signing separately?

meshula · 2025-05-22T17:35:58Z

build_scripts/build_usd.py

    buildMayapyTests=("On" if context.buildMayapyTests else "Off"),
    buildAnimXTests=("On" if context.buildAnimXTests else "Off"),
-    enableHDF5=("On" if context.enableHDF5 else "Off"))
+    enableHDF5=("On" if context.enableHDF5 else "Off"),


we're dropping hdf5 support anyway

meshula · 2025-05-22T17:36:27Z

cmake/defaults/CXXDefaults.cmake

+endif()
+
+# Setup CCache for C/C++ compilation
+if(PXR_ENABLE_COMPILER_CACHE)


different PR

meshula · 2025-05-22T17:38:42Z

pxr/base/arch/defines.h

 #else
 #define ARCH_OS_OSX
 #endif
+#if TARGET_OS_SIMULATOR


separate PR?

meshula · 2025-05-22T17:39:03Z

pxr/base/plug/initConfig.cpp

    _AppendPathList(&result, buildLocation, binaryPath);
    _AppendPathList(&result, pluginBuildLocation, binaryPath);

+#ifdef PXR_BUILD_APPLE_FRAMEWORK


can we configure this in cmake to eliminate the ifdef here

meshula · 2025-05-22T17:39:34Z

pxr/imaging/hgiMetal/graphicsCmds.mm

-        }
-        else {
-            metalColorAttachment.loadAction =
+        metalColorAttachment.loadAction =


dgovil force-pushed the ios_core_frameworks branch from bc56f55 to 5f321b9 Compare February 26, 2024 18:54

dgovil force-pushed the ios_core_frameworks branch 2 times, most recently from 1664609 to 4a0f035 Compare February 29, 2024 03:05

dgovil force-pushed the ios_core_frameworks branch from e07ce73 to 352d4d6 Compare June 18, 2024 18:14

dgovil force-pushed the ios_core_frameworks branch from 352d4d6 to 947efa1 Compare August 16, 2024 18:51

dgovil force-pushed the ios_core_frameworks branch from 390e3af to 8d23ab3 Compare August 20, 2024 20:54

dgovil mentioned this pull request Aug 22, 2024

Ios imaging #3245

Closed

2 tasks

dgovil force-pushed the ios_core_frameworks branch from 4f54b2a to 47da75e Compare November 23, 2024 18:59

Allow building as Apple Frameworks and XCFrameworks, including Simula…

0729140

…tor support

dgovil force-pushed the ios_core_frameworks branch from 12c2357 to 0729140 Compare January 27, 2025 18:58

Add opt-in option to prefix headers

50f2977

dgovil force-pushed the ios_core_frameworks branch from d1bf209 to 50f2977 Compare January 27, 2025 19:14

dgovil added 2 commits January 27, 2025 11:20

Add some more language around configuring Xcode

0c3c5a9

Fix iOS not clearing background buffer when animating/navigating

25cedad

meshula reviewed May 22, 2025

View reviewed changes

cmake/defaults/CXXDefaults.cmake

endif()

# Setup CCache for C/C++ compilation

if(PXR_ENABLE_COMPILER_CACHE)

Copy link

Member

meshula May 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

different PR

meshula reviewed May 22, 2025

View reviewed changes

pxr/base/arch/defines.h

#else

#define ARCH_OS_OSX

#endif

#if TARGET_OS_SIMULATOR

Copy link

Member

meshula May 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

separate PR?

meshula reviewed May 22, 2025

View reviewed changes

pxr/imaging/hgiMetal/graphicsCmds.mm

}

else {

metalColorAttachment.loadAction =

metalColorAttachment.loadAction =

Copy link

Member

meshula May 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

separate

dgovil changed the title ~~Apple: Enable building as an Apple Framework~~ [OLD] Apple: Enable building as an Apple Framework Jul 8, 2025

dgovil mentioned this pull request Jul 8, 2025

APPLE: Enable Building as Framework #3713

Open

5 tasks

[OLD] Apple: Enable building as an Apple Framework #2969

Are you sure you want to change the base?

[OLD] Apple: Enable building as an Apple Framework #2969

Uh oh!

Conversation

dgovil commented Feb 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change(s)

Uh oh!

jesschimein commented Feb 28, 2024

Uh oh!

jesschimein commented Feb 28, 2024

Uh oh!

azure-pipelines bot commented Feb 28, 2024

Uh oh!

jesschimein commented Feb 29, 2024

Uh oh!

azure-pipelines bot commented Feb 29, 2024

Uh oh!

meshula commented Jun 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jesschimein commented Jun 17, 2024

Uh oh!

azure-pipelines bot commented Jun 17, 2024

Uh oh!

meshula commented Jun 18, 2024

Uh oh!

dgovil commented Jun 18, 2024

Uh oh!

meshula commented Jun 18, 2024

Uh oh!

jesschimein commented Aug 19, 2024

Uh oh!

azure-pipelines bot commented Aug 19, 2024

Uh oh!

jesschimein commented Aug 20, 2024

Uh oh!

azure-pipelines bot commented Aug 20, 2024

Uh oh!

dgovil commented Aug 21, 2024

Uh oh!

jesschimein commented Aug 21, 2024

Uh oh!

azure-pipelines bot commented Aug 21, 2024

Uh oh!

jesschimein commented Aug 23, 2024

Uh oh!

azure-pipelines bot commented Aug 23, 2024

Uh oh!

dgovil commented Aug 23, 2024

Uh oh!

meshula commented Aug 23, 2024

Uh oh!

dgovil commented Aug 23, 2024

Uh oh!

jesschimein commented Oct 15, 2024

Uh oh!

azure-pipelines bot commented Oct 15, 2024

Uh oh!

jesschimein commented Oct 22, 2024

Uh oh!

azure-pipelines bot commented Oct 22, 2024

Uh oh!

jesschimein commented Nov 25, 2024

Uh oh!

azure-pipelines bot commented Nov 25, 2024

Uh oh!

jesschimein commented Dec 2, 2024

Uh oh!

azure-pipelines bot commented Dec 2, 2024

Uh oh!

jesschimein commented Dec 3, 2024

Uh oh!

azure-pipelines bot commented Dec 3, 2024

Uh oh!

jesschimein commented Jan 30, 2025

Uh oh!

azure-pipelines bot commented Jan 30, 2025

Uh oh!

dgovil commented Feb 26, 2024 •

edited

Loading

meshula commented Jun 17, 2024 •

edited

Loading