godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into 3.1

Browse Source
This commit is contained in:
Rémi Verschelde
2019-07-29 18:20:01 +02:00
parent 0f8326dc51 c19078ee16
commit 98e0adf5d8
94 changed files with 1396 additions and 1115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
development/compiling/compiling_for_windows.rst
View File

@@ -151,29 +151,29 @@ If you are a Linux or macOS user, you need to install
and 64-bit variants. The package names may differ based on your distribution,
here are some known ones:
+---------------+--------------------------------------------------------------+
| **Arch** | :: |
| | |
| | pacman -S mingw-w64-gcc |
+---------------+--------------------------------------------------------------+
| **Debian** / | :: |
| **Ubuntu** | |
| | apt install mingw-w64 |
+---------------+--------------------------------------------------------------+
| **Fedora** | :: |
| | |
| | dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+---------------+--------------------------------------------------------------+
| **macOS** | :: |
| | |
| | brew install mingw-w64 |
+---------------+--------------------------------------------------------------+
| **Mageia** | :: |
| | |
| | urpmi mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+---------------+--------------------------------------------------------------+
+----------------+--------------------------------------------------------------+
| **Arch Linux** | Install `mingw-w64-gcc from the AUR`_. |
+----------------+--------------------------------------------------------------+
| **Debian** / | :: |
| **Ubuntu** | |
| | apt install mingw-w64 |
+----------------+--------------------------------------------------------------+
| **Fedora** | :: |
| | |
| | dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+----------------+--------------------------------------------------------------+
| **macOS** | :: |
| | |
| | brew install mingw-w64 |
+----------------+--------------------------------------------------------------+
| **Mageia** | :: |
| | |
| | urpmi mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+----------------+--------------------------------------------------------------+
.. _mingw-w64-gcc from the AUR: https://aur.archlinux.org/packages/mingw-w64-gcc/
Before attempting the compilation, SCons will check for
the following binaries in your ``PATH`` environment variable::

5
development/compiling/compiling_for_x11.rst
View File

@@ -45,8 +45,9 @@ Distro-specific oneliners
+----------------+-----------------------------------------------------------------------------------------------------------+
| **FreeBSD** | :: |
| | |
| | sudo pkg install scons pkgconf xorg-libraries libXcursor libXrandr libXi xineramaproto libglapi \ |
| | libGLU yasm |
| | sudo pkg install scons pkgconf xorg-libraries libXcursor libXrandr libXi xorgproto libGLU alsa-lib \ |
| | pulseaudio yasm |
| | |
+----------------+-----------------------------------------------------------------------------------------------------------+
| **Gentoo** | :: |
| | |

141
development/compiling/compiling_with_mono.rst
View File

@@ -13,18 +13,18 @@ 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 using the following environment variables for the respective
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 using the following environment variables for the respective
``bits`` option: ``MONO32_PREFIX`` and ``MONO64_PREFIX``.
The specified directory must contain the subdirectories ``bin``, ``include``, and ``lib``.
@@ -32,71 +32,77 @@ The specified directory must contain the subdirectories ``bin``, ``include``, an
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``.
Once this file is generated, you can build Godot for all the desired targets without the need to repeat this process.
Once this file is generated, you can build Godot for all the desired targets
without the need 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.
- 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.
- 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>`.
Examples
--------
@@ -138,22 +144,27 @@ 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.
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.
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`` |
@@ -164,8 +175,8 @@ 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`` (optional)
- ``Mono`` (optional)
@@ -226,14 +237,20 @@ In the case of macOS, if the Godot editor is distributed as a bundle, the conten
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)
- **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**)

119
development/compiling/introduction_to_the_buildsystem.rst
View File

@@ -15,9 +15,8 @@ to move the build system to CMake, or Visual Studio, but this is not
going to happen. There are many reasons why we have chosen SCons over
other alternatives, for example:
- Godot can be compiled for a dozen different platforms. All PC
platforms, all mobile platforms, many consoles, and many web-based
platforms (such as HTML5 and Chrome PNACL).
- Godot can be compiled for a dozen different platforms: all PC
platforms, all mobile platforms, many consoles, and WebAssembly.
- Developers often need to compile for several of the platforms **at
the same time**, or even different targets of the same platform. They
can't afford reconfiguring and rebuilding the project each time.
@@ -30,19 +29,24 @@ other alternatives, for example:
customization (plugins). This requires complex logic which is easier
to write in an actual programming language (like Python) rather than
using a mostly macro-based language only meant for building.
- Godot build process makes heavy use of cross compiling tools. Each
- Godot build process makes heavy use of cross-compiling tools. Each
platform has a specific detection process, and all these must be
handled as specific cases with special code written for each.
So, please try to keep an open mind and get at least a little familiar with it if you are planning to
build Godot yourself.
So, please try to keep an open mind and get at least a little familiar with it
if you are planning to build Godot yourself.
Setup
-----
Please refer to the documentation for :ref:`doc_compiling_for_android`, :ref:`doc_compiling_for_ios`, :ref:`doc_compiling_for_osx`, :ref:`doc_compiling_for_uwp`, :ref:`doc_compiling_for_web`, :ref:`doc_compiling_for_windows` and :ref:`doc_compiling_for_x11`.
Please refer to the documentation for :ref:`doc_compiling_for_android`,
:ref:`doc_compiling_for_ios`, :ref:`doc_compiling_for_osx`,
:ref:`doc_compiling_for_uwp`, :ref:`doc_compiling_for_web`,
:ref:`doc_compiling_for_windows` and :ref:`doc_compiling_for_x11`.
Note that for **Windows/Visual Studio**, you need to use ``x86_x64 Cross Tools Command Prompt for VS 2017`` or similar, depending on your install, instead of the standard Windows command prompt to enter the commands below.
Note that for **Windows/Visual Studio**, you need to use ``x86_x64 Cross Tools
Command Prompt for VS 2017`` or similar, depending on your install, instead of
the standard Windows command prompt to enter the commands below.
Platform selection
------------------
@@ -52,30 +56,25 @@ for. If not detected, the platform will simply not appear on the list of
available platforms. The build requirements for each platform are
described in the rest of this tutorial section.
SCons is invoked by just calling ``scons``.
SCons is invoked by just calling ``scons``. If no platform is specified,
SCons will detect the target platform automatically based on the host platform.
It will then start building for the target platform right away.
However, this will do nothing except list the available platforms, for
example:
To list the available target platforms, use ``scons platform=list``::
::
user@host:~/godot$ scons
user@host:~/godot$ scons platform=list
scons: Reading SConscript files ...
No valid target platform selected.
The following were detected:
The following platforms are available:
android
server
javascript
server
windows
x11
Please run scons again with argument: platform=<string>
scons: done reading SConscript files.
scons: Building targets ...
scons: `.' is up to date.
scons: done building targets.
Please run SCons again and select a valid platform: platform=<string>
To build for a platform (for example, x11), run with the ``platform=`` (or just
To build for a platform (for example, x11), run with the ``platform=`` (or
``p=`` to make it short) argument:
::
@@ -83,8 +82,8 @@ To build for a platform (for example, x11), run with the ``platform=`` (or just
user@host:~/godot$ scons platform=x11
This will start the build process, which will take a while. If you want
scons to build faster, use the ``-j <cores>`` parameter to specify how many
cores will be used for the build. Or just leave it using one core, so you
SCons to build faster, use the ``-j <cores>`` parameter to specify how many
cores will be used for the build. Or leave it using one core, so you
can use your computer for something else :)
Example for using 4 cores:
@@ -96,16 +95,12 @@ Example for using 4 cores:
Resulting binary
----------------
The resulting binaries will be placed in the bin/ subdirectory,
generally with this naming convention:
::
The resulting binaries will be placed in the ``bin/`` subdirectory,
generally with this naming convention::
godot.<platform>.[opt].[tools/debug].<architecture>[extension]
For the previous build attempt the result would look like this:
::
For the previous build attempt, the result would look like this::
user@host:~/godot$ ls bin
bin/godot.x11.tools.64
@@ -113,18 +108,16 @@ For the previous build attempt the result would look like this:
This means that the binary is for X11, is not optimized, has tools (the
whole editor) compiled in, and is meant for 64 bits.
A Windows binary with the same configuration will look like this.
A Windows binary with the same configuration will look like this::
::
C:\GODOT> DIR BIN/
C:\godot> dir bin/
godot.windows.tools.64.exe
Just copy that binary to wherever you like, as it contains the
project manager, editor and all means to execute the game. However, it
lacks the data to export it to the different platforms. For that the
export templates are needed (which can be either downloaded from
`godotengine.org <https://godotengine.org/>`__, or you can build them yourself).
Copy that binary to any location you like, as it contains the project manager,
editor and all means to execute the game. However, it lacks the data to export
it to the different platforms. For that the export templates are needed (which
can be either downloaded from `godotengine.org <https://godotengine.org/>`__, or
you can build them yourself).
Aside from that, there are a few standard options that can be set in all
build targets, and which will be explained below.
@@ -150,19 +143,19 @@ Target controls optimization and debug flags. Each mode means:
checks and reports error) and none to little optimization.
- **release_debug**: Build without C++ debugging symbols and
optimization, but keep the runtime checks (performs checks and
reports errors). Official binaries use this configuration.
reports errors). Official editor binaries use this configuration.
- **release**: Build without symbols, with optimization and with little
to no runtime checks. This target can't be used together with
tools=yes, as the tools require some debug functionality and run-time
``tools=yes``, as the editor requires some debug functionality and run-time
checks to run.
::
scons platform=<platform> target=debug/release_debug/release
This flag appends the ".debug" suffix (for debug), or ".tools" (for debug
with tools enabled). When optimization is enabled (release) it appends
the ".opt" suffix.
This flag appends the ``.debug`` suffix (for debug), or ``.tools`` (for debug
with tools enabled). When optimization is enabled (release), it appends
the ``.opt`` suffix.
Bits
----
@@ -171,18 +164,17 @@ Bits is meant to control the CPU or OS version intended to run the
binaries. It is focused mostly on desktop platforms and ignored everywhere
else.
- **32**: Build binaries for 32 bits platform.
- **64**: Build binaries for 64 bits platform.
- **default**: Build whatever the build system feels is best. On Linux
this depends on the host platform (if not cross compiling),
on Mac it defaults to 64 bits and on Windows it defaults to 32 bits.
- **32**: Build binaries for 32-bit platforms.
- **64**: Build binaries for 64-bit platforms.
- **default**: Build for the architecture that matches the host platform.
::
scons platform=<platform> bits=default/32/64
This flag appends ".32" or ".64" suffixes to resulting binaries when
relevant.
This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when
relevant. If ``bits=default`` is used, the suffix will match the detected
architecture.
Other build options
-------------------
@@ -203,7 +195,7 @@ to build them yourself (in case you want newer ones, you are using custom
modules, or simply don't trust your own shadow).
If you download the official export templates package and unzip it, you
will notice that most are just optimized binaries or packages for each
will notice that most files are optimized binaries or packages for each
platform:
::
@@ -225,12 +217,19 @@ platform:
windows_64_debug.exe
windows_64_release.exe
To create those yourself, just follow the instructions detailed for each
To create those yourself, follow the instructions detailed for each
platform in this same tutorial section. Each platform explains how to
create its own template.
If you are developing for multiple platforms, macOS is definitely the most convenient
host platform for cross compilation, since you can cross-compile for
almost every target (except for UWP). Linux and Windows come in second
place, but Linux has the advantage of being the easier platform to set
this up.
The ``version.txt`` file should contain the corresponding Godot version
identifier. This file is used to install export templates in a version-specific
directory to avoid conflicts. For instance, if you are building export templates
for Godot 3.1.1, ``version.txt`` should contain ``3.1.1.stable`` on the first
line (and nothing else). This version identifier is based on the ``major``,
``minor``, ``patch`` (if present) and ``status`` lines of the
`version.py file in the Godot Git repository <https://github.com/godotengine/godot/blob/master/version.py>`__.
If you are developing for multiple platforms, macOS is definitely the most
convenient host platform for cross-compilation, since you can cross-compile for
almost every target (except for UWP). Linux and Windows come in second place,
but Linux has the advantage of being the easier platform to set this up.

2
development/cpp/configuring_an_ide.rst
View File

@@ -295,4 +295,4 @@ To create them:
- You can now start Debug process again to test that everything works.
- If the build phase fails, check console for hints. On Linux it's most likely that some dependencies are missing. Check :ref:`Compiling for X11 (Linux, \*BSD) <doc_compiling_for_x11>`
- If the build phase fails, check the console for hints. On Linux it's most likely that some dependencies are missing. Check :ref:`Compiling for X11 (Linux, \*BSD) <doc_compiling_for_x11>`

2
development/cpp/custom_modules_in_cpp.rst
View File

@@ -21,7 +21,7 @@ transparently.
What for?
---------
While it's recommended that most of a game is written in scripting (as
While it's recommended that most of a game be written in scripting (as
it is an enormous time saver), it's perfectly possible to use C++
instead. Adding C++ modules can be useful in the following scenarios: