From 41fb0964e81a0bcc377939c02fe0a6f2801e4f23 Mon Sep 17 00:00:00 2001 From: Jan Haller Date: Sat, 29 Jul 2023 17:29:14 +0200 Subject: [PATCH] Update ReadMe + Contribution guidelines ReadMe.md * "Experimental" warning is less alarming * Usage examples moved to book * Mention brief philosophy Contributing.md * Dev-Tools moved to book --- Contributing.md | 140 ++---------------------------------------------- ReadMe.md | 93 ++++++++++---------------------- 2 files changed, 31 insertions(+), 202 deletions(-) diff --git a/Contributing.md b/Contributing.md index d0143e1a0..67b70f6b2 100644 --- a/Contributing.md +++ b/Contributing.md @@ -33,144 +33,12 @@ This signals that reviews are appreciated, but that the code is not yet ready fo Non-draft PRs that pass CI are assumed to be mergeable (and maintainers may do so).
-# Dev tools -## Local development +## Development tools -The script `check.sh` in the project root can be used to mimic a minimal version of CI locally. -It's useful to run this before you commit, push or create a pull request: - -```bash -$ ./check.sh -``` - -At the time of writing, this will run formatting, clippy, unit tests and integration tests. More checks may be added in the future. -Run `./check.sh --help` to see all available options. - -If you like, you can set this as a pre-commit hook in your local clone of the repository: - -```bash -$ ln -sf check.sh .git/hooks/pre-commit -``` - - -### Unit tests - -Because most of gdext interacts with the Godot engine, which is not available from the test executable, unit tests -(using `cargo test` and the `#[test]` attribute) are pretty limited in scope. They are primarily used for Rust-only logic. - -As additional flags might be needed, the preferred way to run unit tests is through the `check.sh` script: - -```bash -$ ./check.sh test -``` - - -### Integration tests - -The `itest` directory contains a suite of integration tests. It is split into two directories: -`rust`, containing the Rust code for the GDExtension library, and `godot` with the Godot project and GDScript tests. - -Similar to `#[test]`, the function annotated by `#[itest]` contains one integration test. There are multiple syntax variations: - -```rust -// Use a Godot API and verify the results using assertions. -#[itest] -fn variant_nil() { - let variant = Variant::nil(); - assert!(variant.is_nil()); -} - -// TestContext parameter gives access to a node in the scene tree. -#[itest] -fn do_sth_with_the_tree(ctx: &TestContext) { - let tree: Gd = ctx.scene_tree.share(); - - // If you don't need the scene, you can also construct free-standing nodes: - let node: Gd = Node3D::new_alloc(); - // ... - node.free(); // don't forget to free everything created by new_alloc(). -} - -// Skip a test that's not yet ready. -#[itest(skip)] -fn not_executed() { - // ... -} - -// Focus on a one or a few tests. -// As soon as there is at least one #[itest(focus)], only focused tests are run. -#[itest(focus)] -fn i_need_to_debug_this() { - // ... -} -``` - -You can run the integration tests like this: - -```bash -$ ./check.sh itest -``` - -Just like when compiling the crate, the `GODOT4_BIN` environment variable can be used to supply the path and filename of your Godot executable. -Otherwise, a binary named `godot4` in your PATH is used. - - -### Formatting - -`rustfmt` is used to format code. `check.sh` only warns about formatting issues, but does not fix them. To do that, run: - -```bash -$ cargo fmt -``` - - -### Clippy - -`clippy` is used for additional lint warnings not implemented in `rustc`. This, too, is best run through `check.sh`: - -```bash -$ ./check.sh clippy -``` - -## Continuous Integration - -If you want to have the full CI experience, you can experiment as much as you like on your own gdext fork, before submitting a pull request. - -For this, navigate to the file `.github/workflows/full-ci.yml` and change the following lines: - -```yml -on: - push: - branches: - - staging - - trying -``` - -to: - -```yml -on: - push: -``` - -This runs the entire CI pipeline to run on every push. You can then see the results in the _Actions_ tab in your repository. - -Don't forget to undo this before opening a PR! You may want to keep it in a separate commit named "UNDO" or similar. - - -## Build configurations - -### `real` type - -Certain types in Godot use either a single or double-precision float internally, such as `Vector2`. -When working with these types, we use the `real` type instead of choosing either `f32` or `f64`. -As a result, our code is portable between Godot binaries compiled with `precision=single` and `precision=double`. - -To run the testing suite with `double-precision` enabled you may add `--double` to a `check.sh` invocation: -```bash -$ ./check.sh --double -``` +Further information for contributors, such as tools supporting you in local development, is available in the [godot-rust book]. +The book also elaborates design principles and conventions behind our API. [GitHub issue]: https://github.com/godot-rust/gdext/issues [Discord]: https://discord.gg/aKUCJ8rJsc +[godot-rust book](https://godot-rust.github.io/gdext/contribute). \ No newline at end of file diff --git a/ReadMe.md b/ReadMe.md index 3d6abebe2..661a73faf 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -4,84 +4,43 @@ _**[Website]** | **[API Docs]** | [Discord] | [Mastodon] | [Twitter]_ -**gdext** is an early-stage library to bind the **Rust** language to **Godot 4**. +**gdext** is a library to bind the **Rust** language to **Godot 4**. -[Godot] is an open-source game engine, whose upcoming version 4.0 brings several improvements. +[Godot] is an open-source game engine, whose version 4 has brought large-scale improvements. Its _GDExtension_ API allows integrating third-party languages and libraries. > **Note**: if you are looking for a Rust binding for GDNative (Godot 3), checkout [`gdnative`]. -> **Warning**: this library is experimental and rapidly evolving. In particular, this means: -> * Lots of bugs. A lot of the scaffolding is still being ironed out. -> There are known safety issues, possible undefined behavior as well as other potential problems. -> * Lots of missing features. The priority is to get basic interactions working; -> as such, edge case APIs are deliberately neglected at this stage. -> * No stability guarantees. APIs will break frequently (for releases, we try to take SemVer seriously though). -> Resolving the above two points has currently more weight than a stable API. -We do not recommend building a larger project in gdext yet. -However, the library can serve as a playground for experimenting. +## Philosophy -To get an overview of currently supported features, consult [#24](https://github.com/godot-rust/gdext/issues/24). -At this point, there is **no** support for Android, iOS or WASM. Contributions are very welcome! +The primary goal of gdext is to provide a **pragmatic Rust API** for game developers. +Recurring workflows should be easy and with minimal boilerplate. APIs are designed to be safe and idiomatic Rust wherever possible. +Due to interacting with Godot as a C++/GDScript engine, we sometimes follow unconventional approaches to provide a good user experience. -## Getting started - -An elaborate tutorial is available [in the book] (still under construction), here is the short version. - -To find a version of Godot 4, the library expects either an executable of name `godot4` in the PATH, or an environment variable `GODOT4_BIN` -containing the path to the executable (including filename). -We currently only have a GitHub version, crates.io releases are planned once more of the foundation is ready. - -In your Cargo.toml, add: -```toml -[lib] -crate-type = ["cdylib"] +## Development status -[dependencies] -godot = { git = "https://github.com/godot-rust/gdext", branch = "master" } -``` -To get the latest changes, you can regularly run a `cargo update` (possibly breaking). Keep your `Cargo.lock` file under version control, so that it's easy to revert updates. +> **Warning**: the gdext library has evolved a lot during 2023 and is now in a usable state for smaller projects. +> However, it is still in an early stage and there are certain things to keep in mind: -To register the GDExtension library with Godot, you need to create two files relative to your Godot project folder: +* While most Godot features are available, some less commonly used ones are missing. + See [#24] for an up-to-date overview. +* We have an elaborate test suite, but bugs and UB is still possible. +* The public API introduces breaking changes from time to time. Most of these are motivated by new features and + improved ergonomics for existing ones. Once we are on crates.io, we will adhere to SemVer for releases. +* At this point, there is **no** support for Android, iOS or WASM. Contributions are very welcome! -1. First, add `res://MyExt.gdextension`, which is the equivalent of `.gdnlib` for GDNative. - The `[configuration]` section should be copied as-is. - The `[libraries]` section should be updated to match the paths of your dynamic Rust libraries. - `{my-ext}` can be replaced with the name of your crate. - ```ini - [configuration] - entry_symbol = "gdext_rust_init" - - [libraries] - linux.debug.x86_64 = "res://../rust/target/debug/lib{my-ext}.so" - linux.release.x86_64 = "res://../rust/target/release/lib{my-ext}.so" - windows.debug.x86_64 = "res://../rust/target/debug/{my-ext}.dll" - windows.release.x86_64 = "res://../rust/target/release/{my-ext}.dll" - macos.debug = "res://../rust/target/debug/{my-ext}.dylib" - macos.release = "res://../rust/target/release/{my-ext}.dylib" - macos.debug.arm64 = "res://../rust/target/debug/{my-ext}.dylib" - macos.release.arm64 = "res://../rust/target/release/{my-ext}.dylib" - ``` - > **Note**: for exporting your project, you'll need to use paths inside `res://` - - > **Note**: If you specify your cargo compilation target via the `--target` flag or a `.cargo/config.toml` file, the rust library will be placed in a path name that includes target architecture, and the `.gdextension` library paths will need to match. E.g. for M1 Macs (`macos.debug.arm64` and `macos.release.arm64`) the path would be `"res://../rust/target/aarch64-apple-darwin/debug/{my-ext}.dylib"` - -2. A second file `res://.godot/extension_list.cfg` should be generated once you open the Godot editor for the first time. - If not, you can also manually create it, simply containing the Godot path to your `.gdextension` file: - ``` - res://MyExt.gdextension - ``` +## Getting started -### Examples +To dive into Rust development with gdext, check out [the godot-rust book][book]. The book is still under construction, +but already includes a tutorial to set up a simple example. -We highly recommend to have a look at a working example in the `examples/dodge-the-creeps` directory. -This integrates a small game with Godot and has all the necessary steps set up. +To consult the API reference, check out the online [API Docs]. -API documentation can be generated locally using `./check.sh doc` (use `dok` instead of `doc` to open the page in the browser). +Furthermore, we provide a small example game in the [`examples/dodge-the-creeps` directory][dodge-the-creeps]. If you need help, join our [Discord] server and ask in the `#help-gdext` channel! @@ -97,14 +56,16 @@ those changes available (and only those, no surrounding code). ## Contributing -Contributions are very welcome! If you want to help out, see [`Contributing.md`](Contributing.md) for some pointers on getting started! +Contributions are very welcome! If you want to help out, see [`Contributing.md`](Contributing.md) for some pointers on getting started. -[Godot]: https://godotengine.org +[#24]: https://github.com/godot-rust/gdext/issues/24 [`gdnative`]: https://github.com/godot-rust/gdnative -[mpl]: https://www.mozilla.org/en-US/MPL -[Website]: https://godot-rust.github.io [API Docs]: https://godot-rust.github.io/docs/gdext +[book]: https://godot-rust.github.io/book/gdext [Discord]: https://discord.gg/aKUCJ8rJsc +[dodge-the-creeps]: examples/dodge-the-creeps +[Godot]: https://godotengine.org [Mastodon]: https://mastodon.gamedev.place/@GodotRust +[mpl]: https://www.mozilla.org/en-US/MPL [Twitter]: https://twitter.com/GodotRust -[in the book]: https://godot-rust.github.io/book/gdext/intro \ No newline at end of file +[Website]: https://godot-rust.github.io