Repository files navigation

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:

#![feature(proc_macro_hygiene, decl_macro)]#[macro_use]externcrate rocket;#[get("/<name>/<age>")]fnhello(name:String,age:u8) ->String{format!("Hello, {} year old named {}!", age, name)}fnmain(){    rocket::ignite().mount("/hello",routes![hello]).launch();}

Visitinglocalhost:8000/hello/John/58, for example, will trigger thehelloroute resulting in the stringHello, 58 year old named John! being sent to thebrowser. If an<age> string was passed in that can't be parsed as au8, theroute won't get called, resulting in a 404 error.

Rocket is extensively documented:

• 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".

The official community support channels are#rocket:mozilla.org on Matrixand the bridged#rocket IRC channel on Freenode atchat.freenode.net. Werecommend joining us onMatrix via Riot. If your prefer IRC, you can join viatheKiwi IRC client or a client of your own.

Rocket requires a nightly version of Rust as it makes heavy use of syntaxextensions. This means that the first two unwieldly lines in the introductoryexample above are required.

All of the Rocket libraries are managed by Cargo. As a result, compiling them issimple.

• Core:cd lib && cargo build
• Codegen:cd codegen && cargo build
• Contrib:cd contrib && cargo build --all-features

Rocket ships with an extensive number of examples in theexamples/ directorywhich can be compiled and run with Cargo. For instance, the following sequenceof commands builds and runs theHello, world! example:

cd examples/hello_worldcargo run

You should seeHello, world! by visitinghttp://localhost:8000.

To test Rocket, simply run./scripts/test.sh from the root of the source tree.This will build and test thecore,codegen, andcontrib libraries as wellas all of the examples. Thetest.sh script accepts no flags or either the--release flag to test in release mode or the--contrib flag to test allcontrib modules individually. This script gets run by CI.

To test a crate individually, runcargo test --all-features in thecorresponding crate directory.

Testing for the core library is done inline in the corresponding module. Forexample, the tests for routing can be found at the bottom of thelib/src/router/mod.rs file.

Code generation tests can be found incodegen/tests. We use thecompiletest library, which wasextracted fromrustc, for testing. See thecompiler testdocumentationfor information on how to write compiler tests.

You can build the Rocket API documentation locally by running./scripts/mk-docs.sh. The resulting documentation is what gets uploaded toapi.rocket.rs.

Contributions are absolutely, positively welcome and encouraged! Contributionscome in many forms. You could:

1. Submit a feature request or bug report as anissue.
2. Ask for improved documentation as anissue.
3. Comment onissues that requirefeedback.
4. Contribute code viapull requests.

We aim to keep Rocket's code quality at the highest level. This means that anycode you contribute must be:

• Commented: Public itemsmust be commented.
• Documented: Exposed itemsmust have rustdoc comments withexamples, if applicable.
• Styled: Your code should berustfmt'd when possible.
• Simple: Your code should accomplish its task as simply andidiomatically 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. Note that unless youexplicitly state otherwise, any contribution intentionally submitted forinclusion in Rocket by you shall be dual licensed under the MIT License andApache License, Version 2.0, without any additional terms or conditions.

Rocket is licensed under either of the following, at your option:

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

The Rocket website source is licensed underseparate terms.