Rocket/README.md

166 lines
6.8 KiB
Markdown
Raw Normal View History

# Rocket
[![Build Status](https://github.com/SergioBenitez/Rocket/workflows/CI/badge.svg)](https://github.com/SergioBenitez/Rocket/actions)
[![Rocket Homepage](https://img.shields.io/badge/web-rocket.rs-red.svg?style=flat&label=https&colorB=d33847)](https://rocket.rs)
[![Current Crates.io Version](https://img.shields.io/crates/v/rocket.svg)](https://crates.io/crates/rocket)
2020-02-27 22:37:27 +00:00
[![Matrix: #rocket:mozilla.org](https://img.shields.io/badge/style-%23rocket:mozilla.org-blue.svg?style=flat&label=[m])](https://chat.mozilla.org/#/room/#rocket:mozilla.org)
[![IRC: #rocket on chat.freenode.net](https://img.shields.io/badge/style-%23rocket-blue.svg?style=flat&label=freenode)](https://kiwiirc.com/client/chat.freenode.net/#rocket)
2016-04-05 02:04:46 +00:00
Rocket is an async web framework for Rust with a focus on usability, security,
extensibility, and speed.
2016-03-12 18:54:38 +00:00
```rust
#[macro_use] extern crate rocket;
2016-03-12 18:54:38 +00:00
2016-09-04 11:10:35 +00:00
#[get("/<name>/<age>")]
fn hello(name: String, age: u8) -> String {
2016-04-03 11:28:09 +00:00
format!("Hello, {} year old named {}!", age, name)
2016-03-12 18:54:38 +00:00
}
#[launch]
fn rocket() -> rocket::Rocket {
rocket::ignite().mount("/hello", routes![hello])
2016-03-12 18:54:38 +00:00
}
```
2016-04-06 19:50:51 +00:00
Visiting `localhost:8000/hello/John/58`, for example, will trigger the `hello`
route resulting in the string `Hello, 58 year old named John!` being sent to the
browser. If an `<age>` string was passed in that can't be parsed as a `u8`, the
route won't get called, resulting in a 404 error.
## Documentation
2016-09-13 23:32:57 +00:00
Rocket is extensively documented:
2016-09-13 23:32:57 +00:00
2016-12-20 04:50:14 +00:00
* [Overview]: A brief look at what makes Rocket special.
* [Quickstart]: How to get started as quickly as possible.
* [Getting Started]: How to start your first Rocket project.
* [Guide]: A detailed guide and reference to Rocket.
* [API Documentation]: The "rustdocs".
2019-05-13 23:18:48 +00:00
[Quickstart]: https://rocket.rs/guide/quickstart
[Getting Started]: https://rocket.rs/guide/getting-started
2019-05-13 23:58:11 +00:00
[Overview]: https://rocket.rs/overview/
[Guide]: https://rocket.rs/guide/
[API Documentation]: https://api.rocket.rs/rocket/
2016-09-04 22:07:47 +00:00
2020-02-27 22:37:27 +00:00
The official community support channels are [`#rocket:mozilla.org`] on Matrix
and the bridged [`#rocket`] IRC channel on Freenode at `chat.freenode.net`. We
2020-07-22 20:03:23 +00:00
recommend joining us on [Matrix via Element]. If your prefer IRC, you can join
via the [Kiwi IRC client] or a client of your own.
2020-02-27 22:37:27 +00:00
[`#rocket:mozilla.org`]: https://chat.mozilla.org/#/room/#rocket:mozilla.org
[`#rocket`]: https://kiwiirc.com/client/chat.freenode.net/#rocket
2020-07-22 20:03:23 +00:00
[Matrix via Element]: https://chat.mozilla.org/#/room/#rocket:mozilla.org
2020-02-27 22:37:27 +00:00
[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket
2017-01-06 06:19:01 +00:00
## Examples
2016-09-04 22:07:47 +00:00
An extensive number of examples are provided in the `examples/` directory. Each
example can be compiled and run with Cargo. For instance, the following sequence
of commands builds and runs the `Hello, world!` example:
2016-03-12 18:54:38 +00:00
```sh
2016-04-06 19:50:51 +00:00
cd examples/hello_world
2016-03-12 18:54:38 +00:00
cargo run
```
You should see `Hello, world!` by visiting `http://localhost:8000`.
## Building and Testing
2016-03-12 18:54:38 +00:00
### Core and Contrib
The `core` directory contains the three core libraries: `lib`, `codegen`, and
`http`. The `contrib` directory contains officially supported community
contributions and similarly consists of `lib` and `codegen`.
2016-03-12 18:54:38 +00:00
Public APIs are exposed via `lib` packages: `core/lib` is distributed as the
`rocket` crate while `contrib/lib` is distributed as the `rocket_contrib` crate.
The remaining crates are implementation details.
### Library Testing
Rocket's complete test suite can be run with `./scripts/test.sh` from the root
of the source tree. The script builds and tests all libraries and examples. It
accepts the following flags:
* `--contrib`: tests each `contrib` feature individually
* `--core`: tests each `core` feature individually
* `--release`: runs the testing suite in `release` mode
2019-05-13 23:18:48 +00:00
Additionally, a `+${toolchain}` flag, where `${toolchain}` is a valid `rustup`
toolchain string, can be passed as the first parameter. The flag is forwarded to
`cargo` commands.
To test crates individually, simply run `cargo test --all-features` in the
crate's directory.
### Codegen Testing
Code generation diagnostics are tested using [`trybuild`]; tests can be found in
the `codegen/tests/ui-fail` directory of both `core` and `contrib`. Each test is
symlinked into sibling `ui-fail-stable` and `ui-fail-nightly` directories which
contain the expected error output for stable and nightly compilers,
respectively.
[`trybuild`]: https://docs.rs/trybuild/1
## Documentation
API documentation is built with `./scripts/mk-docs.sh`. The resulting assets are
uploaded to [api.rocket.rs](https://api.rocket.rs/).
Documentation for a released version `${x}` can be found at
`https://api.rocket.rs/v${x}` and `https://rocket.rs/v${x}`. For instance, the
documentation for `0.4` can be found at https://api.rocket.rs/v0.4 and
https://rocket.rs/v0.4. Documentation for unreleased versions in branch
`${branch}` be found at `https://api.rocket.rs/${branch}` and
`https://rocket.rs/${branch}`. For instance, the documentation for the `master`
branch can be found at https://api.rocket.rs/master and
https://rocket.rs/master. Documentation for unreleased branches is updated
periodically.
## Contributing
Contributions are absolutely, positively welcome and encouraged! Contributions
come in many forms. You could:
2019-05-13 23:18:48 +00:00
1. Submit a feature request or bug report as an [issue].
2. Ask for improved documentation as an [issue].
3. Comment on [issues that require feedback].
4. Contribute code via [pull requests].
[issue]: https://github.com/SergioBenitez/Rocket/issues
2019-05-13 23:58:11 +00:00
[issues that require feedback]: https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22
[pull requests]: https://github.com/SergioBenitez/Rocket/pulls
We aim to keep Rocket's code quality at the highest level. This means that any
code you contribute must be:
* **Commented:** Complex and non-obvious functionality must be properly
commented.
* **Documented:** Public items _must_ have doc comments with examples, if
applicable.
* **Styled:** Your code's style should match the existing and surrounding code
style.
* **Simple:** Your code should accomplish its task as simply and
idiomatically as possible.
* **Tested:** You must write (and pass) convincing tests for any new
functionality.
* **Focused:** Your code should do what it's supposed to and nothing more.
2016-03-12 18:54:38 +00:00
All pull requests are code reviewed and tested by the CI. Note that unless you
explicitly state otherwise, any contribution intentionally submitted for
inclusion in Rocket by you shall be dual licensed under the MIT License and
Apache License, Version 2.0, without any additional terms or conditions.
2016-12-16 01:19:23 +00:00
## License
Rocket is licensed under either of the following, at your option:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
* MIT License ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
The Rocket website source is licensed under [separate terms](site#license).