Skip to content

Commit

Permalink
Update ReadMe + Contribution guidelines
Browse files Browse the repository at this point in the history 
ReadMe.md
* "Experimental" warning is less alarming
* Usage examples moved to book
* Mention brief philosophy

Contributing.md
* Dev-Tools moved to book
  • Loading branch information
@Bromeon
Bromeon committed Jul 29, 2023
1 parent 443f25a commit 41fb096
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 202 deletions.
140 changes: 4 additions & 136 deletions Contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
<br/>

# 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<Node> = ctx.scene_tree.share();

// If you don't need the scene, you can also construct free-standing nodes:
let node: Gd<Node3D> = 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).
93 changes: 27 additions & 66 deletions ReadMe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!

Expand All @@ -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
[Website]: https://godot-rust.github.io

0 comments on commit 41fb096

Please sign in to comment.