diff --git a/contributing/development/compiling/compiling_for_ios.rst b/contributing/development/compiling/compiling_for_ios.rst index 6cd9686f7..c5d370daf 100644 --- a/contributing/development/compiling/compiling_for_ios.rst +++ b/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 `__. @@ -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 + scons platform=ios target=template_release generate_bundle=yes -for a release build (check ``platform/ios/detect.py`` for the compiler -flags used for each configuration). - -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. +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). -:: - - 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. +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 --- diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst index 65ae80af5..ae6b2f5d6 100644 --- a/contributing/development/compiling/compiling_for_macos.rst +++ b/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=x86_64 - -- For Arm64 (Apple M1):: - - scons platform=macos target=template_release arch=arm64 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 -To support both architectures in a single "Universal 2" binary, run the above -two commands blocks and then use ``lipo`` to bundle them together:: +- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware):: - 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_debug arch=arm64 + 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 /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 ----------------------------------- diff --git a/tutorials/export/exporting_for_macos.rst b/tutorials/export/exporting_for_macos.rst index 1961338f4..ecafd0675 100644 --- a/tutorials/export/exporting_for_macos.rst +++ b/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 `__. +`Universal binaries for macOS support both Intel x86_64 and ARM64 (Apple Silicon) architectures `__. .. warning:: Due to file system limitations, raw ``.app`` bundles exported from Windows lack ``executable`` flag and won't run on macOS.