-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
/
compiling_with_dotnet.rst
219 lines (156 loc) · 8.27 KB
/
compiling_with_dotnet.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
.. _doc_compiling_with_dotnet:
Compiling with .NET
===================
.. highlight:: shell
Requirements
------------
- `.NET SDK 6.0+ <https://dotnet.microsoft.com/download>`_
You can use ``dotnet --info`` to check which .NET SDK versions are installed.
Enable the .NET module
----------------------
.. note:: C# support for Godot has historically used the
`Mono <https://www.mono-project.com/>`_ runtime instead of the
`.NET Runtime <https://github.com/dotnet/runtime>`_ and internally
many things are still named ``mono`` instead of ``dotnet`` or
otherwise referred to as ``mono``.
By default, the .NET module is disabled when building. To enable it, add the
option ``module_mono_enabled=yes`` to the SCons command line, while otherwise
following the instructions for building the desired Godot binaries.
Generate the glue
-----------------
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 .NET-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 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 .NET 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 .NET support, you
might have similarly named binaries without this suffix. These binaries can't be
used to generate the .NET 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 .NET glue, you can build the managed libraries with
the ``build_assemblies.py`` script::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin
If everything went well, the ``GodotSharp`` directory, containing the managed
libraries, should have been created in the ``bin`` directory.
.. note:: By default, all development builds share a version number, which can
cause some issues with caching of the NuGet packages. To solve this
issue either use ``GODOT_VERSION_STATUS`` to give every build a unique
version or delete ``GodotNuGetFallbackFolder`` after every build to
clear the package cache.
Unlike "classical" Godot builds, when building with the .NET 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_dotnet_data_directory>`.
Build Platform
^^^^^^^^^^^^^^
Provide the ``--godot-platform=<platform>`` argument to control for which
platform specific the libraries are built. Omit this argument to build for the
current system.
This currently only controls the inclusion of the support for Visual Studio as
an external editor, the libraries are otherwise identical.
NuGet packages
^^^^^^^^^^^^^^
The API assemblies, source generators, and custom MSBuild project SDK are
distributed as NuGet packages. This is all transparent to the user, but it can
make things complicated during development.
In order to use Godot with a development version of those packages, a local
NuGet source must be created where MSBuild can find them.
First, pick a location for the local NuGet source. If you don't have a
preference, create an empty directory at one of these recommended locations:
- On Windows, ``C:\Users\<username>\MyLocalNugetSource``
- On Linux, \*BSD, etc., ``~/MyLocalNugetSource``
This path is referred to later as ``<my_local_source>``.
After picking a directory, run this .NET CLI command to configure NuGet to use
your local source:
::
dotnet nuget add source <my_local_source> --name MyLocalNugetSource
When you run the ``build_assemblies.py`` script, pass ``<my_local_source>`` to
the ``--push-nupkgs-local`` option:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source>
This option ensures the packages will be added to the specified local NuGet
source and that conflicting versions of the package are removed from the NuGet
cache. It's recommended to always use this option when building the C# solutions
during development to avoid mistakes.
Double Precision Support (REAL_T_IS_DOUBLE)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When building Godot with double precision support, i.e. the ``precision=double``
argument for scons, the managed libraries must be adjusted to match by passing
the ``--precision=double`` argument:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --precision=double
Examples
--------
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 --headless --generate-mono-glue modules/mono/glue
# Build .NET assemblies
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=windows
Example (Linux, \*BSD)
^^^^^^^^^^^^^^^^^^^^^^
::
# 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 --headless --generate-mono-glue modules/mono/glue
# Generate binaries
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=linuxbsd
.. _compiling_with_dotnet_data_directory:
Data directory
--------------
The data directory is a dependency for Godot binaries built with the .NET module
enabled. It contains important files for the correct functioning of Godot. It
must be distributed together with the Godot executable.
Editor
^^^^^^
The name of the data directory for the Godot editor will always be
``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.
On macOS, if the Godot editor is distributed as a bundle, the ``GodotSharp``
directory may be placed in the ``<bundle_name>.app/Contents/Resources/``
directory inside the bundle.
Export templates
^^^^^^^^^^^^^^^^
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.
In the case of multi-architecture exports multiple such data directories will be
generated.
Command-line options
--------------------
The following is the list of command-line options available when building with
the .NET module:
- **module_mono_enabled**\ =yes | **no**
- Build Godot with the .NET module enabled.