Merge pull request #10096 from Calinou/compiling-macos-ios-scons-generate-bundle

Document `generate_bundle=yes` SCons option in Compiling for macOS and iOS

Author: mhilbrunner

contributing/development/compiling/compiling_for_ios.rst

@@ -20,9 +20,6 @@ Requirements
       Xcode and need to install iOS support, go to *Xcode -> Settings... -> Platforms*.
     - Go to *Xcode -> Settings... -> Locations -> Command Line Tools* and select
       an installed version. Even if one is already selected, re-select it.
-
-If you are building the ``master`` branch:
-
 -  Download and follow README instructions to build a static ``.xcframework``
    from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
 
@@ -49,46 +46,40 @@ If you are building the ``master`` branch:
 Compiling
 ---------
 
-Open a Terminal, go to the root dir of the engine source code and type:
+Open a Terminal, go to the root folder of the engine source code and type
+the following to compile a debug build:
 
 ::
 
-    scons platform=ios target=template_debug
+    scons platform=ios target=template_debug generate_bundle=yes
 
-for a debug build, or:
+To compile a release build:
 
 ::
 
-    scons platform=ios target=template_release
-
-for a release build (check ``platform/ios/detect.py`` for the compiler
-flags used for each configuration).
+    scons platform=ios target=template_release generate_bundle=yes
 
-Alternatively, you can run
+Alternatively, you can run the following command for Xcode simulator libraries (optional):
 
 ::
 
-    scons platform=ios target=template_debug ios_simulator=yes arch=x86_64
     scons platform=ios target=template_debug ios_simulator=yes arch=arm64
+    scons platform=ios target=template_debug ios_simulator=yes arch=x86_64 generate_bundle=yes
 
-for a Simulator libraries.
+These simulator libraries cannot be used to run the exported project on the
+target device. Instead, they can be used to run the exported project directly on
+your Mac while still testing iOS platform-specific functionality.
 
 To create an Xcode project like in the official builds, you need to use the
 template located in ``misc/dist/ios_xcode``. The release and debug libraries
-should be placed in ``libgodot.ios.debug.xcframework`` and ``libgodot.ios.release.xcframework`` respectively.
-
-::
-
-    cp -r misc/dist/ios_xcode .
-
-    cp libgodot.ios.template_debug.arm64.a ios_xcode/libgodot.ios.debug.xcframework/ios-arm64/libgodot.a
-    lipo -create libgodot.ios.template_debug.arm64.simulator.a libgodot.ios.template_debug.x86_64.simulator.a -output ios_xcode/libgodot.ios.debug.xcframework/ios-arm64_x86_64-simulator/libgodot.a
-
-    cp libgodot.ios.template_release.arm64.a ios_xcode/libgodot.ios.release.xcframework/ios-arm64/libgodot.a
-    lipo -create libgodot.ios.template_release.arm64.simulator.a libgodot.ios.template_release.x86_64.simulator.a -output ios_xcode/libgodot.ios.release.xcframework/ios-arm64_x86_64-simulator/libgodot.a
-
-The MoltenVK static ``.xcframework`` folder must also be placed in the ``ios_xcode``
-folder once it has been created.
+should be placed in ``libgodot.ios.debug.xcframework`` and
+``libgodot.ios.release.xcframework`` respectively. This process can be automated
+by using the ``generate_bundle=yes`` option on the *last* SCons command used to
+build export templates (so that all binaries can be included).
+
+The MoltenVK static ``.xcframework`` folder must also be placed in the
+``ios_xcode`` folder once it has been created. MoltenVK is always statically
+linked on iOS; there is no dynamic linking option available, unlike macOS.
 
 Run
 ---

contributing/development/compiling/compiling_for_macos.rst

@@ -119,54 +119,46 @@ To build macOS export templates, you have to compile using the targets without
 the editor: ``target=template_release`` (release template) and
 ``target=template_debug``.
 
-Official templates are universal binaries which support both Intel x86_64 and
-ARM64 architectures. You can also create export templates that support only one
-of those two architectures by leaving out the ``lipo`` step below.
+Official templates are *Universal 2* binaries which support both ARM64 and Intel
+x86_64 architectures.
 
-- For Intel x86_64::
+- To support ARM64 (Apple Silicon) + Intel x86_64::
 
-    scons platform=macos target=template_release arch=x86_64
+    scons platform=macos target=template_debug arch=arm64
+    scons platform=macos target=template_release arch=arm64
     scons platform=macos target=template_debug arch=x86_64
+    scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
 
-- For Arm64 (Apple M1)::
+- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware)::
 
-    scons platform=macos target=template_release arch=arm64
     scons platform=macos target=template_debug arch=arm64
-
-To support both architectures in a single "Universal 2" binary, run the above
-two commands blocks and then use ``lipo`` to bundle them together::
-
-    lipo -create bin/godot.macos.template_release.x86_64 bin/godot.macos.template_release.arm64 -output bin/godot.macos.template_release.universal
-    lipo -create bin/godot.macos.template_debug.x86_64 bin/godot.macos.template_debug.arm64 -output bin/godot.macos.template_debug.universal
+    scons platform=macos target=template_release arch=arm64 generate_bundle=yes
 
 To create an ``.app`` bundle like in the official builds, you need to use the
-template located in ``misc/dist/macos_template.app``. The release and debug
-builds should be placed in ``macos_template.app/Contents/MacOS`` with the names
-``godot_macos_release.universal`` and ``godot_macos_debug.universal`` respectively. You can do so
-with the following commands (assuming a universal build, otherwise replace the
-``.universal`` extension with the one of your arch-specific binaries)::
-
-    cp -r misc/dist/macos_template.app .
-    mkdir -p macos_template.app/Contents/MacOS
-    cp bin/godot.macos.template_release.universal macos_template.app/Contents/MacOS/godot_macos_release.universal
-    cp bin/godot.macos.template_debug.universal macos_template.app/Contents/MacOS/godot_macos_debug.universal
-    chmod +x macos_template.app/Contents/MacOS/godot_macos*
+template located in ``misc/dist/macos_template.app``. This process can be automated by using
+the ``generate_bundle=yes`` option on the *last* SCons command used to build export templates
+(so that all binaries can be included). This option also takes care of calling ``lipo`` to create
+an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both were compiled beforehand).
 
 .. note::
 
-    If you are building the ``master`` branch, you also need to include support
-    for the MoltenVK Vulkan portability library. By default, it will be linked
-    statically from your installation of the Vulkan SDK for macOS.
-    You can also choose to link it dynamically by passing ``use_volk=yes`` and
-    including the dynamic library in your ``.app`` bundle::
+    You also need to include support for the MoltenVK Vulkan portability
+    library. By default, it will be linked statically from your installation of
+    the Vulkan SDK for macOS. You can also choose to link it dynamically by
+    passing ``use_volk=yes`` and including the dynamic library in your ``.app``
+    bundle::
 
         mkdir -p macos_template.app/Contents/Frameworks
         cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib
 
+    In most cases, static linking should be preferred as it makes distribution
+    easier. The main upside of dynamic linking is that it allows updating
+    MoltenVK without having to recompile export templates.
+
 You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip``
 template from the official Godot distribution::
 
-    zip -q -9 -r macos.zip macos_template.app
+    zip -r9 macos.zip macos_template.app
 
 Using Pyston for faster development
 -----------------------------------

tutorials/export/exporting_for_macos.rst

@@ -11,7 +11,7 @@ Exporting for macOS
 
 macOS apps exported with the official export templates are exported as a single "Universal 2" binary ``.app`` bundle, a folder with a specific structure which stores the executable, libraries and all the project files.
 This bundle can be exported as is, packed in a ZIP archive or DMG disk image (only supported when exporting from a computer running macOS).
-`Universal binaries for macOS support both Intel x86_64 and ARM64 (Apple silicon, i.e. M1) architectures <https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary>`__.
+`Universal binaries for macOS support both Intel x86_64 and ARM64 (Apple Silicon) architectures <https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary>`__.
 
 .. warning::
     Due to file system limitations, raw ``.app`` bundles exported from Windows lack ``executable`` flag and won't run on macOS.