Add documentation about .gdextension file

Update tutorials/scripting/gdextension/gdextension_file.rst

tutorials/scripting/gdextension/gdextension_file.rst

@@ -0,0 +1,123 @@
+.. _doc_gdextension_file_sections:
+
+The .gdextension file
+=====================
+
+Introduction
+------------
+
+The ``.gdextension`` file in your project contains the instructions for how to load
+the GDExtension. The instructions are separated into specific sections. This page
+should give you a quick overview of the different options available to you. For an introduction
+how to get started with GDExtensions take a look at the :ref:`GDExtension C++ Example <doc_gdextension_cpp_example>`.
+
+Configuration section
+---------------------
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Instruction | Description |
++===============================+======================================================================================================+
+| **entry_symbol** | Name of the entry function for initializing the GDExtension. This function should be defined in |
+| | the ``register_types.cpp`` file. Adding this is necessary for the extension to work. |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compatibility_minimum** | Minimum compatible version. This prevents older versions of Godot from loading extensions that |
+| | depend on features from newer versions of Godot. **Only supported for Godot 4.1+** |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **compatibility_maximum** | Maximum compatible version. This prevents newer versions of Godot from loading the extension. |
+| | **Only supported for Godot 4.3+** |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **reloadable** | Reloads the extension upon recompilation. Reloading is not supported for every exposed class. |
+| | This flag should be mainly used for developing or debugging an extension. |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **android_aar_plugin** | The GDExtension is part of a :ref:`v2 Android plugin <doc_android_plugin>`. During export this flag |
+| | will indicate to the editor that the GDExtension native shared libraries are exported by the Android |
+| | plugin AAR binaries. |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+
+Libraries section
+-----------------
+
+In this section you can set the paths to the compiled binaries of your GDExtension libraries.
+By setting feature flags you can filter which version should be loaded and exported with your
+game depending on which feature flags are active. Every feature flag must match to Godot's
+feature flags. For instance ``macos.debug`` means that it will be loaded if Godot has both the
+``macos`` and ``debug`` flag active. Each line of the section is evaluated from top to bottom.
+
+Here is an example of what that can look like:
+
+.. code-block:: none
+
+ [libraries]
+
+ macos.debug = "res://bin/libgdexample.macos.template_debug.framework"
+ macos.release = "res://bin/libgdexample.macos.template_release.framework"
+ windows.debug.x86_32 = "res://bin/libgdexample.windows.template_debug.x86_32.dll"
+ windows.release.x86_32 = "res://bin/libgdexample.windows.template_release.x86_32.dll"
+ windows.debug.x86_64 = "res://bin/libgdexample.windows.template_debug.x86_64.dll"
+ windows.release.x86_64 = "res://bin/libgdexample.windows.template_release.x86_64.dll"
+ linux.debug.x86_64 = "res://bin/libgdexample.linux.template_debug.x86_64.so"
+ linux.release.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
+ linux.debug.arm64 = "res://bin/libgdexample.linux.template_debug.arm64.so"
+ linux.release.arm64 = "res://bin/libgdexample.linux.template_release.arm64.so"
+ linux.debug.rv64 = "res://bin/libgdexample.linux.template_debug.rv64.so"
+ linux.release.rv64 = "res://bin/libgdexample.linux.template_release.rv64.so"
+
+
+Here are lists of available options (for more look at the :ref:`feature tags <doc_feature_tags>`):
+
+Running system
+^^^^^^^^^^^^^^
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Flag | Description |
++===============================+======================================================================================================+
+| **windows** | Windows operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **macos** | Mac operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **linux** | Linux operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **bsd** | BSD operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **linuxbsd** | Linux or BSD operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **android** | Android operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **ios** | iOS operating system |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **web** | Web browser |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+
+Build
+^^^^^
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Flag | Description |
++===============================+======================================================================================================+
+| **debug** | Build with debug symbols |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **release** | Optimized build without debug symbols |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **editor** | Editor build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+
+Architecture
+^^^^^^^^^^^^
+
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| Flag | Description |
++===============================+======================================================================================================+
+| **double** | double-precision build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **single** | single-precision build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **x86_64** | 64-bit x86 build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **arm64** | 64-bit ARM build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **rv64** | 64-bit RISC-V build |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **riscv** | RISC-V build (any bitness) |
++-------------------------------+------------------------------------------------------------------------------------------------------+
+| **wasm32** | 32-bit WebAssembly build |
++-------------------------------+------------------------------------------------------------------------------------------------------+

tutorials/scripting/gdextension/index.rst

@@ -9,3 +9,4 @@ GDExtension
 
  what_is_gdextension
  gdextension_cpp_example
+ gdextension_file