mirror of https://github.com/rwf2/Rocket.git
Revamp README: add documentation, testing, and contributing sections.
This commit is contained in:
parent
85c06fde04
commit
4c96f6c71f
108
README.md
108
README.md
|
@ -26,70 +26,86 @@ 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
|
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.
|
route won't get called, resulting in a 404 error.
|
||||||
|
|
||||||
## Overview
|
## Documentation
|
||||||
|
|
||||||
Rocket employs code generation to remove the need for boilerplate involved with
|
Rocket is extensively documented:
|
||||||
parsing requests and request parameters, prevent invalid and/or incorrect
|
|
||||||
requests from invoking a user's request handler, and allow the user to define
|
|
||||||
what is valid and/or correct.
|
|
||||||
|
|
||||||
Rocket uses type _guards_, or _constraints_, on request handlers to
|
* [Quickstart](guide/quickstart): How to get started as quickly as possible.
|
||||||
accomplishing it's safety and correctness goals. In Rocket, handlers are _only_
|
* [Getting Started](guide/getting_started): How to start your first project.
|
||||||
invoked if all types that appear in the request handler's argument list can be
|
* [Overview](overview): A brief introduction.
|
||||||
derived from the incoming request.
|
* [Guide](guide): A detailed guide and reference to every component.
|
||||||
|
* [API Documentation](api): The "rustdocs" (API documentation).
|
||||||
In their simplest incarnation, guards can be types expected of parameters in a
|
|
||||||
matched path. This is illustrated in the previous example where the `hello`
|
|
||||||
request handler is only be invoked if the dynamic path parameter `<age>` parses
|
|
||||||
as a `u8`. Guards can also be derived directly from a request. For instance, you
|
|
||||||
can define an `AdminUser` type that can be derived only if the proper cookies
|
|
||||||
were sent along with the request. Then, by simply including the type in a
|
|
||||||
handler's argument list as follows:
|
|
||||||
|
|
||||||
#[get("/admin/post/<id>")]
|
|
||||||
fn admin(user: AdminUser, id: isize) -> { .. }
|
|
||||||
|
|
||||||
you can be assured that the handler will be invoked _only_ if an administrative
|
|
||||||
user is logged in. Any number of such guards can be included. For example, to
|
|
||||||
retrieve the request's cookies along with the admin user, simply include the
|
|
||||||
`&Cookies` type in the argument list:
|
|
||||||
|
|
||||||
#[get("/admin/post/<id>")]
|
|
||||||
fn admin(user: AdminUser, cookies: &Cookies, id: isize) -> { .. }
|
|
||||||
|
|
||||||
Full documentation about built-in request guards is coming soon.
|
|
||||||
|
|
||||||
## Building
|
## Building
|
||||||
|
|
||||||
### Nightly
|
### Nightly
|
||||||
|
|
||||||
Rocket requires a nightly version of Rust as it makes heavy use of syntax
|
Rocket requires a nightly version of Rust as it makes heavy use of syntax
|
||||||
extensions. This also means that the first two unwieldly lines in the Rust file
|
extensions. This means that the first two unwieldly lines in the introductory
|
||||||
above are required.
|
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`
|
||||||
|
|
||||||
### Examples
|
### Examples
|
||||||
|
|
||||||
Try running the examples in the `examples/` folder. For instance, the following
|
Rocket ships with an extensive number of examples in the `examples/` directory
|
||||||
sequence of commands builds and runs the `Hello, world!` example:
|
which can be compiled and run with Cargo. For instance, the following sequence
|
||||||
|
of commands builds and runs the `Hello, world!` example:
|
||||||
|
|
||||||
```
|
```
|
||||||
cd examples/hello_world
|
cd examples/hello_world
|
||||||
cargo run
|
cargo run
|
||||||
```
|
```
|
||||||
|
|
||||||
Then visit `localhost:8000`. You should see `Hello, world!`.
|
You should see `Hello, world!` by visiting `http://localhost:8000`.
|
||||||
|
|
||||||
### OS X
|
## Testing
|
||||||
|
|
||||||
Apple has stopped shipping `openssl` with OS X.11. As such, if your build fails
|
To test Rocket, simply run `./scripts/test.sh` from the root of the source tree.
|
||||||
to compile with some `openssl` related errors, you'll need to install `openssl`,
|
This will build and test the `core`, `codegen`, and `contrib` libraries as well
|
||||||
`cargo clean`, and then `cargo build` again. Here are some lightweight
|
as all of the examples. This is the script that gets run by Travis CI.
|
||||||
instructions:
|
|
||||||
|
|
||||||
```
|
### Core
|
||||||
brew install openssl
|
|
||||||
brew link --force openssl
|
|
||||||
export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include
|
|
||||||
export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib
|
|
||||||
```
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
### Codegen
|
||||||
|
|
||||||
|
Code generation tests can be found in `codegen/tests`. We use the
|
||||||
|
[compiletest](https://crates.io/crates/compiletest_rs) library, which was
|
||||||
|
extracted from `rustc`, for testing. See the [compiler test
|
||||||
|
documentation](https://github.com/rust-lang/rust/blob/master/COMPILER_TESTS.md)
|
||||||
|
for information on how to write compiler tests.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Contributions are absolutely, positively welcome and encouraged! Contributions
|
||||||
|
come in many forms. You could:
|
||||||
|
|
||||||
|
1. Submit a feature request or bug report as an [issue](https://github.com/SergioBenitez/Rocket/issues).
|
||||||
|
2. Comment on [issues that require
|
||||||
|
feedback](https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22).
|
||||||
|
3. Contribute code via [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:** 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.
|
||||||
|
* **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.
|
||||||
|
|
||||||
|
All pull requests are code reviewed and tested by the CI.
|
||||||
|
|
Loading…
Reference in New Issue