Merge pull request #1902 from dsnopek/v10-readme-updates

Update README for versioning and compatibility changes in v10

Author: dsnopek

README.md

@@ -1,23 +1,9 @@
 # godot-cpp
 
-> [!WARNING]
->
-> This repository's `master` branch is only usable with
-> [GDExtension](https://godotengine.org/article/introducing-gd-extensions)
-> from Godot's `master` branch.
->
-> For users of stable branches, switch to the branch matching your target Godot version:
-> - [`4.5`](https://github.com/godotengine/godot-cpp/tree/4.5)
-> - [`4.4`](https://github.com/godotengine/godot-cpp/tree/4.4)
-> - [`4.3`](https://github.com/godotengine/godot-cpp/tree/4.3)
-> - [`4.2`](https://github.com/godotengine/godot-cpp/tree/4.2)
-> - [`4.1`](https://github.com/godotengine/godot-cpp/tree/4.1)
-> - [`4.0`](https://github.com/godotengine/godot-cpp/tree/4.0)
->
-> Or check out the Git tag matching your Godot version (e.g. `godot-4.1.1-stable`).
+> [!NOTE]
 >
-> For GDNative users (Godot 3.x), switch to the [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
-> or the [`3.5`](https://github.com/godotengine/godot-cpp/tree/3.5) branch.
+> For GDNative (Godot 3.x), switch to the [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
+> or the [`3.6`](https://github.com/godotengine/godot-cpp/tree/3.6) branch.
 
 This repository contains the  *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API.
 
@@ -29,36 +15,41 @@ This repository contains the  *C++ bindings* for the [**Godot Engine**](https://
 
 ## Versioning
 
-This repositories follows the same branch versioning as the main [Godot Engine
-repository](https://github.com/godotengine/godot):
-
-- `master` tracks the current GDExtension development branch for the next Godot
-  4.x minor release.
-- `3.x` tracks the development of the GDNative plugin for the next 3.x minor
-  release.
-- Other versioned branches (e.g. `4.0`, `3.5`) track the latest stable release
-  in the corresponding branch.
-
-Stable releases are also tagged on this repository:
-[**Tags**](https://github.com/godotengine/godot-cpp/tags).
+> [!WARNING]
+>
+> The master branch of godot-cpp (version 10.x) is currently in Beta. You may prefer to choose a previous version to build on top of instead:
+> - [`4.5`](https://github.com/godotengine/godot-cpp/tree/4.5)
+> - [`godot-4.5-stable`](https://github.com/godotengine/godot-cpp/tree/godot-4.5-stable)
+> - [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
 
-**For any project built against a stable release of Godot, we recommend using
-this repository as a Git submodule, checking out the specific tag matching your
-Godot version.**
+Starting with version 10.x, godot-cpp is versioned independently from Godot. The godot-cpp version you
+choose has no bearing on which Godot versions it is compatible with.
 
-> As the `master` branch of Godot is constantly getting updated, if you are
-> using `godot-cpp` against a more current version of Godot, see the instructions
-> in the `gdextension` folder to update the relevant files.
+Until we have a stable release branch, you can use the `master` branch, or choose any of the previous
+version branches and tags for your project.
 
 ## Compatibility
 
 GDExtensions targeting an earlier version of Godot should work in later minor versions,
-but not vice-versa. For example, a GDExtension targeting Godot 4.2 should work just fine
-in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2.
+but not vice-versa. For example, a GDExtension targeting Godot 4.3 should work just fine
+in Godot 4.4, but one targeting Godot 4.4 won't work in Godot 4.3.
+
+You can specify which version you are targeting with the `api_version` option:
 
-There is one exception to this: extensions targeting Godot 4.0 will _not_ work with
-Godot 4.1 and later.
-See [Updating your GDExtension for 4.1](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.1.html#updating-your-gdextension-for-godot-4-1).
+```
+scons api_version=4.3
+```
+
+... or by providing a custom `extension_api.json` generated by the Godot version you are
+targeting:
+
+```
+godot --dump-extension-api
+scons custom_api_file=extension_api.json
+```
+
+If you don't provide `api_version` or `custom_api_file`, then, by default, godot-cpp will
+target the latest stable Godot version that it's aware of.
 
 ## Contributing
 
@@ -69,16 +60,8 @@ wish to help out, please visit the [godot-cpp section of the Contributing docs](
 
 You need the same C++ pre-requisites installed that are required for the `godot` repository. Follow the [official build instructions for your target platform](https://docs.godotengine.org/en/latest/engine_details/development/compiling/index.html).
 
-Getting started with GDExtensions is a bit similar to what it was for 3.x but also a bit different.
-
-This new approach is much more akin to how core Godot modules are structured.
-
-Compiling this repository generates a static library to be linked with your shared lib,
-just like before.
-
-To use the shared lib in your Godot project you'll need a `.gdextension`
-file, which replaces what was the `.gdnlib` before.
-See [example.gdextension](test/project/example.gdextension) used in the test project:
+Building your extension will create a shared library. To use this in your Godot project you'll need a `.gdextension`
+file, for example:
 
 ```ini
 [configuration]
@@ -97,8 +80,10 @@ linux.release.x86_64 = "res://bin/libgdexample.linux.release.x86_64.so"
 # Repeat for other architectures to support arm64, rv64, etc.
 ```
 
-The `entry_symbol` is the name of the function that initializes
-your library. It should be similar to following layout:
+See the [example.gdextension](https://github.com/godotengine/godot-cpp-template/blob/main/demo/bin/example.gdextension)
+used in the template project for a complete example.
+
+The `entry_symbol` is the name of the function that initializes your library, for example:
 
 ```cpp
 extern "C" {
@@ -117,7 +102,7 @@ GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddre
 }
 ```
 
-The `initialize_example_module()` should register the classes in ClassDB, very like a Godot module would do.
+The `initialize_example_module()` should register the classes in ClassDB, similar to a Godot module:
 
 ```cpp
 using namespace godot;
@@ -129,7 +114,8 @@ void initialize_example_module(ModuleInitializationLevel p_level) {
 }
 ```
 
-Any node and resource you register will be available in the corresponding `Create...` dialog. Any class will be available to scripting as well.
+Any node and resource you register will be available in the corresponding `Create...` dialog.
+Any class will be available to scripting as well.
 
 ## Examples and templates