Skip to content

Document relative paths in .gdextension files being supported #11381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 5, 2025
+48 −36
Merged

Document relative paths in .gdextension files being supported #11381

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions tutorials/scripting/cpp/gdextension_cpp_example.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -338,18 +338,18 @@ loaded for each platform and the entry function for the module. It is called ``g

[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"
macos.debug = "./bin/libgdexample.macos.template_debug.dylib"
macos.release = "./bin/libgdexample.macos.template_release.dylib"
windows.debug.x86_32 = "./bin/libgdexample.windows.template_debug.x86_32.dll"
windows.release.x86_32 = "./bin/libgdexample.windows.template_release.x86_32.dll"
windows.debug.x86_64 = "./bin/libgdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "./bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "./bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.debug.arm64 = "./bin/libgdexample.linux.template_debug.arm64.so"
linux.release.arm64 = "./bin/libgdexample.linux.template_release.arm64.so"
linux.debug.rv64 = "./bin/libgdexample.linux.template_debug.rv64.so"
linux.release.rv64 = "./bin/libgdexample.linux.template_release.rv64.so"

This file contains a ``configuration`` section that controls the entry function of the module.
You should also set the minimum compatible Godot version with ``compatibility_minimum``,
Expand Down
60 changes: 36 additions & 24 deletions tutorials/scripting/gdextension/gdextension_file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,21 +50,25 @@ Here is an example of what that can look like:

.. code-block:: none

; A comment line starts with a semicolon. This line is ignored by the engine.
[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"

macos.debug = "./bin/libgdexample.macos.template_debug.dylib" ; Inline comments are also allowed.
macos.release = "./bin/libgdexample.macos.template_release.dylib"
windows.debug.x86_32 = "./bin/libgdexample.windows.template_debug.x86_32.dll"
windows.release.x86_32 = "./bin/libgdexample.windows.template_release.x86_32.dll"
windows.debug.x86_64 = "./bin/libgdexample.windows.template_debug.x86_64.dll"
windows.release.x86_64 = "./bin/libgdexample.windows.template_release.x86_64.dll"
linux.debug.x86_64 = "./bin/libgdexample.linux.template_debug.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.debug.arm64 = "./bin/libgdexample.linux.template_debug.arm64.so"
linux.release.arm64 = "./bin/libgdexample.linux.template_release.arm64.so"
linux.debug.rv64 = "./bin/libgdexample.linux.template_debug.rv64.so"
linux.release.rv64 = "./bin/libgdexample.linux.template_release.rv64.so"

Paths can be relative or absolute (starting with ``res://``). Relative paths are recommended,
as they allow the extension to keep working if it's installed to a different folder than what's
specified in the path.

Entries are matched in order, so if two sets of feature tags could match
the same system, be sure to put the more specific ones first:
Expand All @@ -73,8 +77,8 @@ the same system, be sure to put the more specific ones first:

[libraries]

linux.release.editor.x86_64 = "res://bin/libgdexample.linux.template_release.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.noeditor.template_release.x86_64.so"
linux.release.editor.x86_64 = "./bin/libgdexample.linux.template_release.x86_64.so"
linux.release.x86_64 = "./bin/libgdexample.linux.noeditor.template_release.x86_64.so"

Here are lists of some of the available built-in options (for more look at the :ref:`feature tags <doc_feature_tags>`):

Expand Down Expand Up @@ -107,9 +111,9 @@ Build
+-------------------------------+------------------------------------------------------------------------------------------------------+
| Flag | Description |
+===============================+======================================================================================================+
| **debug** | Build with debug symbols |
| **debug** | Build with debugging features (editor builds always have debugging features) |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **release** | Optimized build without debug symbols |
| **release** | Optimized build without debugging features |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **editor** | Editor build |
+-------------------------------+------------------------------------------------------------------------------------------------------+
Expand Down Expand Up @@ -138,8 +142,8 @@ Architecture
Icons section
-------------

By default, Godot uses the Node icon in the scene dock for GDExtension nodes. A custom icon can be
set by reference to its name and resource path of an SVG file.
By default, Godot uses the Node icon in the scene dock for GDExtension nodes.
A custom icon can be set by reference to its name and resource path of an SVG file.

For example:

Expand All @@ -149,20 +153,28 @@ For example:

GDExample = "res://icons/gd_example.svg"

The path should point to a 16 by 16 pixel SVG image. Read the guide for :ref:`creating icons <doc_editor_icons>`
The path should point to a 16×16 pixel SVG image, with two options enabled on the
image in the Import dock:

- **Editor > Scale with Editor Scale**.
- **Editor > Convert Colors with Editor Theme**.

Enabling both options ensures the icon behaves as closely as possible to
the stock editor icons. Read the guide for :ref:`creating icons <doc_editor_icons>`
for more information.

Dependencies section
--------------------

In this section you set the paths of the GDExtension dependencies. This is used internally to export the dependencies
In this section, you set the paths of the GDExtension dependencies. This is used internally to export the dependencies
when exporting your game executable. You are able to set which dependency is loaded depending on the feature flags
of the exported executable. In addition, you are able to set an optional subdirectory to move your dependencies into.
If no path is supplied Godot will move the libraries into the same directory as your game executable.
If no path is supplied, Godot will move the libraries into the same directory as your game executable.

.. warning::
In MacOS it is necessary to have shared libraries inside a folder called ``Frameworks`` with a directory structure
like this: ``Game.app/Contents/Frameworks``.

On macOS, it is necessary to have shared libraries inside a folder called ``Frameworks``
with a directory structure like this: ``Game.app/Contents/Frameworks``.

.. code-block:: none

Expand Down
Loading