rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rework docs for stable and async support.

This commit is contained in:
Sergio Benitez 2020-07-21 14:28:49 -07:00
parent cd7e99a535
commit b47d1b8f0f
4 changed files with 78 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@ -6,8 +6,8 @@
[![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) [![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) [![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)
Rocket is a web framework for Rust (nightly) with a focus on ease-of-use, Rocket is an async web framework for Rust with a focus on usability, security,
expressibility, and speed. Here's an example of a complete Rocket application: extensibility, and speed.
```rust ```rust
#[macro_use] extern crate rocket; #[macro_use] extern crate rocket;
@ -54,27 +54,10 @@ the [Kiwi IRC client] or a client of your own.
[Matrix via Riot]: https://chat.mozilla.org/#/room/#rocket:mozilla.org [Matrix via Riot]: https://chat.mozilla.org/#/room/#rocket:mozilla.org
[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket [Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket
## Building ## Examples
### Nightly 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
Rocket requires a nightly version of Rust as it makes heavy use of syntax
extensions. This means that the first two unwieldly lines in the introductory
example above are required.
### Core, Codegen, and Contrib
All of the Rocket libraries are managed by Cargo. As a result, compiling them is
simple.
* Core: `cd lib && cargo build`
* Codegen: `cd codegen && cargo build`
* Contrib: `cd contrib && cargo build --all-features`
### Examples
Rocket ships with an extensive number of examples in the `examples/` directory
which can be compiled and run with Cargo. For instance, the following sequence
of commands builds and runs the `Hello, world!` example: of commands builds and runs the `Hello, world!` example:
```sh ```sh
@ -84,37 +67,57 @@ cargo run
You should see `Hello, world!` by visiting `http://localhost:8000`. You should see `Hello, world!` by visiting `http://localhost:8000`.
## Testing ## Building and Testing
To test Rocket, simply run `./scripts/test.sh` from the root of the source tree. ### Core and Contrib
This will build and test the `core`, `codegen`, and `contrib` libraries as well
as all of the examples. The `test.sh` script accepts no flags or either the
`--release` flag to test in release mode or the `--contrib` flag to test all
`contrib` modules individually. This script gets run by CI.
To test a crate individually, run `cargo test --all-features` in the The `core` directory contains the three core libraries: `lib`, `codegen`, and
corresponding crate directory. `http`. The `contrib` directory contains officially supported community
contributions and similarly consists of `lib` and `codegen`.
### Core 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.
Testing for the core library is done inline in the corresponding module. For ### Library Testing
example, the tests for routing can be found at the bottom of the
`lib/src/router/mod.rs` file.
### Codegen 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:
Code generation tests can be found in `codegen/tests`. We use the [compiletest] * `--contrib`: tests each `contrib` feature individually
library, which was extracted from `rustc`, for testing. See the [compiler test * `--core`: tests each `core` feature individually
documentation] for information on how to write compiler tests. * `--release`: runs the testing suite in `release` mode
[compiletest]: https://crates.io/crates/compiletest_rs Additionally, a `+${toolchain}` flag, where `${toolchain}` is a valid `rustup`
[compiler test documentation]: https://github.com/rust-lang/rust/blob/master/src/test/COMPILER_TESTS.md 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 ## Documentation
You can build the Rocket API documentation locally by running API documentation is built with `./scripts/mk-docs.sh`. The resulting assets are
`./scripts/mk-docs.sh`. The resulting documentation is what gets uploaded to uploaded to [api.rocket.rs](https://api.rocket.rs/).
[api.rocket.rs](https://api.rocket.rs/).
Documentation for a released version `${x}` can be found at
`https://api.rocket.rs/v${x}`. For instance, the documentation for `0.4` can be
found at https://api.rocket.rs/v0.4. Documentation for unreleased versions in
branch `${branch}` be found at `https://api.rocket.rs/${branch}`. For instance,
the documentation for the `master` branch can be found at
https://api.rocket.rs/master. Documentation for unreleased branches is updated
periodically.
## Contributing ## Contributing
@ -133,14 +136,17 @@ come in many forms. You could:
We aim to keep Rocket's code quality at the highest level. This means that any We aim to keep Rocket's code quality at the highest level. This means that any
code you contribute must be: code you contribute must be:
* **Commented:** Public items _must_ be commented. * **Commented:** Complex and non-obvious functionality must be properly
* **Documented:** Exposed items _must_ have rustdoc comments with commented.
examples, if applicable. * **Documented:** Public items _must_ have doc comments with examples, if
* **Styled:** Your code should be `rustfmt`'d when possible. applicable.
* **Styled:** Your code's style should match the existing and surrounding code
style.
* **Simple:** Your code should accomplish its task as simply and * **Simple:** Your code should accomplish its task as simply and
idiomatically as possible. idiomatically as possible.
* **Tested:** You must add (and pass) convincing tests for any functionality you add. * **Tested:** You must write (and pass) convincing tests for any new
* **Focused:** Your code should do what it's supposed to do and nothing more. functionality.
* **Focused:** Your code should do what it's supposed to and nothing more.
All pull requests are code reviewed and tested by the CI. Note that unless you All pull requests are code reviewed and tested by the CI. Note that unless you
explicitly state otherwise, any contribution intentionally submitted for explicitly state otherwise, any contribution intentionally submitted for

2
core/lib/Cargo.toml
View File

@ -3,7 +3,7 @@ name = "rocket"
version = "0.5.0-dev" version = "0.5.0-dev"
authors = ["Sergio Benitez <sb@sergio.bz>"] authors = ["Sergio Benitez <sb@sergio.bz>"]
description = """ description = """
Web framework for nightly with a focus on ease-of-use, expressibility, and speed. Web framework with a focus on usability, security, extensibility, and speed.
""" """
documentation = "https://api.rocket.rs/v0.5/rocket/" documentation = "https://api.rocket.rs/v0.5/rocket/"
homepage = "https://rocket.rs" homepage = "https://rocket.rs"

9
site/guide/1-quickstart.md
View File

@ -1,10 +1,9 @@
# Quickstart # Quickstart
Before you can start writing a Rocket application, you'll need a **nightly** Before you can start writing a Rocket application, you'll need to install the
version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to Rust toolchain. We recommend using [rustup](https://rustup.rs/). If you don't
install or configure such a version. If you don't have Rust installed and would have Rust installed and would like extra guidance doing so, see the [getting
like extra guidance doing so, see the [getting started](../getting-started) started](../getting-started) section.
section.
## Running Examples ## Running Examples

44
site/guide/2-getting-started.md
View File

@ -1,40 +1,33 @@
# Getting Started # Getting Started
Let's create and run our first Rocket application. We'll ensure we have a Let's create and run our first Rocket application. We'll ensure we have a
compatible version of Rust, create a new Cargo project that depends on Rocket, compatible Rust toolchain installed, create a new Cargo project that depends on
and then run the application. Rocket, and then run the application.
## Installing Rust ## Installing Rust
Rocket makes abundant use of Rust's syntax extensions and other advanced, Rocket makes use of the latest Rust features. Because of this, we'll need a
unstable features. Because of this, we'll need to use a nightly version of Rust. recent release of Rust to run Rocket applications. If you already have a working
If you already have a working installation of the latest Rust nightly, feel free installation of the latest Rust compiler, feel free to skip to the next section.
to skip to the next section.
To install a nightly version of Rust, we recommend using `rustup`. Install To install the latst version of Rust, we recommend using `rustup`. Install
`rustup` by following the instructions on [its website](https://rustup.rs/). `rustup` by following the instructions on [its website](https://rustup.rs/).
Once `rustup` is installed, configure Rust nightly as your default toolchain by Once `rustup` is installed, ensure the latest toolchain is installled by running
running the command: the command:
```sh ```sh
rustup default nightly rustup default stable
``` ```
If you prefer, once we setup a project directory in the following section, you ! note: You may prefer to develop using the _nightly_ channel.
can use per-directory overrides to use the nightly version _only_ for your
Rocket project by running the following command in the directory:
```sh The nightly Rust toolchain enables certain improved developer experiences,
rustup override set nightly such as better compile-time diagnostics, when developing with Rocket. You may
``` choose to develop on the nightly channel to take advantage of these improved
experiences. Note that all Rocket features are available across all Rust
channels.
! warning: Rocket requires the _latest_ version of Rust nightly. To set the nightly toolchain as your default, run `rustup default nightly`.
If your Rocket application suddenly stops building, ensure you're using the
latest version of Rust nightly and Rocket by updating your toolchain and
dependencies with:
`rustup update && cargo update`
## Hello, world! ## Hello, world!
@ -64,7 +57,7 @@ fn index() -> &'static str {
"Hello, world!" "Hello, world!"
} }
#[rocket::launch] #[launch]
fn rocket() -> rocket::Rocket { fn rocket() -> rocket::Rocket {
rocket::ignite().mount("/", routes![index]) rocket::ignite().mount("/", routes![index])
} }
@ -96,5 +89,4 @@ Visit `http://localhost:8000` to see your first Rocket application in action!
You can disable colors and emoji by setting the `ROCKET_CLI_COLORS` You can disable colors and emoji by setting the `ROCKET_CLI_COLORS`
environment variable to `0` or `off` when running a Rocket binary: environment variable to `0` or `off` when running a Rocket binary:
`ROCKET_CLI_COLORS=off cargo run`.
`ROCKET_CLI_COLORS=off cargo run`