Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

为 macOS 平台编译

备注

这个页面描述的是如何从源码编译 macOS 编辑器和导出模板二进制文件。如果你要找的是导出项目到 macOS,请阅读 为 macOS 导出

需求

在 macOS 下编译时,需要以下条件:

备注

If you have Homebrew installed, you can easily install SCons using the following command:

brew install scons

如果你还没有 Xcode 命令行工具,安装 Homebrew 也会自动进行获取。

Similarly, if you have MacPorts installed, you can easily install SCons using the following command:

sudo port install scons

参见

要获取编译所需的 Godot 源码,请参阅 获取源代码

有关 Godot 的 SCons 用法的一般概述,请参阅 构建系统介绍

编译

启动终端, 进入引擎源代码的根目录.

若要为英特尔(x86-64)架构的 Mac 编译,请使用:

scons platform=macos arch=x86_64

要为 Apple Silicon(ARM64)驱动的 Mac 编译,请使用:

scons platform=macos arch=arm64

如果要通过“Universal 2”二进制来同时支持这两种架构,请运行上述两个命令,然后使用 lipo 将它们打包在一起:

lipo -create bin/godot.macos.tools.x86_64 bin/godot.macos.tools.arm64 -output bin/godot.macos.tools.universal

If all goes well, the resulting binary executable will be placed in the bin/ subdirectory. This executable file contains the whole engine and runs without any dependencies. Executing it will bring up the Project Manager.

备注

如果你想为自己的 Godot 构建和官方发布使用单独的编辑器设置,你可以通过在 bin/ 文件夹中创建一个名为 ._sc__sc_ 的文件来启用 自包含模式

To create an .app bundle like in the official builds, you need to use the template located in misc/dist/macos_tools.app. Typically, for an optimized editor binary built with target=release_debug:

cp -r misc/dist/macos_tools.app ./Godot.app
mkdir -p Godot.app/Contents/MacOS
cp bin/godot.macos.tools.universal Godot.app/Contents/MacOS/Godot
chmod +x Godot.app/Contents/MacOS/Godot
codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - Godot.app

备注

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:

mkdir -p Godot.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib

Running a headless/server build

To run in headless mode which provides editor functionality to export projects in an automated manner, use the normal build:

scons platform=macos target=editor

And then use the --headless command line argument:

./bin/godot.macos.editor.x86_64 --headless

如果要编译调试版本的服务器,支持远程调试工具,那么请使用:

scons platform=macos target=template_debug

如果要编译发布版本的服务器,针对运行专门的游戏服务器进行优化,那么请使用:

scons platform=macos target=template_release production=yes

构建导出模板

To build macOS export templates, you have to compile using the targets without the editor: target=template_release (release template) and target=template_debug.

官方模板是通用的二进制文件,同时支持英特尔x86_64和ARM64架构。你也可以通过省略下面的 lipo 步骤,创建只支持架构中的一种的导出模板。

  • 对于英特尔 x86_64:

    scons platform=macos target=template_release arch=x86_64
    scons platform=macos target=template_debug arch=x86_64
    
  • 对于 ARM64(Apple M1):

    scons platform=macos target=template_release arch=arm64
    scons platform=macos target=template_debug arch=arm64
    

要使用“Universal 2”二进制来同时支持这两种架构,请运行上述两个命令块,然后使用 lipo 将它们捆绑在一起:

lipo -create bin/godot.macos.opt.x86_64 bin/godot.macos.opt.arm64 -output bin/godot.macos.opt.universal
lipo -create bin/godot.macos.opt.debug.x86_64 bin/godot.macos.opt.debug.arm64 -output bin/godot.macos.opt.debug.universal

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.64 and godot_macos_debug.64 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.opt.universal macos_template.app/Contents/MacOS/godot_macos_release.64
cp bin/godot.macos.opt.debug.universal macos_template.app/Contents/MacOS/godot_macos_debug.64
chmod +x macos_template.app/Contents/MacOS/godot_macos*

备注

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:

mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib

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

使用 Pyston 加快开发速度

You can use Pyston to run SCons. Pyston is a JIT-enabled implementation of the Python language (which SCons is written in). Its "full" version is currently only compatible with Linux, but Pyston-lite is also compatible with macOS (both x86 and ARM). Pyston can speed up incremental builds significantly, often by a factor between 1.5× and 2×. Pyston can be combined with alternative linkers such as LLD or Mold to get even faster builds.

To install Pyston-lite, run python -m pip install pyston_lite_autoload then run SCons as usual. This will automatically load a subset of Pyston's optimizations in any Python program you run. However, this won't bring as much of a performance improvement compared to installing "full" Pyston (which currently can't be done on macOS).

从 Linux 交叉编译 macOS

在Linux环境下为macOS进行编译是可行的(也许也可以在Windows中使用Windows Subsystem for Linux). 为此, 你需要安装 OSXCross , 以便能够使用macOS作为目标. 首先, 按照说明来安装它:

在你的机器上某处克隆 OSXCross 资源库(或者下载一个 ZIP 文件并解压缩),例如:

git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
  1. 按照说明打包SDK:https://github.com/tpoechtrager/osxcross#packaging-the-sdk

  2. 按照说明安装OSXCross:https://github.com/tpoechtrager/osxcross#installation

然后,你需要将 OSXCROSS_ROOT 定义为 OSXCross 的安装路径(与你克隆软件库/提取压缩包的地方相同),例如:

export OSXCROSS_ROOT="$HOME/osxcross"

现在你可以像平时一样用 SCons 进行编译:

scons platform=macos

如果你的 OSXCross SDK 版本与 SCons 构建系统所期望的不同,你可以用 osxcross_sdk 参数指定一个自定义的版本:

scons platform=macos osxcross_sdk=darwin15