forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5241e09671
bevy/tools/compile_fail_utils
History
Zachary Harrold 5241e09671
Upgrade to Rust Edition 2024 (#17967) 
# Objective

- Fixes #17960

## Solution

- Followed the [edition upgrade
guide](https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html)

## Testing

- CI

---

## Summary of Changes

### Documentation Indentation

When using lists in documentation, proper indentation is now linted for.
This means subsequent lines within the same list item must start at the
same indentation level as the item.

```rust
/* Valid */
/// - Item 1
///   Run-on sentence.
/// - Item 2
struct Foo;

/* Invalid */
/// - Item 1
///     Run-on sentence.
/// - Item 2
struct Foo;
```

### Implicit `!` to `()` Conversion

`!` (the never return type, returned by `panic!`, etc.) no longer
implicitly converts to `()`. This is particularly painful for systems
with `todo!` or `panic!` statements, as they will no longer be functions
returning `()` (or `Result<()>`), making them invalid systems for
functions like `add_systems`. The ideal fix would be to accept functions
returning `!` (or rather, _not_ returning), but this is blocked on the
[stabilisation of the `!` type
itself](https://doc.rust-lang.org/std/primitive.never.html), which is
not done.

The "simple" fix would be to add an explicit `-> ()` to system
signatures (e.g., `|| { todo!() }` becomes `|| -> () { todo!() }`).
However, this is _also_ banned, as there is an existing lint which (IMO,
incorrectly) marks this as an unnecessary annotation.

So, the "fix" (read: workaround) is to put these kinds of `|| -> ! { ...
}` closuers into variables and give the variable an explicit type (e.g.,
`fn()`).

```rust
// Valid
let system: fn() = || todo!("Not implemented yet!");
app.add_systems(..., system);

// Invalid
app.add_systems(..., || todo!("Not implemented yet!"));
```

### Temporary Variable Lifetimes

The order in which temporary variables are dropped has changed. The
simple fix here is _usually_ to just assign temporaries to a named
variable before use.

### `gen` is a keyword

We can no longer use the name `gen` as it is reserved for a future
generator syntax. This involved replacing uses of the name `gen` with
`r#gen` (the raw-identifier syntax).

### Formatting has changed

Use statements have had the order of imports changed, causing a
substantial +/-3,000 diff when applied. For now, I have opted-out of
this change by amending `rustfmt.toml`

```toml
style_edition = "2021"
```

This preserves the original formatting for now, reducing the size of
this PR. It would be a simple followup to update this to 2024 and run
`cargo fmt`.

### New `use<>` Opt-Out Syntax

Lifetimes are now implicitly included in RPIT types. There was a handful
of instances where it needed to be added to satisfy the borrow checker,
but there may be more cases where it _should_ be added to avoid
breakages in user code.

### `MyUnitStruct { .. }` is an invalid pattern

Previously, you could match against unit structs (and unit enum
variants) with a `{ .. }` destructuring. This is no longer valid.

### Pretty much every use of `ref` and `mut` are gone

Pattern binding has changed to the point where these terms are largely
unused now. They still serve a purpose, but it is far more niche now.

### `iter::repeat(...).take(...)` is bad

New lint recommends using the more explicit `iter::repeat_n(..., ...)`
instead.

## Migration Guide

The lifetimes of functions using return-position impl-trait (RPIT) are
likely _more_ conservative than they had been previously. If you
encounter lifetime issues with such a function, please create an issue
to investigate the addition of `+ use<...>`.

## Notes

- Check the individual commits for a clearer breakdown for what
_actually_ changed.

---------

Co-authored-by: François Mockers <francois.mockers@vleue.com>
2025-02-24 03:54:47 +00:00
..
src Prefer Display over Debug (#16112) 2024-12-27 00:40:06 +00:00
tests Fix compile_fail compile fail (#16805) 2024-12-17 00:01:08 +00:00
Cargo.toml Upgrade to Rust Edition 2024 (#17967) 2025-02-24 03:54:47 +00:00
README.md Add benchmarks and compile_fail tests back to workspace (#16858) 2024-12-21 22:30:29 +00:00

README.md

Helpers for compile fail tests

This crate contains everything needed to set up compile tests for the Bevy repo. The CI workflow executes these tests on the stable rust toolchain (see tools/ci).

Writing new test cases

Test cases are annotated .rs files. These annotations define how the test case should be run and what we're expecting to fail. Please see https://github.com/oli-obk/ui_test/blob/main/README.md for more information.

Annotations can roughly be split into global annotations which are prefixed with //@ and define how tests should be run and error annotations which are prefixed with //~ and define where errors we expect to happen. From the global annotations, you're only likely to care about //@check-pass which will make any compile errors in the test trigger a test failure.

The error annotations are composed of two parts. An optional location specifier:

  • ^ The error happens on the line above.
  • v The error happens on the line below.
  • | The error annotation is connected to another one.
  • If the location specifier is missing, the error is assumed to happen on the same line as the annotation.

An error matcher:

  • E#### The error we're expecting has the #### rustc error code, e.g E0499
  • <lint_name> The given compiler lint is triggered, e.g. dead_code
  • LEVEL: <substring> A compiler error of the given level (valid levels are: ERROR, HELP, WARN or NOTE) will be raised and it will contain the substring. Substrings can contain spaces.
  • LEVEL: /<regex>/ Same as above but a regex is used to match the error message.

An example of an error annotation would be //~v ERROR: missing trait. This error annotation will match any error occurring on the line below that contains the substring missing trait.

Adding compile fail tests for a crate that doesn't have them

This will be a rather involved process. You'll have to:

  • Create a subdirectory named compile_fail within the crate you are testing. (E.g. bevy_ecs/compile_fail for bevy_ecs.)
  • Add compile_fail_utils as a dev-dependency.
  • Create a folder called tests within the new crate.
  • Add a test runner file to this folder. The file should contain a main function calling one of the test functions defined in this crate.
  • Add a [[test]] table to the Cargo.toml. This table will need to contain harness = false and name = <name of the test runner file you defined>.
  • Modify the CI tool to run cargo test on this crate.
  • And finally, write your compile tests.

If you have any questions, don't be scared to ask for help.

A note about .stderr files

We're capable of generating .stderr files for all our compile tests. These files contain the error output generated by the test. To create or regenerate them yourself, trigger the tests with the BLESS environment variable set to any value (e.g. BLESS="some symbolic value"). We currently have to ignore mismatches between these files and the actual stderr output from their corresponding test due to issues with file paths. We attempt to sanitize file paths but for proc-macros, the compiler error messages contain file paths to the current toolchain's copy of the standard library. If we knew of a way to construct a path to the current toolchains folder we could fix this.