alex/agb
1
0
Fork 0
mirror of https://github.com/italicsjenga/agb.git synced 2024-12-23 00:01:34 +11:00
Code Issues Packages Projects Releases Wiki Activity
3502 commits 1 branch 0 tags 48 MiB
Rust 60.9%
Logos 32.8%
TypeScript 4.3%
Assembly 1.4%
Just 0.6%
Go to file
Gwilym Inzani 3e87a02d04
Update Rust crate thiserror to v2 (#804) 
This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
| [thiserror](https://redirect.github.com/dtolnay/thiserror) |
dependencies | major | `1` -> `2` |

---

### Release Notes

<details>
<summary>dtolnay/thiserror (thiserror)</summary>

###
[`v2.0.0`](https://redirect.github.com/dtolnay/thiserror/releases/tag/2.0.0)

[Compare
Source](https://redirect.github.com/dtolnay/thiserror/compare/1.0.68...2.0.0)

#### Breaking changes

- Referencing keyword-named fields by a raw identifier like `{r#type}`
inside a format string is no longer accepted; simply use the unraw name
like `{type}`
([#&#8203;347](https://redirect.github.com/dtolnay/thiserror/issues/347))

This aligns thiserror with the standard library's formatting macros,
which gained support for implicit argument capture later than the
release of this feature in thiserror 1.x.

    ```rust
    #[derive(Error, Debug)]
    #[error("... {type} ...")]  // Before: {r#type}
    pub struct Error {
        pub r#type: Type,
    }
    ```

- Trait bounds are no longer inferred on fields whose value is shadowed
by an explicit named argument in a format message
([#&#8203;345](https://redirect.github.com/dtolnay/thiserror/issues/345))

    ```rust
    // Before: impl<T: Octal> Display for Error<T>
    // After: impl<T> Display for Error<T>
    #[derive(Error, Debug)]
    #[error("{thing:o}", thing = "...")]
    pub struct Error<T> {
        thing: T,
    }
    ```

- Tuple structs and tuple variants can no longer use numerical `{0}`
`{1}` access at the same time as supplying extra positional arguments
for a format message, as this makes it ambiguous whether the number
refers to a tuple field vs a different positional arg
([#&#8203;354](https://redirect.github.com/dtolnay/thiserror/issues/354))

    ```rust
    #[derive(Error, Debug)]
    #[error("ambiguous: {0} {}", $N)]
// ^^^ Not allowed, use #[error("... {0} {n}", n = $N)]
    pub struct TupleError(i32);
    ```

- Code containing invocations of thiserror's `derive(Error)` must now
have a direct dependency on the `thiserror` crate regardless of the
error data structure's contents
([#&#8203;368](https://redirect.github.com/dtolnay/thiserror/issues/368),
[#&#8203;369](https://redirect.github.com/dtolnay/thiserror/issues/369),
[#&#8203;370](https://redirect.github.com/dtolnay/thiserror/issues/370),
[#&#8203;372](https://redirect.github.com/dtolnay/thiserror/issues/372))

#### Features

- Support disabling thiserror's standard library dependency by disabling
the default "std" Cargo feature: `thiserror = { version = "2",
default-features = false }`
([#&#8203;373](https://redirect.github.com/dtolnay/thiserror/issues/373))

- Support using `r#source` as field name to opt out of a field named
"source" being treated as an error's `Error::source()`
([#&#8203;350](https://redirect.github.com/dtolnay/thiserror/issues/350))

    ```rust
    #[derive(Error, Debug)]
    #[error("{source} ==> {destination}")]
    pub struct Error {
        r#source: char,
        destination: char,
    }

    let error = Error { source: 'S', destination: 'D' };
    ```

- Infinite recursion in a generated Display impl now produces an
`unconditional_recursion` warning
([#&#8203;359](https://redirect.github.com/dtolnay/thiserror/issues/359))

    ```rust
    #[derive(Error, Debug)]
    #[error("??? {self}")]
    pub struct Error;
    ```

- A new attribute `#[error(fmt = path::to::myfmt)]` can be used to write
formatting logic for an enum variant out-of-line
([#&#8203;367](https://redirect.github.com/dtolnay/thiserror/issues/367))

    ```rust
    #[derive(Error, Debug)]
    pub enum Error {
        #[error(fmt = demo_fmt)]
        Demo { code: u16, message: Option<String> },
    }

fn demo_fmt(code: &u16, message: &Option<String>, formatter: &mut
fmt::Formatter) -> fmt::Result {
        write!(formatter, "{code}")?;
        if let Some(msg) = message {
            write!(formatter, " - {msg}")?;
        }
        Ok(())
    }
    ```

- Enums with an enum-level format message are now able to have
individual variants that are `transparent` to supersede the enum-level
message
([#&#8203;366](https://redirect.github.com/dtolnay/thiserror/issues/366))

    ```rust
    #[derive(Error, Debug)]
    #[error("my error {0}")]
    pub enum Error {
        Json(#[from] serde_json::Error),
        Yaml(#[from] serde_yaml::Error),
        #[error(transparent)]
        Other(#[from] anyhow::Error),
    }
    ```

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined),
Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you
are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR was generated by [Mend Renovate](https://mend.io/renovate/).
View the [repository job
log](https://developer.mend.io/github/agbrs/agb).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzOC4xNDIuNyIsInVwZGF0ZWRJblZlciI6IjM4LjE0Mi43IiwidGFyZ2V0QnJhbmNoIjoibWFzdGVyIiwibGFiZWxzIjpbXX0=-->
2024-11-06 09:38:03 +00:00
.github Update dependency ubuntu to v24 2024-09-26 22:51:07 +00:00
.vscode add projects to workspace 2024-01-13 10:05:04 +00:00
agb Add some keywords to the main agb crates 2024-10-30 11:43:48 +00:00
agb-debug Update Rust crate thiserror to v2 2024-11-06 03:20:03 +00:00
agb-fixnum Add some keywords to the main agb crates 2024-10-30 11:43:48 +00:00
agb-gbafix Release v0.21.1 2024-10-02 23:08:04 +01:00
agb-hashmap Add some keywords to the main agb crates 2024-10-30 11:43:48 +00:00
agb-image-converter Release v0.21.1 2024-10-02 23:08:04 +01:00
agb-macros Release v0.21.1 2024-10-02 23:08:04 +01:00
agb-sound-converter Release v0.21.1 2024-10-02 23:08:04 +01:00
book Release v0.21.1 2024-10-02 23:08:04 +01:00
emulator Update Rust crate thiserror to v2 2024-11-06 03:20:03 +00:00
examples Fix clippy lints in games too 2024-10-05 22:02:10 +01:00
template Release v0.21.1 2024-10-02 23:08:04 +01:00
tools also update build-dependencies 2024-09-24 20:27:15 +01:00
tracker Fix the xmrs version since we've had failures twice 2024-10-15 19:58:14 +01:00
website Update Javascript packages (non-major) 2024-10-30 11:19:49 +00:00
.gitignore ignore Cargo lockfiles 2024-04-09 20:42:11 +01:00
.gitmodules replace mgba-test-runner with better bindings 2023-08-08 09:48:07 +01:00
Cargo.toml Add template to workspace exclude 2024-07-24 17:16:39 +01:00
CHANGELOG.md Changelog entry for serde support in agb-hashmap 2024-10-30 11:18:07 +00:00
justfile Ensure the hashmap tests get run with serde 2024-10-30 11:08:49 +00:00
LICENSE add project wide MPLv2 license 2021-05-29 15:22:19 +01:00
logo-original.png Add logo to repo and readme 2021-07-05 23:56:43 +01:00
README.md Can just refer to the emulator directly once 2024-04-30 20:23:49 +01:00

README.md

AGB

Rust for the Game Boy Advance

Docs Build Licence Crates.io

AGB logo

This is a library for making games on the Game Boy Advance using the Rust programming language. The library's main focus is to provide an abstraction that allows you to develop games which take advantage of the GBA's capabilities without needing to have extensive knowledge of its low-level implementation.

agb provides the following features:

  • Simple build process with minimal dependencies
  • Built in importing of sprites, backgrounds, music and sound effects
  • High performance audio mixer and optional tracker which can play .xm files
  • Easy to use sprite and tiled background usage
  • A global allocator allowing for use of both core and alloc

The documentation for the latest release can be found on docs.rs.

Getting started

The best way to get started with agb is to use the template, either within the template directory in this repository or cloning the template repository.

Once you have done this, you will find further instructions within the README in the template.

There is an (in progress) tutorial which you can find on the project website.

Help / Support

If you need any help, the discussions page is a great place to get help from the creators and contributors.

Feel free to create a new discussion in the Q&A category and we'll do our best to help!

Contributing to agb itself

In order to contribute to agb itself, you will need a few extra tools on top of what you would need to just write games for the Game Boy Advance using this library:

  • Recent rustup, see the rust website for instructions for your operating system.
    • You can update rustup with rustup self update, or using your package manager if you obtained rustup in this way.
  • libelf and cmake
    • Debian and derivatives: sudo apt install libelf-dev cmake
    • Arch Linux and derivatives: pacman -S libelf cmake
  • mgba-test-runner
    • Run cargo install --path emulator/test-runner inside this directory
  • The 'just' build tool
    • Install with cargo install just
  • mdbook
    • Install with cargo install mdbook
  • miri
    • Some of the unsafe code is tested using miri, install with rustup component add miri

With all of this installed, you should be able to run a full build of agb using by running

just ci

Note that before you create a PR, please file an issue so we can discuss what you are looking to change.

Structure of the repo

agb-debug - a tool you can use to decode agb stacktraces

agb-fixnum - a simple fixed point number storage since the GBA doesn't have a floating point unit, so required for performant decimals.

agb-gbafix - a clean-room reimplementation of the gbafix utility that accepts elf files rather than binaries

agb-hashmap - an no_std hashmap implementation tuned for use on the game boy advance

agb-image-converter - a crate which converts images in normal formats to a format supported by the game boy advance

agb-macros - miscellaneous proc-macros which have to be in a different crate

agb-sound-converter - a crate which converts wav files into a format supported by the game boy advance

agb - the main library code

agb/examples - basic examples often targeting 1 feature, you can run these using just run-example <example-name>

book - the source for the tutorial and website

book/games - games made as part of the tutorial

emulator - Rust bindings for the mgba emulator along with the test runner you can use to run unit tests

examples - bigger examples of a complete game, made during game jams

template - the source for the template repository

tools - misc. tools used in the development of agb itself

tracker - crates that make up the agb-tracker library which allows playing of tracker files

website - the source of the website

Stability

While agb is in the pre-1.0 phase, we follow a semi-semantic versioning scheme to ensure compatibility between minor releases. Specifically, any 0.x.y release is guaranteed to be compatible with another 0.x.z release provided that y > z, but there may be breaking changes between minor releases (i.e., changes to the second digit, e.g., between 0.1 and 0.2).

Once agb reaches version 1.0, we will transition to stronger semantic versioning, meaning that any breaking changes will be indicated by an increment to the major version (i.e., the first digit, e.g., from 1.0 to 2.0).

Acknowledgments

agb would not be possible without the help from the following (non-exhaustive) list of projects:

  • The amazing work of the rust-console for making this all possible in the first place
  • The asefile crate for loading aseprite files
  • agbabi for providing high performance alternatives to common methods
  • mgba for all the useful debugging / developer tools built in to the emulator

Licence

agb and all its subcrates are released under MPL version 2.0. See full licence text in the LICENSE file.

agb contains a subset of the code from agbabi which is released under a zlib style licence, details for which you can find under agb/src/agbabi.

The template is released under CC0 to allow you to make whatever changes you wish.

The agb logo is released under Creative Commons Attribution-ShareAlike 4.0

The music used for the examples is by Josh Woodward and released under Creative Commons Attribution 4.0