Rocket

A web framework for Rust. https://rocket.rs (mirror)
git clone git://git.thc420.xyz/Rocket
Log | Files | Refs | README

README.md (6715B)


      1 # Rocket
      2 
      3 [![Build Status](https://dev.azure.com/SergioBenitez/Rocket/_apis/build/status/SergioBenitez.Rocket?branchName=master)](https://dev.azure.com/SergioBenitez/Rocket/_build/latest?definitionId=3&branchName=master)
      4 [![Rocket Homepage](https://img.shields.io/badge/web-rocket.rs-red.svg?style=flat&label=https&colorB=d33847)](https://rocket.rs)
      5 [![Current Crates.io Version](https://img.shields.io/crates/v/rocket.svg)](https://crates.io/crates/rocket)
      6 [![Chat on Matrix](https://img.shields.io/badge/style-matrix-blue.svg?style=flat&label=chat)](https://riot.im/app/#/room/#mozilla_#rocket:matrix.org)
      7 [![IRC: #rocket on irc.mozilla.org](https://img.shields.io/badge/style-%23rocket-blue.svg?style=flat&label=mozilla)](https://kiwiirc.com/client/irc.mozilla.org/#rocket)
      8 
      9 Rocket is web framework for Rust (nightly) with a focus on ease-of-use,
     10 expressibility, and speed. Here's an example of a complete Rocket application:
     11 
     12 ```rust
     13 #![feature(proc_macro_hygiene, decl_macro)]
     14 
     15 #[macro_use] extern crate rocket;
     16 
     17 #[get("/<name>/<age>")]
     18 fn hello(name: String, age: u8) -> String {
     19     format!("Hello, {} year old named {}!", age, name)
     20 }
     21 
     22 fn main() {
     23     rocket::ignite().mount("/hello", routes![hello]).launch();
     24 }
     25 ```
     26 
     27 Visiting `localhost:8000/hello/John/58`, for example, will trigger the `hello`
     28 route resulting in the string `Hello, 58 year old named John!` being sent to the
     29 browser. If an `<age>` string was passed in that can't be parsed as a `u8`, the
     30 route won't get called, resulting in a 404 error.
     31 
     32 ## Documentation
     33 
     34 Rocket is extensively documented:
     35 
     36   * [Overview]: A brief look at what makes Rocket special.
     37   * [Quickstart]: How to get started as quickly as possible.
     38   * [Getting Started]: How to start your first Rocket project.
     39   * [Guide]: A detailed guide and reference to Rocket.
     40   * [API Documentation]: The "rustdocs".
     41 
     42 [Quickstart]: https://rocket.rs/guide/quickstart
     43 [Getting Started]: https://rocket.rs/guide/getting-started
     44 [Overview]: https://rocket.rs/overview/
     45 [Guide]: https://rocket.rs/guide/
     46 [API Documentation]: https://api.rocket.rs/rocket/
     47 
     48 The official community support channels are the `#rocket` IRC channel on the
     49 [Mozilla IRC Server] at `irc.mozilla.org` and the bridged [Rocket room on
     50 Matrix]. If you're not familiar with IRC, we recommend chatting through [Matrix
     51 via Riot] or via the [Kiwi web IRC client]. You can learn more about IRC via
     52 Mozilla's [Getting Started with IRC] guide.
     53 
     54 [Mozilla IRC Server]: https://wiki.mozilla.org/IRC
     55 [Rocket room on Matrix]: https://riot.im/app/#/room/#mozilla_#rocket:matrix.org
     56 [Matrix via Riot]: https://riot.im/app/#/room/#mozilla_#rocket:matrix.org
     57 [Kiwi web IRC client]: https://kiwiirc.com/client/irc.mozilla.org/#rocket
     58 [Getting Started with IRC]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Getting_Started_with_IRC
     59 
     60 ## Building
     61 
     62 ### Nightly
     63 
     64 Rocket requires a nightly version of Rust as it makes heavy use of syntax
     65 extensions. This means that the first two unwieldly lines in the introductory
     66 example above are required.
     67 
     68 ### Core, Codegen, and Contrib
     69 
     70 All of the Rocket libraries are managed by Cargo. As a result, compiling them is
     71 simple.
     72 
     73   * Core: `cd lib && cargo build`
     74   * Codegen: `cd codegen && cargo build`
     75   * Contrib: `cd contrib && cargo build --all-features`
     76 
     77 ### Examples
     78 
     79 Rocket ships with an extensive number of examples in the `examples/` directory
     80 which can be compiled and run with Cargo. For instance, the following sequence
     81 of commands builds and runs the `Hello, world!` example:
     82 
     83 ```
     84 cd examples/hello_world
     85 cargo run
     86 ```
     87 
     88 You should see `Hello, world!` by visiting `http://localhost:8000`.
     89 
     90 ## Testing
     91 
     92 To test Rocket, simply run `./scripts/test.sh` from the root of the source tree.
     93 This will build and test the `core`, `codegen`, and `contrib` libraries as well
     94 as all of the examples. The `test.sh` script accepts no flags or either the
     95 `--release` flag to test in release mode or the `--contrib` flag to test all
     96 `contrib` modules individually. This script gets run by CI.
     97 
     98 To test a crate individually, run `cargo test --all-features` in the
     99 corresponding crate directory.
    100 
    101 ### Core
    102 
    103 Testing for the core library is done inline in the corresponding module. For
    104 example, the tests for routing can be found at the bottom of the
    105 `lib/src/router/mod.rs` file.
    106 
    107 ### Codegen
    108 
    109 Code generation tests can be found in `codegen/tests`. We use the [compiletest]
    110 library, which was extracted from `rustc`, for testing. See the [compiler test
    111 documentation] for information on how to write compiler tests.
    112 
    113 [compiletest]: https://crates.io/crates/compiletest_rs
    114 [compiler test documentation]: https://github.com/rust-lang/rust/blob/master/src/test/COMPILER_TESTS.md
    115 
    116 ## Documentation
    117 
    118 You can build the Rocket API documentation locally by running
    119 `./scripts/mk-docs.sh`. The resulting documentation is what gets uploaded to
    120 [api.rocket.rs](https://api.rocket.rs/).
    121 
    122 ## Contributing
    123 
    124 Contributions are absolutely, positively welcome and encouraged! Contributions
    125 come in many forms. You could:
    126 
    127   1. Submit a feature request or bug report as an [issue].
    128   2. Ask for improved documentation as an [issue].
    129   3. Comment on [issues that require feedback].
    130   4. Contribute code via [pull requests].
    131 
    132 [issue]: https://github.com/SergioBenitez/Rocket/issues
    133 [issues that require feedback]: https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22
    134 [pull requests]: https://github.com/SergioBenitez/Rocket/pulls
    135 
    136 We aim to keep Rocket's code quality at the highest level. This means that any
    137 code you contribute must be:
    138 
    139   * **Commented:** Public items _must_ be commented.
    140   * **Documented:** Exposed items _must_ have rustdoc comments with
    141     examples, if applicable.
    142   * **Styled:** Your code should be `rustfmt`'d when possible.
    143   * **Simple:** Your code should accomplish its task as simply and
    144      idiomatically as possible.
    145   * **Tested:** You must add (and pass) convincing tests for any functionality you add.
    146   * **Focused:** Your code should do what it's supposed to do and nothing more.
    147 
    148 All pull requests are code reviewed and tested by the CI. Note that unless you
    149 explicitly state otherwise, any contribution intentionally submitted for
    150 inclusion in Rocket by you shall be dual licensed under the MIT License and
    151 Apache License, Version 2.0, without any additional terms or conditions.
    152 
    153 ## License
    154 
    155 Rocket is licensed under either of the following, at your option:
    156 
    157  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
    158  * MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
    159 
    160 The Rocket website source is licensed under [separate terms](site#license).