# Ruma – Your home in Matrix

A set of [Rust] crates (libraries) for interacting with the [Matrix] chat
network.

[website] • [chat] • [documentation][docs] ([unstable][unstable-docs])

[Rust]: https://rust-lang.org/
[Matrix]: https://matrix.org/
[website]: https://ruma.dev/
[chat]: https://matrix.to/#/#ruma:matrix.org
[docs]: https://docs.rs/ruma/
[unstable-docs]: https://docs.ruma.dev/ruma/

## Getting started

If you want to build a Matrix client or bot, have a look at [matrix-rust-sdk].
It builds on Ruma and includes handling of state storage, end-to-end encryption
and many other useful things.

For homeservers, bridges and harder-to-categorize software that works with
Matrix, you're at the right place. To get started, add `ruma` to your
dependencies:

```toml
# crates.io release
ruma = { version = "0.15.0", features = ["..."] }
# git dependency
ruma = { git = "https://github.com/ruma/ruma", branch = "main", features = ["..."] }
```

`ruma` re-exports all of the other crates, so you don't have to worry about
them as a user. Check out the documentation [on docs.rs][docs] (or on
[docs.ruma.dev][unstable-docs] if you use use the git dependency).

You can find a low level Matrix client in the [ruma-client repository](https://github.com/ruma/ruma-client).

You can also find a small number of examples in our dedicated
[ruma-examples repository](https://github.com/ruma/ruma-examples).

[matrix-rust-sdk]: https://github.com/matrix-org/matrix-rust-sdk#readme

## Status

Ruma 0.15.0 supports all events and REST endpoints of Matrix 1.18.

Only room versions enforcing canonical JSON (introduced with room version 6) are
supported. Room versions 1 through 5 are supported on a best effort basis, but a
missing feature or an incompatibility with a homeserver implementation are not
considered bugs. Clients should be able to work with those room versions,
granted parts of the room might break in some unconventional cases, but
homeservers based on Ruma **should not** advertise support for them.

Various changes from in-progress or finished MSCs are also implemented, gated
behind the `unstable-mscXXXX` (where `XXXX` is the MSC number) Cargo features.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Minimum Rust version

Ruma currently requires Rust 1.89. In general, we will never require beta or
nightly for crates.io releases of our crates, and we will try to avoid releasing
crates that depend on features that were only just stabilized.

`ruma-signatures` is an exception: It uses cryptographic libraries that often
use relatively new features and that we don't want to use outdated versions of.
It is guaranteed to work with whatever is the latest stable version though.

## License

[MIT](https://opensource.org/licenses/MIT)
