Add Framework build support

Author: dgovil

README.md

@@ -173,6 +173,11 @@ Or for visionOS:
 > python OpenUSD/build_scripts/build_usd.py --build-target visionOS --build-monolithic /path/to/my_usd_install_dir
 ```
 
+Additionally you can provide the `--build-apple-framework` flag to create a framework output, for easier integration
+into an Xcode application. Framework support is currently experimental. It defaults to On for iOS and visionOS. 
+Framework builds will enable monolithic builds by default.
+
+
 ##### Windows:
 
 Launch the "x64 Native Tools Command Prompt" for your version of Visual Studio

build_scripts/apple_utils.py

@@ -15,6 +15,7 @@
 import sys
 import locale
 import os
+import re
 import platform
 import shlex
 import subprocess
@@ -163,20 +164,56 @@ def ExtractFilesRecursive(path, cond):
                 files.append(os.path.join(r, file))
     return files
 
-def CodesignFiles(files):
-    SDKVersion  = subprocess.check_output(
-        ['xcodebuild', '-version']).strip()[6:10]
-    codeSignIDs = subprocess.check_output(
-        ['security', 'find-identity', '-vp', 'codesigning'])
+def _GetCodeSignStringFromTerminal():
+    codeSignIDs = GetCommandOutput(['security', 'find-identity', '-vp', 'codesigning'])
+    return codeSignIDs
 
-    codeSignID = "-"
+def GetCodeSignID():
     if os.environ.get('CODE_SIGN_ID'):
-        codeSignID = os.environ.get('CODE_SIGN_ID')
-    elif float(SDKVersion) >= 11.0 and \
-                codeSignIDs.find(b'Apple Development') != -1:
-        codeSignID = "Apple Development"
-    elif codeSignIDs.find(b'Mac Developer') != -1:
-        codeSignID = "Mac Developer"
+        return os.environ.get('CODE_SIGN_ID')
+
+    codeSignIDs = _GetCodeSignStringFromTerminal()
+    if not codeSignIDs:
+        return "-"
+    for codeSignID in codeSignIDs.splitlines():
+        if "CSSMERR_TP_CERT_REVOKED" in codeSignID:
+            continue
+        if ")" not in codeSignID:
+            continue
+        codeSignID = codeSignID.split()[1]
+        break
+    else:
+        raise RuntimeError("Could not find a valid codesigning ID")
+
+    return codeSignID or "-"
+
+def GetCodeSignIDHash():
+    codeSignIDs = _GetCodeSignStringFromTerminal()
+    try:
+        return re.findall(r'\(.*?\)', codeSignIDs)[0][1:-1]
+    except:
+        raise Exception("Unable to parse codesign ID hash")
+
+def GetDevelopmentTeamID():
+    if os.environ.get("DEVELOPMENT_TEAM"):
+        return os.environ.get("DEVELOPMENT_TEAM")
+    codesignID = GetCodeSignIDHash()
+
+    certs = subprocess.check_output(["security", "find-certificate", "-c", codesignID, "-p"])
+    subject = GetCommandOutput(["openssl", "x509", "-subject"], input=certs)
+    subject = subject.splitlines()[0]
+
+    # Extract the Organizational Unit (OU field) from the cert
+    try:
+        team = [elm for elm in subject.split(
+            '/') if elm.startswith('OU')][0].split('=')[1]
+        if team is not None and team != "":
+            return team
+    except Exception as ex:
+        raise Exception("No development team found with exception " + ex)
+
+def CodesignFiles(files):
+    codeSignID = GetCodeSignID()
 
     for f in files:
         subprocess.call(['codesign', '-f', '-s', '{codesignid}'
@@ -245,4 +282,10 @@ def ConfigureCMakeExtraArgs(context, args:List[str]) -> List[str]:
         args.append(f"-DCMAKE_FIND_ROOT_PATH_MODE_INCLUDE=BOTH")
         args.append(f"-DCMAKE_FIND_ROOT_PATH_MODE_LIBRARY=BOTH")
 
+
+    # Signing needs to happen on all systems
+    if context.macOSCodesign:
+        args.append(f"-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY={GetCodeSignID()}")
+        args.append(f"-DCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM={GetDevelopmentTeamID()}")
+
     return args

build_scripts/build_usd.py

@@ -955,7 +955,7 @@ def InstallBoost(context, force, buildArgs):
 
 def InstallOneTBB(context, force, buildArgs):
     with CurrentWorkingDirectory(DownloadURL(ONETBB_URL, context, force)):
-        RunCMake(context, force, 
+        RunCMake(context, force,
                  ['-DTBB_TEST=OFF',
                   '-DTBB_STRICT=OFF'] + buildArgs)
 
@@ -1326,12 +1326,12 @@ def InstallOpenImageIO(context, force, buildArgs):
                      '-DUSE_PYTHON=OFF',
                      '-DSTOP_ON_WARNING=OFF']
 
-        # OIIO's FindOpenEXR module circumvents CMake's normal library 
+        # OIIO's FindOpenEXR module circumvents CMake's normal library
         # search order, which causes versions of OpenEXR installed in
         # /usr/local or other hard-coded locations in the module to
-        # take precedence over the version we've built, which would 
-        # normally be picked up when we specify CMAKE_PREFIX_PATH. 
-        # This may lead to undefined symbol errors at build or runtime. 
+        # take precedence over the version we've built, which would
+        # normally be picked up when we specify CMAKE_PREFIX_PATH.
+        # This may lead to undefined symbol errors at build or runtime.
         # So, we explicitly specify the OpenEXR we want to use here.
         extraArgs.append('-DOPENEXR_ROOT="{instDir}"'
                          .format(instDir=context.instDir))
@@ -1790,6 +1790,10 @@ def InstallUSD(context, force, buildArgs):
         if Windows():
             # Increase the precompiled header buffer limit.
             extraArgs.append('-DCMAKE_CXX_FLAGS="/Zm150"')
+        if MacOS():
+            extraArgs.append(f"-DPXR_BUILD_APPLE_FRAMEWORK={'ON' if context.buildAppleFramework else 'OFF'}")
+            if context.macOSCodesign:
+                extraArgs.append(f"-DPXR_APPLE_CODESIGN_IDENTITY={context.macOSCodesign}")
 
         # Make sure to use boost installed by the build script and not any
         # system installed boost
@@ -1910,6 +1914,12 @@ def InstallUSD(context, force, buildArgs):
                        help=("Build target for macOS cross compilation. "
                              "(default: {})".format(
                                 apple_utils.GetBuildTargetDefault())))
+    subgroup = group.add_mutually_exclusive_group()
+    subgroup.add_argument("--build-apple-framework", dest="build_apple_framework", action="store_true",
+                          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)")
+
     if apple_utils.IsHostArm():
         # Intel Homebrew stores packages in /usr/local which unfortunately can
         # be where a lot of other things are too. So we only add this flag on arm macs.
@@ -1945,6 +1955,7 @@ def InstallUSD(context, force, buildArgs):
                        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)
 
 if Linux():
     group.add_argument("--use-cxx11-abi", type=int, choices=[0, 1],
@@ -2234,11 +2245,18 @@ def __init__(self, args):
             self.buildTarget = args.build_target
             apple_utils.SetTarget(self, self.buildTarget)
 
-            self.macOSCodesign = \
-                (args.macos_codesign if hasattr(args, "macos_codesign")
-                 else False)
+            self.macOSCodesign = False
+            if args.macos_codesign:
+                self.macOSCodesign = args.macos_codesign_id or apple_utils.GetCodeSignID()
             if apple_utils.IsHostArm() and args.ignore_homebrew:
                 self.ignorePaths.append("/opt/homebrew")
+
+            self.buildAppleFramework = ((args.build_apple_framework
+                                         or self.buildTarget in apple_utils.EMBEDDED_PLATFORMS)
+                                        and not args.no_build_apple_framework)
+            if self.buildAppleFramework:
+                self.buildShared = False
+                self.buildMonolithic = True
         else:
             self.buildTarget = ""
 
@@ -2585,6 +2603,7 @@ def _JoinVersion(v):
 summaryMsg += """\
     Variant                     {buildVariant}
     Target                      {buildTarget}
+    Framework Build             {buildAppleFramework}
     Imaging                     {buildImaging}
       Ptex support:             {enablePtex}
       OpenVDB support:          {enableOpenVDB}
@@ -2669,7 +2688,8 @@ def FormatBuildArguments(buildArgs):
     buildMaterialX=("On" if context.buildMaterialX else "Off"),
     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"),
+    buildAppleFramework=("On" if MacOS() and context.buildAppleFramework else "Off"))
 
 Print(summaryMsg)
 
@@ -2731,8 +2751,9 @@ def FormatBuildArguments(buildArgs):
     ])
 
 if MacOS():
-    if context.macOSCodesign:
-        apple_utils.Codesign(context.usdInstDir, verbosity > 1)
+    # We don't need to codesign when building a framework because it's handled during framework creation
+    if context.macOSCodesign and not context.buildAppleFramework:
+        apple_utils.Codesign(context, verbosity > 1)
 
 additionalInstructions = any([context.buildPython, context.buildTools, context.buildPrman])
 if additionalInstructions:
@@ -2755,3 +2776,12 @@ def FormatBuildArguments(buildArgs):
 if context.buildPrman:
     Print("See documentation at http://openusd.org/docs/RenderMan-USD-Imaging-Plugin.html "
           "for setting up the RenderMan plugin.\n")
+
+if context.buildAppleFramework:
+    Print("""
+        Added the following framework to your Xcode Project, (recommended as Embed Without Signing):
+        OpenUSD.framework
+        
+        Set the following compiler argument, to find the headers:
+        SYSTEM_HEADER_SEARCH_PATHS=$(SRCROOT)/$(TARGET_NAME)/OpenUSD.framework/Headers
+    """)

cmake/defaults/CXXDefaults.cmake

@@ -89,3 +89,19 @@ if (PXR_PREFER_SAFETY_OVER_SPEED)
 else()
    set(PXR_PREFER_SAFETY_OVER_SPEED "0")
 endif()
+
+# Setup CCache for C/C++ compilation
+if(PXR_ENABLE_COMPILER_CACHE)
+    find_program(COMPILER_CACHE_PROGRAM ${PXR_COMPILER_CACHE_NAME})
+    if(COMPILER_CACHE_PROGRAM)
+        set(CMAKE_C_COMPILER_LAUNCHER "${COMPILER_CACHE_PROGRAM}")
+        set(CMAKE_CXX_COMPILER_LAUNCHER "${COMPILER_CACHE_PROGRAM}")
+    else ()
+        MESSAGE(STATUS "Compiler Caching disabled. Could not find ${PXR_COMPILER_CACHE_NAME}.")
+    endif()
+endif()
+
+# Set that Apple Framework is being build
+if (PXR_BUILD_APPLE_FRAMEWORK)
+    _add_define("PXR_BUILD_APPLE_FRAMEWORK")
+endif()

cmake/defaults/Options.cmake

@@ -38,6 +38,7 @@ option(PXR_PREFER_SAFETY_OVER_SPEED
         ON)
 
 if(APPLE)
+    set(PXR_APPLE_CODESIGN_IDENTITY "-" CACHE STRING "The Codesigning identity needed to sign compiled objects")
     # Cross Compilation detection as defined in CMake docs
     # Required to be handled here so it can configure options later on
     # https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-ios-tvos-visionos-or-watchos
@@ -54,6 +55,16 @@ if(APPLE)
         endif()
         set(PXR_ENABLE_GL_SUPPORT OFF)
     endif ()
+
+    option(PXR_BUILD_APPLE_FRAMEWORK "Builds an Apple Framework." APPLE_EMBEDDED)
+    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})
+        if(${PXR_BUILD_USD_TOOLS})
+            MESSAGE(STATUS "Setting PXR_BUILD_USD_TOOLS=OFF because PXR_BUILD_APPLE_FRAMEWORK is enabled.")
+            set(PXR_BUILD_USD_TOOLS OFF)
+        endif()
+    endif()
 endif()
 
 
@@ -133,6 +144,12 @@ set(PXR_LIB_PREFIX ""
 
 option(BUILD_SHARED_LIBS "Build shared libraries." ON)
 option(PXR_BUILD_MONOLITHIC "Build a monolithic library." OFF)
+if (${PXR_BUILD_APPLE_FRAMEWORK})
+    set(BUILD_SHARED_LIBS OFF)
+    set(PXR_BUILD_MONOLITHIC ON)
+    MESSAGE(STATUS "Setting PXR_BUILD_MONOLITHIC=ON for Framework build")
+endif ()
+
 set(PXR_MONOLITHIC_IMPORT ""
     CACHE
     STRING
@@ -228,3 +245,11 @@ if (${PXR_BUILD_PYTHON_DOCUMENTATION})
         set(PXR_BUILD_PYTHON_DOCUMENTATION "OFF" CACHE BOOL "" FORCE)
     endif()
 endif()
+
+# Configure the use of compiler caches for faster compilation
+option(PXR_ENABLE_COMPILER_CACHE "Enable the use of a compiler cache" OFF)
+set(PXR_COMPILER_CACHE_NAME "ccache"
+        CACHE
+        STRING
+        "The name of the compiler cache program to use"
+)

cmake/macros/Public.cmake

@@ -1104,6 +1104,12 @@ function(pxr_toplevel_epilogue)
     # Setup the plugins in the top epilogue to ensure that everybody has had a
     # chance to update PXR_EXTRA_PLUGINS with their plugin paths.
     pxr_setup_plugins()
+
+    # Build
+    if (PXR_BUILD_APPLE_FRAMEWORK)
+        pxr_create_apple_framework()
+    endif ()
+
 endfunction() # pxr_toplevel_epilogue
 
 function(pxr_monolithic_epilogue)
@@ -1294,10 +1300,10 @@ function(pxr_build_python_documentation)
 endfunction() # pxr_build_python_documentation
 
 # Adding support for a "docs-only" directory, needed when adding doxygen docs
-# not associated with a specific library/etc. 
+# not associated with a specific library/etc.
 function(pxr_docs_only_dir NAME)
-    # Get list of doxygen files, which could include image files and/or 
-    # snippets example cpp files 
+    # Get list of doxygen files, which could include image files and/or
+    # snippets example cpp files
     set(multiValueArgs
         DOXYGEN_FILES
     )
@@ -1317,4 +1323,27 @@ function(pxr_docs_only_dir NAME)
                 ${args_DOXYGEN_FILES}
         )
     endif()
-endfunction() # pxr_docs_only_dir
+endfunction() # pxr_docs_only_dir
+
+function(pxr_create_apple_framework)
+    # CMake can have a lot of different boolean representations, that need to be narrowed down
+    if (APPLE_EMBEDDED)
+        set(EMBEDDED_BUILD "true")
+    else()
+        set(EMBEDDED_BUILD "false")
+    endif()
+
+    _get_library_prefix(LIB_PREFIX)
+    if(TARGET usd_ms)
+        set(FRAMEWORK_ROOT_LIBRARY_NAME "${LIB_PREFIX}usd_ms.dylib")
+    else()
+        set(FRAMEWORK_ROOT_LIBRARY_NAME "${LIB_PREFIX}usd.dylib")
+    endif()
+
+    # Install the Info.plist and shell script
+    configure_file(cmake/resources/Info.plist.in "${PROJECT_BINARY_DIR}/Info.plist" @ONLY)
+    configure_file(cmake/resources/AppleFrameworkBuild.zsh.in "${PROJECT_BINARY_DIR}/AppleFrameworkBuild.zsh" @ONLY)
+
+    # Run the shell script for the primary configuration
+    install(CODE "execute_process(COMMAND zsh ${PROJECT_BINARY_DIR}/AppleFrameworkBuild.zsh )")
+endfunction() # pxr_create_apple_framework