Merge pull request #2646 from Calinou/improve-compiling-with-mono

Improve writing style in "Compiling with Mono"

development/compiling/compiling_with_mono.rst

@@ -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.
-
-``<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.
+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'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.
-
-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.
-
-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).
+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 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'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**)