mirror of https://github.com/rwf2/Rocket.git
Rework docs for stable and async support.
This commit is contained in:
Sergio Benitez
parent
cd7e99a535
commit
b47d1b8f0f
104
README.md
104
README.md
|
|
@ -6,8 +6,8 @@
|
|||
[](https://chat.mozilla.org/#/room/#rocket:mozilla.org)
|
||||
[](https://kiwiirc.com/client/chat.freenode.net/#rocket)
|
||||
|
||||
Rocket is a web framework for Rust (nightly) with a focus on ease-of-use,
|
||||
expressibility, and speed. Here's an example of a complete Rocket application:
|
||||
Rocket is an async web framework for Rust with a focus on usability, security,
|
||||
extensibility, and speed.
|
||||
|
||||
```rust
|
||||
#[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
|
||||
[Kiwi IRC Client]: https://kiwiirc.com/client/chat.freenode.net/#rocket
|
||||
|
||||
## Building
|
||||
## Examples
|
||||
|
||||
### Nightly
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
```sh
|
||||
|
|
@ -84,37 +67,57 @@ cargo run
|
|||
|
||||
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.
|
||||
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.
|
||||
### Core and Contrib
|
||||
|
||||
To test a crate individually, run `cargo test --all-features` in the
|
||||
corresponding crate directory.
|
||||
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`.
|
||||
|
||||
### 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
|
||||
example, the tests for routing can be found at the bottom of the
|
||||
`lib/src/router/mod.rs` file.
|
||||
### Library Testing
|
||||
|
||||
### 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]
|
||||
library, which was extracted from `rustc`, for testing. See the [compiler test
|
||||
documentation] for information on how to write compiler tests.
|
||||
* `--contrib`: tests each `contrib` feature individually
|
||||
* `--core`: tests each `core` feature individually
|
||||
* `--release`: runs the testing suite in `release` mode
|
||||
|
||||
[compiletest]: https://crates.io/crates/compiletest_rs
|
||||
[compiler test documentation]: https://github.com/rust-lang/rust/blob/master/src/test/COMPILER_TESTS.md
|
||||
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
|
||||
|
||||
You can build the Rocket API documentation locally by running
|
||||
`./scripts/mk-docs.sh`. The resulting documentation is what gets uploaded to
|
||||
[api.rocket.rs](https://api.rocket.rs/).
|
||||
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}`. 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
|
||||
|
||||
|
|
@ -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
|
||||
code you contribute must be:
|
||||
|
||||
* **Commented:** Public items _must_ be commented.
|
||||
* **Documented:** Exposed items _must_ have rustdoc comments with
|
||||
examples, if applicable.
|
||||
* **Styled:** Your code should be `rustfmt`'d when possible.
|
||||
* **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 add (and pass) convincing tests for any functionality you add.
|
||||
* **Focused:** Your code should do what it's supposed to do and nothing more.
|
||||
* **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.
|
||||
|
||||
All pull requests are code reviewed and tested by the CI. Note that unless you
|
||||
explicitly state otherwise, any contribution intentionally submitted for
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name = "rocket"
|
|||
version = "0.5.0-dev"
|
||||
authors = ["Sergio Benitez <sb@sergio.bz>"]
|
||||
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/"
|
||||
homepage = "https://rocket.rs"
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
# Quickstart
|
||||
|
||||
Before you can start writing a Rocket application, you'll need a **nightly**
|
||||
version of Rust installed. We recommend you use [rustup](https://rustup.rs/) to
|
||||
install or configure such a version. If you don't have Rust installed and would
|
||||
like extra guidance doing so, see the [getting started](../getting-started)
|
||||
section.
|
||||
Before you can start writing a Rocket application, you'll need to install the
|
||||
Rust toolchain. We recommend using [rustup](https://rustup.rs/). If you don't
|
||||
have Rust installed and would like extra guidance doing so, see the [getting
|
||||
started](../getting-started) section.
|
||||
|
||||
## Running Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -1,40 +1,33 @@
|
|||
# Getting Started
|
||||
|
||||
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,
|
||||
and then run the application.
|
||||
compatible Rust toolchain installed, create a new Cargo project that depends on
|
||||
Rocket, and then run the application.
|
||||
|
||||
## Installing Rust
|
||||
|
||||
Rocket makes abundant use of Rust's syntax extensions and other advanced,
|
||||
unstable features. Because of this, we'll need to use a nightly version of Rust.
|
||||
If you already have a working installation of the latest Rust nightly, feel free
|
||||
to skip to the next section.
|
||||
Rocket makes use of the latest Rust features. Because of this, we'll need a
|
||||
recent release of Rust to run Rocket applications. If you already have a working
|
||||
installation of the latest Rust compiler, feel free 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/).
|
||||
Once `rustup` is installed, configure Rust nightly as your default toolchain by
|
||||
running the command:
|
||||
Once `rustup` is installed, ensure the latest toolchain is installled by running
|
||||
the command:
|
||||
|
||||
```sh
|
||||
rustup default nightly
|
||||
rustup default stable
|
||||
```
|
||||
|
||||
If you prefer, once we setup a project directory in the following section, you
|
||||
can use per-directory overrides to use the nightly version _only_ for your
|
||||
Rocket project by running the following command in the directory:
|
||||
! note: You may prefer to develop using the _nightly_ channel.
|
||||
|
||||
```sh
|
||||
rustup override set nightly
|
||||
```
|
||||
The nightly Rust toolchain enables certain improved developer experiences,
|
||||
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.
|
||||
|
||||
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`
|
||||
To set the nightly toolchain as your default, run `rustup default nightly`.
|
||||
|
||||
## Hello, world!
|
||||
|
||||
|
|
@ -64,7 +57,7 @@ fn index() -> &'static str {
|
|||
"Hello, world!"
|
||||
}
|
||||
|
||||
#[rocket::launch]
|
||||
#[launch]
|
||||
fn rocket() -> rocket::Rocket {
|
||||
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`
|
||||
environment variable to `0` or `off` when running a Rocket binary:
|
||||
|
||||
`ROCKET_CLI_COLORS=off cargo run`
|
||||
`ROCKET_CLI_COLORS=off cargo run`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue