使用Mono编译

需求

  • Mono 5.12.0或以上版本
  • MSBuild
  • NuGet
  • On Linux/macOS only: pkg-config

您可能需要导入必要的证书，以使NuGet执行HTTPS请求。

The recommended method is to use curl‘s CA (Certificate Autorities) certificate bundle.

Run the following commands to download and import it. On Windows, you can run it from the Mono command line prompt (or the regular prompt if you added Mono’s bin directory to your PATH environment variable):

  1. # If using PowerShell, replace `curl` with `curl.exe` below.
  2. curl -LO https://curl.haxx.se/ca/cacert.pem
  3. cert-sync --user cacert.pem

Alternatively, you can use the following command, though it’s deprecated and may not work correctly:

  1. mozroots --import --sync

环境变量

默认情况下，SCons会尝试在Windows上的Windows注册表中或通过其他平台上的 pkg-config 找到Mono。您可以通过将 mono_prefix 命令行选项传递给SCons来指定其他安装目录。如， scons [...] mono_prefix=%ProgramFiles%/Mono。

这是包含子目录 include 和 lib 的目录。

启用 Mono 模块

默认情况下，构建时禁用Mono模块。要启用它，请将选项 module_mono_enabled=yes 添加到SCons命令行。

生成胶水代码

胶水源码是包装函数，将被管理的方法调用。必须在构建最终二进制文件之前生成这些源文件。为了生成它们，首先，您必须使用选项 tools=yes 和 mono_glue=no 构建一个临时的Godot二进制文件：

  1. scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no

构建完成后，您需要运行带有参数 --generate-mono-glue 的编译后的可执行文件，后跟输出目录的路径。在Godot目录中，此路径必须是 modules/mono/glue：

  1. <godot_binary> --generate-mono-glue modules/mono/glue

这个命令告诉 Godot 在 modules/mono/glue/Managed/Generated 生 modules/mono/glue/mono_glue.gen.cpp 文件和C#代码。生成这些文件后，您可以为所有所需目标构建Godot，而无需重复此过程。

<godot_binary> refers to the tools binary you compiled above with the Mono module enabled. Its exact name will differ based on your system and configuration, but should be of the form bin/godot.<platform>.tools.<bits>.mono, e.g. bin/godot.x11.tools.64.mono or bin/godot.windows.tools.64.mono.exe. Be especially aware of the .mono suffix! If you’ve previously compiled Godot without Mono support, you might have similarly named binaries without this suffix. These binaries can’t be used to generate the Mono glue.

注意

  • 不要使用 mono_glue=no 来构建您的发布版 Godot。 此选项会禁用C#脚本，它仅用于控制生成胶水代码的临时二进制文件。如果Godot是在没有胶水源码的情况下构建的，它将在启动时打印一条警告。
  • 每次ClassDB注册的API更改时，都必须重新生成胶水源码。即，例如，当将新方法注册到脚本API时，或该方法的参数之一发生更改时。如果ClassDB和胶水源码之间的API不匹配，Godot将在启动时打印一条错误。

用Mono胶水代码重构

一旦您生成了Mono胶水代码，就可以使用 mono_glue=yes 构建最终的二进制文件。这是 mono_glue 的默认值，所以您也可以省略它。您可以构建启用Mono的编辑器：

  1. scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=yes

启用Mono的导出模板：

  1. scons p=<platform> tools=no module_mono_enabled=yes mono_glue=yes

如果一切正常，除了正常的输出，SCons应该在 bin 目录中创建了以下文件：

  • 如果您不是静态链接Mono运行时，则构建脚本会将Mono运行时共享库（monosgen-2.0）放置在输出目录中的Godot二进制文件旁边。分发Godot时，请确保包括此库。以Android为目标平台时，不需要任何额外的步骤，因为该库会自动复制到 #platform/android/java/libs，而Gradle会处理其余的工作。
  • 与“经典”Godot构建不同，在启用Mono模块（取决于目标平台）的情况下构建时，将为编辑器和导出模板两者一块创建数据目录。 该目录对于正常运行很重要，必须与Godot一起分发。 有关此目录的更多详细信息，参见 Data directory 。

示例

示例（Windows）

  1. # Build temporary binary
  2. scons p=windows tools=yes module_mono_enabled=yes mono_glue=no
  3. # Generate glue sources
  4. bin\godot.windows.tools.64.mono --generate-mono-glue modules/mono/glue
  6. ### Build binaries normally
  7. # Editor
  8. scons p=windows target=release_debug tools=yes module_mono_enabled=yes
  9. # Export templates
  10. scons p=windows target=release_debug tools=no module_mono_enabled=yes
  11. scons p=windows target=release tools=no module_mono_enabled=yes

示例（x11）

  1. # Build temporary binary
  2. scons p=x11 tools=yes module_mono_enabled=yes mono_glue=no
  3. # Generate glue sources
  4. bin/godot.x11.tools.64.mono --generate-mono-glue modules/mono/glue
  6. ### Build binaries normally
  7. # Editor
  8. scons p=x11 target=release_debug tools=yes module_mono_enabled=yes
  9. # Export templates
  10. scons p=x11 target=release_debug tools=no module_mono_enabled=yes
  11. scons p=x11 target=release tools=no module_mono_enabled=yes

数据目录

数据目录是启用了Mono模块的Godot二进制文件的依赖项。它包含对Godot正确运行的重要文件。它必须与Godot可执行文件一起分发。

注解

The information below doesn’t apply for Android, iOS and WASM, as there is no data directory for these platforms.

导出模板

The name of the data directory for an export template differs based on the configuration it was built with. The format is data.mono.<platform>.<bits>.<target>, e.g. data.mono.x11.32.release_debug or data.mono.windows.64.release.

必须以其原始名称将该目录放置在Godot导出模板旁边。导出项目时，Godot还会将此目录与游戏可执行文件一起复制，但名称将更改为 data_<APPNAME> ，其中 <APPNAME> 是项目设置 application/config/name 中指定的应用程序名称。

对于macOS，将导出模板压缩为ZIP存档，则数据目录的内容可以放置在ZIP存档内的以下位置：

bin/data.mono.<platform>.<bits>.<target>/Mono/lib/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib
bin/data.mono.<platform>.<bits>.<target>/Mono/etc/osx_template.app/Contents/Resources/GodotSharp/Mono/etc

编辑器

Godot编辑器的数据目录名称将始终为 GodotSharp。该目录的内容如下：

  • Api
  • Mono （可选）
  • Tools

Api 子目录包含Godot API程序集。在macOS上，如果Godot编辑器作为捆绑分发，则数据目录的内容可能位于以下位置：

bin/data.mono.<platform>.<bits>.<target>/Api<bundle_name>.app/Contents/Frameworks/GodotSharp/Api
bin/data.mono.<platform>.<bits>.<target>/Mono/lib<bundle_name>.app/Contents/Frameworks/GodotSharp/Mono/lib
bin/data.mono.<platform>.<bits>.<target>/Mono/etc<bundle_name>.app/Contents/Resources/GodotSharp/Mono/etc
bin/data.mono.<platform>.<bits>.<target>/Tools<bundle_name>.app/Contents/Frameworks/GodotSharp/Tools

Mono 子目录是可选的。分发编辑器时将需要它，因为当用户安装的Mono版本与构建Godot编辑器的版本不同时会出现问题。生成编辑器时，将 copy_mono_root=yes 传递给SCons以便创建此文件夹及其内容。

Tools 子目录包含编辑器所需的工具，如 GodotTools 程序集及其依赖项。

Building the Mono runtime

When building Godot for the desktop, you will likely use the pre-built Mono runtime that is installed on your system. This likely won’t be the case when targeting other platforms like Android, iOS and WebAssembly. You will have to build the Mono runtime yourself for those platforms.

We recommend using these build scripts. They simplify this process but also include some patches needed for proper functioning with Godot. See the README on the link above for instructions on how to use the scripts.

目标平台为Android

与为其他平台构建相比，使用Mono为Android编译导出模板要简单一些，因为构建后无需其他步骤。无需担心运行时依赖项，例如数据目录或共享库（动态链接时），因为它们会自动添加到Gradle项目中。

Once you’ve built Mono, you can proceed to build Godot with the instructions described in this page and the Compiling for Android page. Make sure to let SCons know about the location of the Mono runtime you’ve just built, e.g.: scons [...] mono_prefix="$HOME/mono-installs/android-armeabi-v7a-release" (This path may be different on your system).

Targeting iOS

Once you’ve built Mono, you can proceed to build Godot with the instructions described in this page and the Compiling for iOS page. Make sure to let SCons know about the location of the Mono runtime you’ve just built, e.g.: scons [...] mono_prefix="$HOME/mono-installs/ios-arm64-release" (This path may be different on your system).

After building Godot for each architecture, you will notice SCons has copied the Mono libraries for each of them to the output directory:

  1. #bin/libmono-native.iphone.<arch>.a
  2. #bin/libmonosgen-2.0.iphone.<arch>.a
  3. #bin/libmonoprofiler-log.iphone.<arch>.a
  5. #bin/libmono-ilgen.iphone.<arch>.a
  6. #bin/libmono-ee-interp.iphone.<arch>.a
  7. #bin/libmono-icall-table.iphone.<arch>.a

The last three are only for iOS devices and are not available for the iOS simulator.

These libraries must be put in universal (multi-architecture) “fat” files to be distributed with the export templates.

The following bash script will create the “fat” libraries in the directory #bin/ios/iphone-mono-libs:

  1. mkdir -p bin/ios
  2. mkdir -p bin/ios/iphone-mono-libs
  4. lipo -create bin/libmonosgen-2.0.iphone.arm64.a bin/libmonosgen-2.0.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmonosgen-2.0.iphone.fat.a
  5. lipo -create bin/libmono-native.iphone.arm64.a bin/libmono-native.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmono-native.iphone.fat.a
  6. lipo -create bin/libmono-profiler-log.iphone.arm64.a bin/libmono-profiler-log.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmono-profiler-log.iphone.fat.a
  8. # The Mono libraries for the interpreter are not available for simulator builds
  9. lipo -create bin/libmono-ee-interp.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ee-interp.iphone.fat.a
  10. lipo -create bin/libmono-icall-table.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-icall-table.iphone.fat.a
  11. lipo -create bin/libmono-ilgen.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ilgen.iphone.fat.a

The iphone-mono-libs folder must be distributed with the export templates. The Godot editor will look for the libraries in <templates>/iphone-mono-libs/lib<name>.iphone.fat.a.

Targeting WebAssembly

Building for WebAssembly currently involves the same process regardless of whether the Mono module is enabled.

Once you’ve built Mono, you can proceed to build Godot with the instructions described in this page and the Compiling for the Web page. Make sure to let SCons know about the location of the Mono runtime you’ve just built, e.g.: scons [...] mono_prefix="$HOME/mono-installs/wasm-runtime-release" (This path may be different on your system).

Base Class Library

The export templates must also include the BCL (Base Class Library) for each target platform. Godot looks for the BCL folder at <templates>/bcl/<target_platform>, where <target_platform> is the same name passed to the SCons platform option, e.g.: <templates>/bcl/windows, <templates>/bcl/javascript.

Alternatively, Godot will look for them in the following locations:

Android<templates>/bcl/monodroid
iOS<templates>/bcl/monotouch
WebAssembly<templates>/bcl/wasm
Linux and macOS<templates>/bcl/net_4_x
Windows<templates>/bcl/net_4_x_win

As of now, we’re assuming the same BCL profile can be used for both Linux and macOS, but this may change in the future as they’re not guaranteed to be the same (as is the case with the Windows BCL).

If the target platform is the same as the platform of the Godot editor, then the editor will use the BCL it’s running on (<data_folder>/Mono/lib/mono/4.5) if it cannot find the BCL in the export templates.

AOT cross-compilers

To perform ahead-of-time (AOT) compilation for other platforms, Godot needs to have access to the Mono cross-compilers for that platform and architecture.

Godot will look for the cross-compiler executable in the AOT compilers folder. The location of this folder is <data_folder>/Tools/aot-compilers/.

In order to build the cross-compilers we recommend using these build scripts.

After building them, copy the executable to the Godot AOT compilers directory. The executable name is <triple>-mono-sgen, e.g.: aarch64-apple-darwin-mono-sgen.

命令行选项

以下是使用Mono模块进行构建时可用的命令行选项的列表：

  • module_mono_enabled\=yes | no
    • 在启用Mono模块的情况下构建Godot。
  • mono_glue\=yes | no
    • 是否在构建中包括胶水源文件，并将 MONO_GLUE_DISABLED 定义为预处理器宏。
  • mono_prefix\=path
    • 目标平台和体系结构的Mono安装目录的路径。
  • xbuild_fallback\=yes | no
    • 如果MSBuild不可用，是否回退到xbuild。
  • mono_static\=yes | no
    • 是否静态链接Mono运行时。
    • The default is yes for iOS and WASM, and no for other platforms.
  • copy_mono_root\=yes | no
    • 是否复制Godot编辑器所需的Mono框架程序集和配置文件。