Add opt-in option to prefix headers

Author: dgovil

README.md

@@ -182,17 +182,18 @@ Builds for Apple platforms may optionally build as a framework using the `--buil
 - Building a universal macOS framework is currently not supported. Please generate the arches separately and `lipo` 
   them together after.
 
-To add the Framework to your application, simply add `OpenUSD.framework` to your Xcode project.
+To add the Framework to your application, add `OpenUSD.framework` to your Xcode project.
 It is recommended to set it to `Embed and Sign`.
 
-When including sources from the Framework, you must prefix the include with the framework name.
-However, you should note that these includes are not portable to non-framework builds.
-e.g `#include <OpenUSD/pxr/pxr.h>`
+To setup headers, you may then choose one of two routes:
 
-Optionally, if you want to avoid prefixed includes for your cross platform code, you can manually add the search path
-by setting `SYSTEM_HEADER_SEARCH_PATHS` in your Xcode target to the Headers directory within the framework.
-For example, if your Framework folder is in your project, under a folder with the same name as your target, you would
-set it as `$(SRCROOT)/$(TARGET_NAME)/OpenUSD.framework/Headers`. 
+1. Configure the Xcode `SYSTEM_HEADER_SEARCH_PATHS` to add the path to your headers. e.g
+`$(SRCROOT)/OpenUSD.framework/Headers` if the framework exists in your projects root. This is recommended
+if you intend to share source files with other platforms.
+
+2. Build with `--prefix-framework-headers` (or `-DPXR_APPLE_PREFIX_FRAMEWORK_HEADERS=ON` if using CMake)
+to automatically process the frameworks headers. This requires no extra configuration in Xcode, but does require
+that all includes be prefixed with the name of the framework. e.g `#include <OpenUSD/pxr/pxr.h>`
 
 OpenUSD also supports building a combined XCFramework as well of multiple targets.
 This command takes an optional list of targets to build, but will otherwise build all supported platforms.

build_scripts/build_usd.py

@@ -1865,6 +1865,7 @@ def InstallUSD(context, force, buildArgs):
             extraArgs.append('-DCMAKE_CXX_FLAGS="/Zm150"')
         if MacOS():
             extraArgs.append(f"-DPXR_BUILD_APPLE_FRAMEWORK={'ON' if context.buildAppleFramework else 'OFF'}")
+            extraArgs.append(f"-DPXR_APPLE_PREFIX_FRAMEWORK_HEADERS={'ON' if context.prefixFrameworkHeaders else 'OFF'}")
 
         # Make sure to use boost installed by the build script and not any
         # system installed boost
@@ -1997,6 +1998,8 @@ def InstallUSD(context, force, buildArgs):
                           help="Build USD as an Apple Framework (Default if using build)")
     subgroup.add_argument("--no-build-apple-framework", dest="no_build_apple_framework", action="store_true",
                           help="Do not build USD as an Apple Framework (Default if macOS)")
+    group.add_argument("--prefix-framework-headers", dest="prefix_framework_headers", action="store_true",
+                          help="Add the Framework as a prefix to header includes so that they can automatically be included.")
 
     if apple_utils.IsHostArm():
         # Intel Homebrew stores packages in /usr/local which unfortunately can
@@ -2348,6 +2351,7 @@ def __init__(self, args):
 
             self.buildAppleFramework = ((args.build_apple_framework or MacOSTargetEmbedded(self))
                                         and not args.no_build_apple_framework)
+            self.prefixFrameworkHeaders = args.prefix_framework_headers and self.buildAppleFramework
             if self.buildAppleFramework and not args.build_type:
                     self.buildShared = False
                     self.buildMonolithic = True

cmake/defaults/Options.cmake

@@ -70,7 +70,7 @@ if(APPLE)
     endif ()
 
     option(PXR_BUILD_APPLE_FRAMEWORK "Builds an Apple Framework." ${PXR_APPLE_EMBEDDED})
-    option(PXR_APPLE_APPLY_HEADER_PREFIX "Prefix the headers in framework builds" ON )
+    option(PXR_APPLE_PREFIX_FRAMEWORK_HEADERS "Prefix the headers in framework builds" OFF )
     set(PXR_APPLE_FRAMEWORK_NAME "OpenUSD" CACHE STRING "Name to provide Apple Framework build")
     set(PXR_APPLE_IDENTIFIER_DOMAIN "org.openusd" CACHE STRING "Name to provide Apple Framework build")
     if (${PXR_BUILD_APPLE_FRAMEWORK})

cmake/macros/Public.cmake

@@ -1464,7 +1464,7 @@ function(pxr_create_apple_framework)
         set(EMBEDDED_BUILD "false")
     endif()
 
-    if (PXR_APPLE_APPLY_HEADER_PREFIX)
+    if (PXR_APPLE_PREFIX_FRAMEWORK_HEADERS)
         set(APPLY_HEADER_PREFIX "true")
     else()
         set(APPLY_HEADER_PREFIX "false")