mirror of https://github.com/rwf2/Rocket.git
109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
## 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 supported _nightly_
|
|
version of Rust.
|
|
|
|
To install such a version, 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:
|
|
|
|
```sh
|
|
rustup default nightly-2017-12-21
|
|
```
|
|
|
|
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:
|
|
|
|
```sh
|
|
rustup override set nightly-2017-12-21
|
|
```
|
|
|
|
### Minimum Nightly
|
|
|
|
Rocket generally requires the _latest_ version of Rust nightly. At present,
|
|
however, a Rocket dependency fails to build on the latest nightlies, temporarily
|
|
grounding Rocket (see [#513] for details). As a result, you'll need to use the
|
|
last known working nightly release while the issue is resolved. The commands
|
|
above already take this into account by installing the `2017-12-21` nightly.
|
|
|
|
Once the external issue has been resolved, you can upgrade to the latest nightly
|
|
with `rustup default nightly` or `rustup override set nightly`. If your Rocket
|
|
application suddenly stops building, it's likely that this issue has been
|
|
resolved. If Rocket fails to compile in the future, you should also ensure
|
|
you're using the latest version of Rust nightly and Rocket by updating your
|
|
toolchain and dependencies with:
|
|
|
|
```sh
|
|
rustup update && cargo update
|
|
```
|
|
|
|
[#513]: https://github.com/SergioBenitez/Rocket/issues/513
|
|
|
|
## Hello, world!
|
|
|
|
Let's write our first Rocket application! Start by creating a new binary-based
|
|
Cargo project and changing into the new directory:
|
|
|
|
```sh
|
|
cargo new hello-rocket --bin
|
|
cd hello-rocket
|
|
```
|
|
|
|
Now, add Rocket and its code generation facilities as dependencies of your
|
|
project by ensuring your `Cargo.toml` contains the following:
|
|
|
|
```
|
|
[dependencies]
|
|
rocket = "0.4.0-dev"
|
|
rocket_codegen = "0.4.0-dev"
|
|
```
|
|
|
|
Modify `src/main.rs` so that it contains the code for the Rocket `Hello, world!`
|
|
program, reproduced below:
|
|
|
|
```rust
|
|
#![feature(plugin, decl_macro)]
|
|
#![plugin(rocket_codegen)]
|
|
|
|
extern crate rocket;
|
|
|
|
#[get("/")]
|
|
fn index() -> &'static str {
|
|
"Hello, world!"
|
|
}
|
|
|
|
fn main() {
|
|
rocket::ignite().mount("/", routes![index]).launch();
|
|
}
|
|
```
|
|
|
|
We won't explain exactly what the program does now; we leave that for the rest
|
|
of the guide. In short, it creates an `index` route, _mounts_ the route at the
|
|
`/` path, and launches the application. Compile and run the program with `cargo
|
|
run`. You should see the following:
|
|
|
|
```sh
|
|
🔧 Configured for development.
|
|
=> address: localhost
|
|
=> port: 8000
|
|
=> log: normal
|
|
=> workers: [core count * 2]
|
|
=> secret key: generated
|
|
=> limits: forms = 32KiB
|
|
=> tls: disabled
|
|
🛰 Mounting '/':
|
|
=> GET /
|
|
🚀 Rocket has launched from http://localhost:8000
|
|
```
|
|
|
|
Visit `http://localhost:8000` to see your first Rocket application in action!
|