Compiling with Mono

Requirements

  • Mono 6.12.0 or greater
  • MSBuild
  • NuGet
  • On Linux/macOS only: pkg-config You may need to import necessary certificates for NuGet to perform HTTPS requests. curl‘s CA (Certificate Authorities) certificate bundle. bin directory to your PATH environment variable):
    1. # If using PowerShell, replace `curl` with `curl.exe` below.curl -LO https://curl.haxx.se/ca/cacert.pemcert-sync --user cacert.pem
    Alternatively, you can use the following command, though it’s deprecated and may not work correctly:
    1. mozroots --import --sync

    Environment variables

    pkg-config on other platforms. You can specify a different installation directory by passing the mono_prefix command-line option to SCons; e.g. scons [...] mono_prefix=%ProgramFiles%/Mono. include and lib.

    Enable the Mono module

    module_mono_enabled=yes to the SCons command line.

    Generate the glue

    tools=yes and mono_glue=no:
    1. scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no
    --generate-mono-glue followed by the path to an output directory. This path must be modules/mono/glue in the Godot directory:
    1. <godot_binary> --generate-mono-glue modules/mono/glue
    modules/mono/glue/mono_glue.gen.cpp, the C# solution for the Godot API at modules/mono/glue/GodotSharp/GodotSharp/Generated, and the C# solution for the editor tools at modules/mono/glue/GodotSharp/GodotSharpEditor/Generated. Once these files are generated, you can build Godot for all the desired targets without having to repeat this process. <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.

    Notes

  • Do not build your final binaries with mono_glue=no. This disables C# scripting. This option must be used only for the temporary binary that will generate the glue. Godot will print a warning at startup if it was built without the glue sources.
  • The glue sources must be regenerated every time the ClassDB-registered API changes. That is, for example, when a new method is registered to the scripting API or one of the parameters of such a method changes. Godot will print an error at startup if there is an API mismatch between ClassDB and the glue sources.

    Rebuild with Mono glue

    mono_glue=yes. This is the default value for mono_glue, so you can also omit it. To build a Mono-enabled editor:
    1. scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=yes
    And Mono-enabled export templates:
    1. scons p=<platform> tools=no module_mono_enabled=yes mono_glue=yes
    bin directory:
  • monosgen-2.0) next to the Godot binary in the output directory. Make sure to include this library when distributing Godot. When targeting Android, no extra steps are required as this library is automatically copied to #platform/android/java/libs and Gradle takes care of the rest.
  • Data directory.

    Examples

    Example (Windows)

    1. # Build temporary binaryscons p=windows tools=yes module_mono_enabled=yes mono_glue=no# Generate glue sourcesbin\godot.windows.tools.64.mono --generate-mono-glue modules/mono/glue### Build binaries normally# Editorscons p=windows target=release_debug tools=yes module_mono_enabled=yes# Export templatesscons p=windows target=release_debug tools=no module_mono_enabled=yesscons p=windows target=release tools=no module_mono_enabled=yes

    Example (X11)

    1. # Build temporary binaryscons p=x11 tools=yes module_mono_enabled=yes mono_glue=no# Generate glue sourcesbin/godot.x11.tools.64.mono --generate-mono-glue modules/mono/glue### Build binaries normally# Editorscons p=x11 target=release_debug tools=yes module_mono_enabled=yes# Export templatesscons p=x11 target=release_debug tools=no module_mono_enabled=yesscons p=x11 target=release tools=no module_mono_enabled=yes

    Data directory

    The data directory is a dependency for Godot binaries built with the Mono module enabled. It contains important files for the correct functioning of Godot. It must be distributed together with the Godot executable. Note The information below doesn’t apply for Android, iOS and WASM, as there is no data directory for these platforms.

    Export templates

    data.mono.<platform>.<bits>.<target>, e.g. data.mono.x11.32.release_debug or data.mono.windows.64.release. data_<APPNAME>, where <APPNAME> is the application name as specified in the project setting application/config/name. In the case of macOS, where the export template is compressed as a ZIP archive, the contents of the data directory can be placed in the following locations inside the ZIP archive:

    Editor

    GodotSharp. The contents of this directory are the following:
  • Api
  • Mono (optional)
  • Tools Api subdirectory contains the Godot API assemblies. On macOS, if the Godot editor is distributed as a bundle, the contents of the data directory may be placed in the following locations: Mono subdirectory is optional. It will be needed when distributing the editor, as issues can arise when the user-installed Mono version isn’t identical to the one the Godot editor was built with. Pass copy_mono_root=yes to SCons when building the editor in order to create this folder and its contents. Tools subdirectory contains tools required by the editor, like the GodotTools assemblies and its dependencies.

    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. 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.

    Targeting Android

    Compiling the Android export templates with Mono is a bit simpler than it is for the desktop platforms, as there are no additional steps required after building. There is no need to worry about run-time dependencies like a data directory or the shared library (when dynamically linking) as those are automatically added to the Gradle project. 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

    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#bin/libmonosgen-2.0.iphone.<arch>.a#bin/libmonoprofiler-log.iphone.<arch>.a#bin/libmono-ilgen.iphone.<arch>.a#bin/libmono-ee-interp.iphone.<arch>.a#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. #bin/ios/iphone-mono-libs:
    1. mkdir -p bin/iosmkdir -p bin/ios/iphone-mono-libslipo -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.alipo -create bin/libmono-native.iphone.arm64.a bin/libmono-native.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmono-native.iphone.fat.alipo -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# The Mono libraries for the interpreter are not available for simulator buildslipo -create bin/libmono-ee-interp.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ee-interp.iphone.fat.alipo -create bin/libmono-icall-table.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-icall-table.iphone.fat.alipo -create bin/libmono-ilgen.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ilgen.iphone.fat.a
    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. 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

    <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: 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). <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. <data_folder>/Tools/aot-compilers/. build scripts. <triple>-mono-sgen, e.g.: aarch64-apple-darwin-mono-sgen.

    Command-line options

    The following is the list of command-line options available when building with the Mono module:
  • module_mono_enabled\=yes | no

-

  • mono_glue\=yes | no

  • MONO_GLUE_DISABLED as a preprocessor macro.

  • mono_prefix\=path

-

  • mono_static\=yes | no

  • Whether to link the Mono runtime statically.

  • yes for iOS and WASM, and no for other platforms.
  • copy_mono_root\=yes | no

-