Update the `Compiling with Mono` page

contributing/development/compiling/compiling_with_mono.rst

@@ -8,119 +8,73 @@ Compiling with Mono
 Requirements
 ------------
 
-- Mono 6.12.0 or greater (generally 64 bit)
-- MSBuild
-- NuGet
-- **On Linux/macOS only:** pkg-config
+- .NET SDK 6.0 or greater (generally 64 bit)
 
-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.
+You can use ``dotnet --version`` to check your .NET version.
 
 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.
+option ``module_mono_enabled=yes`` to the SCons command line, while otherwise
+following the instructions for building the desired Godot binaries.
 
 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.
+Parts of the sources of the managed libraries are generated from the ClassDB.
+These source files must be generated before building the managed libraries.
+They can be generated by any mono-enabled Godot editor binary by running it 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
+This command will tell Godot to generate the C# bindings for the Godot API at
+``modules/mono/glue/GodotSharp/GodotSharp/Generated``, and the C# bindings for
+the editor tools at ``modules/mono/glue/GodotSharp/GodotSharpEditor/Generated``.
+Once these files are generated, you can build Godot's managed libraries for all
+the desired targets without having to repeat this process.
+
+``<godot_binary>`` refers to the editor binary you compiled 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.
+
+.. note:: 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.
+
+Building the managed libraries
+------------------------------
+
+Once you have generated the Mono glue, you can builds the managed libraries 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::
+    ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin
 
-    scons p=<platform> target=template_release module_mono_enabled=yes
+If everything went well, the ``GodotSharp`` directory, containing the managed
+libraries, should have been created in the in the ``bin`` directory.
 
-If everything went well, apart from the normal output, SCons should have created
-the following files in the ``bin`` directory:
+.. note:: Due to NuGet package caching, rebuilding the managed libraries does
+          not reliably update all projects using them. To solve this issue
+          either use ``GODOT_VERSION_STATUS`` to give every build a unique
+          version or delete ``GodotNuGetFallbackFolder`` to clear the package
+          cache.
 
-- If you're not linking the Mono runtime statically, the build script will place
-  the Mono runtime shared library (``monosgen-2.0``) next to the Godot
-  binary in the output directory.
-  **Make sure to include this library when distributing the Godot editor or export templates.**
-  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.
-- Unlike "classical" Godot builds, when building with the Mono module enabled
-  (and depending on the target platform), a data directory may be created both
-  for the editor and for export templates. This directory is important for
-  proper functioning and must be distributed together with Godot.
-  More details about this directory in
-  :ref:`Data directory<compiling_with_mono_data_directory>`.
+Unlike "classical" Godot builds, when building with the Mono module enabled
+(and depending on the target platform), a data directory may be created both
+for the editor and for exported projects. This directory is important for
+proper functioning and must be distributed together with Godot.
+More details about this directory in
+:ref:`Data directory<compiling_with_mono_data_directory>`.
 
 Examples
 --------
@@ -132,37 +86,32 @@ Example (Windows)
 
     # Build editor binary
     scons p=windows target=editor module_mono_enabled=yes
+    # Build export templates
+    scons p=windows target=template_debug module_mono_enabled=yes
+    scons p=windows target=template_release module_mono_enabled=yes
+    
     # Generate glue sources
-    bin\godot.windows.editor.x86_64.mono --generate-mono-glue modules/mono/glue
+    bin/godot.windows.editor.x86_64.mono --generate-mono-glue modules/mono/glue
     # Build .NET assemblies
     ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=windows
 
-    ### Build binaries normally
-    # Editor
-    scons p=windows target=editor module_mono_enabled=yes
-    # Export templates
-    scons p=windows target=template_debug module_mono_enabled=yes
-    scons p=windows target=template_release module_mono_enabled=yes
 
 Example (Linux, \*BSD)
 ^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-    # Build temporary binary
+    # Build editor binary
     scons p=linuxbsd target=editor module_mono_enabled=yes
+    # Build export templates
+    scons p=linuxbsd target=template_debug module_mono_enabled=yes
+    scons p=linuxbsd target=template_release module_mono_enabled=yes
+
     # Generate glue sources
     bin/godot.linuxbsd.editor.x86_64.mono --generate-mono-glue modules/mono/glue
     # Generate binaries
     ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=linuxbsd
 
-    ### Build binaries normally
-    # Editor
-    scons p=linuxbsd target=editor module_mono_enabled=yes
-    # Export templates
-    scons p=linuxbsd target=template_debug module_mono_enabled=yes
-    scons p=linuxbsd target=template_release module_mono_enabled=yes
-
 .. _compiling_with_mono_data_directory:
 
 Data directory
@@ -172,197 +121,28 @@ 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
-^^^^^^^^^^^^^^^^
-
-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>.<arch>.<target>``, e.g. ``data.mono.linuxbsd.x86_32.release_debug`` or
-``data.mono.windows.x86_64.release``.
-
-This directory must be placed with its original name next to the Godot export
-templates. When exporting a project, Godot will also copy this directory with
-the game executable but the name will be changed to ``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:
-
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Mono/etc`` | ``/osx_template.app/Contents/Resources/GodotSharp/Mono/etc``  |
-+-------------------------------------------------------+---------------------------------------------------------------+
-
 Editor
 ^^^^^^
 
 The name of the data directory for the Godot editor will always be
-``GodotSharp``. The contents of this directory are the following:
-
-- ``Api``
-- ``Mono`` (optional)
-- ``Tools``
-
-The ``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:
-
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Api``      | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Api``      |
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Mono/lib`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Mono/etc`` | ``<bundle_name>.app/Contents/Resources/GodotSharp/Mono/etc``  |
-+-------------------------------------------------------+---------------------------------------------------------------+
-| ``bin/data.mono.<platform>.<arch>.<target>/Tools``    | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Tools``    |
-+-------------------------------------------------------+---------------------------------------------------------------+
-
-The ``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.
-
-The ``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.
-
-We recommend using these `build scripts <https://github.com/godotengine/godot-mono-builds>`_.
-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.
-
-Once you've built Mono, you can proceed to build Godot with the instructions
-described in this page and the
-:ref:`Compiling for Android<doc_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
-:ref:`Compiling for iOS<doc_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:
-
-::
-
-    #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.
-
-The following bash script will create the "fat" libraries in the directory ``#bin/ios/iphone-mono-libs``:
-
-::
-
-    mkdir -p bin/ios
-    mkdir -p bin/ios/iphone-mono-libs
-
-    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
-    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
-    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
-
-    # The Mono libraries for the interpreter are not available for simulator builds
-    lipo -create bin/libmono-ee-interp.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ee-interp.iphone.fat.a
-    lipo -create bin/libmono-icall-table.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-icall-table.iphone.fat.a
-    lipo -create bin/libmono-ilgen.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ilgen.iphone.fat.a
+``GodotSharp``. This directory contains an ``Api`` subdirectory with the Godot
+API assemblies and a ``Tools`` subdirectory with the tools required by the
+editor, like the ``GodotTools`` assemblies and its dependencies.
 
-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``.
+On macOS, if the Godot editor is distributed as a bundle, ``GodotSharp``
+directory may be placed in the ``<bundle_name>.app/Contents/Resources/``
+directory inside the bundle.
 
-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
-:ref:`Compiling for the Web<doc_compiling_for_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/``.
+Export templates
+^^^^^^^^^^^^^^^^
 
-In order to build the cross-compilers we recommend using these
-`build scripts <https://github.com/godotengine/godot-mono-builds>`_.
+The data directory for exported projects is generated by the editor during the
+export. It is named ``data_<APPNAME>_<ARCH>``, where ``<APPNAME>`` is the
+application name as specified in the project setting ``application/config/name``
+and ``<ARCH>`` is the current architecture of the export.
 
-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``.
+In the case of multi-architecture exports multiple such data directories will be
+generated.
 
 Command-line options
 --------------------
@@ -373,17 +153,3 @@ the Mono module:
 - **module_mono_enabled**\ =yes | **no**
 
   - Build Godot with the Mono module enabled.
-
-- **mono_prefix**\ =path
-
-  - Path to the Mono installation directory for the target platform and architecture.
-
-- **mono_static**\ =yes | no
-
-  - Whether to link the Mono runtime statically.
-  - The default is **yes** for iOS and WASM, and **no** for other platforms.
-
-- **copy_mono_root**\ =yes | **no**
-
-  - Whether to copy the Mono framework assemblies
-    and configuration files required by the Godot editor.