mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-04 14:11:02 +03:00
Merge pull request #2646 from Calinou/improve-compiling-with-mono
Improve writing style in "Compiling with Mono"
This commit is contained in:
Rémi Verschelde
GitHub
@@ -13,92 +13,99 @@ Requirements
|
||||
- NuGet
|
||||
- pkg-config
|
||||
|
||||
You may need to import necessary certificates for NuGet to perform HTTPS requests. You can do this
|
||||
with the following command (on Windows, you can run it from the Mono command line prompt):
|
||||
|
||||
::
|
||||
You may need to import necessary certificates for NuGet to perform HTTPS
|
||||
requests. You can do this with the following command (on Windows, you can run it
|
||||
from the Mono command line prompt)::
|
||||
|
||||
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``.
|
||||
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``.
|
||||
|
||||
Enable the Mono module
|
||||
----------------------
|
||||
|
||||
By default, the mono module is disabled for builds. To enable it you can pass the
|
||||
option ``module_mono_enabled=yes`` to your SCons command.
|
||||
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
|
||||
-------------------
|
||||
|
||||
The 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 ``tools=yes`` and ``mono_glue=no``:
|
||||
|
||||
::
|
||||
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 ``tools=yes`` and ``mono_glue=no``::
|
||||
|
||||
scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no
|
||||
|
||||
After the build finishes, you need to run the compiled executable with the parameter
|
||||
``--generate-mono-glue`` followed by the path to an output directory. This path
|
||||
must be ``modules/mono/glue`` in the Godot directory.
|
||||
|
||||
::
|
||||
After the build finishes, you need to run the compiled executable with the
|
||||
parameter ``--generate-mono-glue`` followed by the path to an output directory.
|
||||
This path must be ``modules/mono/glue`` in the Godot directory::
|
||||
|
||||
<godot_binary> --generate-mono-glue modules/mono/glue
|
||||
|
||||
This command will tell Godot to generate the file ``modules/mono/glue/mono_glue.gen.cpp``
|
||||
and the C# solution for the Godot API at ``modules/mono/glue/Managed/Generated``.
|
||||
Once these files are generated, you can build Godot for all the desired targets without the need to repeat this process.
|
||||
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.exe``.
|
||||
Be especially aware of the **.mono** suffix! If you compiled Godot without Mono support previously,
|
||||
you might have similarly named binaries without this suffix which can't be used to generate the Mono glue.
|
||||
``<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.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 parameter of such a method changes.
|
||||
Godot will print an error at startup if there is an API mismatch between ClassDB and the glue sources.
|
||||
- **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
|
||||
----------------------
|
||||
|
||||
Once you have generated the Mono glue, you can build the final binary with ``mono_glue=yes``.
|
||||
This is the default value for ``mono_glue`` so you can also omit it. You can build the Mono-enabled editor:
|
||||
|
||||
::
|
||||
Once you have generated the Mono glue, you can build the final binary with
|
||||
``mono_glue=yes``. This is the default value for ``mono_glue``, so you can also
|
||||
omit it. To build a Mono-enabled editor::
|
||||
|
||||
scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=yes
|
||||
|
||||
And Mono-enabled export templates:
|
||||
|
||||
::
|
||||
And Mono-enabled export templates::
|
||||
|
||||
scons p=<platform> tools=no module_mono_enabled=yes mono_glue=yes
|
||||
|
||||
If everything went well, apart from the normal output SCons should have created the following files in the ``bin`` directory:
|
||||
|
||||
- If you're not static linking the Mono runtime, the build script will place the Mono runtime shared library (``monosgen-2.0``) next
|
||||
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.
|
||||
- Unlike "classical" Godot builds, when building with the mono module enabled and depending of 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>`.
|
||||
If everything went well, apart from the normal output, SCons should have created
|
||||
the following files in the ``bin`` directory:
|
||||
|
||||
- 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 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.
|
||||
- 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>`.
|
||||
|
||||
Examples
|
||||
--------
|
||||
@@ -140,23 +147,30 @@ Example (X11)
|
||||
Data directory
|
||||
--------------
|
||||
|
||||
The data directory is a dependency for Godot binaries built with the mono module enabled. It contains files
|
||||
that are important for the correct functioning of Godot. It must be distributed together with the Godot executable.
|
||||
This information does not apply for ``Android`` as there is no data directory for that platform.
|
||||
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 to Android, as there is
|
||||
no data directory for that platform.
|
||||
|
||||
Export templates
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The name of the data directory for a 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.debug`` or ``data.mono.windows.64.release``.
|
||||
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.debug`` or
|
||||
``data.mono.windows.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``.
|
||||
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 file, the
|
||||
contents of the data directory can be placed in the following locations inside the zip:
|
||||
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>.<bits>.<target>/Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
|
||||
@@ -167,15 +181,16 @@ contents of the data directory can be placed in the following locations inside t
|
||||
Editor
|
||||
^^^^^^^^
|
||||
|
||||
The name of the data directory for the Godot editor will always be ``GodotSharp``.
|
||||
The contents of this directory are the following:
|
||||
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.
|
||||
In the case of macOS, if the Godot editor is distributed as a bundle, the contents of the data directory may be placed in the following locations:
|
||||
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>.<bits>.<target>/Api`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Api`` |
|
||||
@@ -187,44 +202,58 @@ In the case of macOS, if the Godot editor is distributed as a bundle, the conten
|
||||
| ``bin/data.mono.<platform>.<bits>.<target>/Tools`` | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Tools`` |
|
||||
+-------------------------------------------------------+---------------------------------------------------------------+
|
||||
|
||||
The ``Mono`` subdirectory is optional but will be needed when distributing the editor, as some issues might arise
|
||||
when the installed Mono version in the user's system is not be the same as 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 ``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.
|
||||
The ``Tools`` subdirectory contains tools required by the editor, like the
|
||||
``GodotTools`` assemblies and its dependencies.
|
||||
|
||||
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 any
|
||||
dependency like a data directory or the runtime shared library (when dynamically linking) as
|
||||
those are automatically added to the gradle project.
|
||||
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.
|
||||
|
||||
Before building Godot you do need to cross compile the Mono runtime for the target architectures.
|
||||
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.
|
||||
Read the README for instructions on how to use the scripts.
|
||||
Before building Godot, you need to cross compile the Mono runtime for the target
|
||||
architectures. 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.
|
||||
|
||||
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 just built:
|
||||
``scons [...] mono_prefix=$HOME/mono-installs/android-armeabi-v7a-release``
|
||||
(This path may be different on your system depending on the options you used to build Mono).
|
||||
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:
|
||||
``scons [...] mono_prefix="$HOME/mono-installs/android-armeabi-v7a-release"``
|
||||
(This path may be different on your system, depending on the options you used
|
||||
to build Mono).
|
||||
|
||||
Command-line options
|
||||
--------------------
|
||||
|
||||
The following is the list of command-line options available when building with the mono module:
|
||||
The following is the list of command-line options available when building with
|
||||
the Mono module:
|
||||
|
||||
- **module_mono_enabled**: Build Godot with the mono module enabled ( yes | **no** )
|
||||
- **module_mono_enabled**: Build Godot with the Mono module enabled
|
||||
(yes | **no**)
|
||||
|
||||
- **mono_glue**: Whether to include the glue source files in the build and define `MONO_GLUE_DISABLED` as a preprocessor macro ( **yes** | no )
|
||||
- **mono_glue**: Whether to include the glue source files in the build
|
||||
and define ``MONO_GLUE_DISABLED`` as a preprocessor macro (**yes** | no)
|
||||
|
||||
- **mono_prefix**: Path to the Mono installation directory for the target platform and architecture
|
||||
- **mono_prefix**: Path to the Mono installation directory
|
||||
for the target platform and architecture
|
||||
|
||||
- **xbuild_fallback**: Whether to fallback to xbuild if MSBuild is not available ( yes | **no** )
|
||||
- **xbuild_fallback**: Whether to fallback to xbuild if MSBuild is not available
|
||||
(yes | **no**)
|
||||
|
||||
- **mono_static**: Whether to link the mono runtime statically ( yes | **no** )
|
||||
- **mono_static**: Whether to link the Mono runtime statically
|
||||
(yes | **no**)
|
||||
|
||||
- **copy_mono_root**: Whether to copy the Mono framework assemblies and configuration files required by the Godot editor ( yes | **no** )
|
||||
- **copy_mono_root**: Whether to copy the Mono framework assemblies
|
||||
and configuration files required by the Godot editor (yes | **no**)
|
||||
|
||||
Reference in New Issue
Block a user