Compiling with Mono

Requirements

  • Mono 6.12.0 or greater (generally 64 bit)

  • MSBuild

  • NuGet

  • On Linux/macOS only: pkg-config

You can use mono -V to check your Mono version. A build error like the one below may indicate your Mono version is too old:

'mono_runtime_set_pending_exception': identifier not found

You may need to import necessary certificates for NuGet to perform HTTPS requests.

The recommended method is to use curl's CA (Certificate Authorities) 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):

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

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

mozroots --import --sync

Environment variables

By default, SCons will try to find Mono in the Windows Registry on Windows or via 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.

This is the directory that contains the subdirectories include and lib. Note that as usual, paths including spaces must be wrapped in double quotes.

Enable the Mono module

By default, the Mono module is disabled when building. To enable it, add the option module_mono_enabled=yes to the SCons command line.

Generate the glue

Glue sources are the wrapper functions that will be called by managed methods. These source files must be generated before building your final binaries. In order to generate them, first, you must build a temporary Godot binary with the options target=editor:

scons p=<platform> target=editor module_mono_enabled=yes

After the build finishes, you need to run the compiled executable with the parameters --headless --generate-mono-glue followed by the path to an output directory. This path must be modules/mono/glue in the Godot directory:

<godot_binary> --headless --generate-mono-glue modules/mono/glue

This command will tell Godot to generate the file 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 editor 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>.editor.<arch>.mono, e.g. bin/godot.linuxbsd.editor.x86_64.mono or bin/godot.windows.editor.x86_32.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

  • 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

Once you have generated the Mono glue, you can generate the final binary with the build_assemblies.py script.:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform={PLATFORM_NAME}

And Mono-enabled export templates:

scons p=<platform> target=template_release module_mono_enabled