1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126This is a Heroku buildpack for Rust with support for [cargo][] and [rustup][]. Features include:
- Caching of builds between deployments.
- Automatic updates to the latest stable Rust by default.
- Optional pinning of Rust to a specific version.
- Support for `export` so that other buildpacks can access the Rust toolchain.
- Support for compiling Rust-based extensions for projects written in other languages.
[fode]: https://github.com/ericfode/heroku-buildpack-rust
[cargo]: http://crates.io/
[rustup]: https://www.rustup.rs/
## Example projects
Here are several example projects:
- [rust-buildpack-example-actix][] uses the popular [Actix][] framework, and runs on stable Rust.
- [rust-buildpack-example-rocket][] uses the innovative [Rocket][] framework, which currently requires nightly Rust.
[rust-buildpack-example-actix]: https://github.com/emk/rust-buildpack-example-actix
[Actix]: https://actix.rs/
[rust-buildpack-example-rocket]: https://github.com/emk/rust-buildpack-example-rocket
[Rocket]: https://rocket.rs/
## Using this buildpack
To deploy an application to Heroku, we recommend installing the [Heroku CLI][].
If you're creating a new Heroku application, `cd` to the directory containing your code, and run:
```sh
heroku create --buildpack emk/rust
```
This will only work if your application has a `Cargo.toml` and uses `git`. If you want to set a particular name for application, see `heroku create --help` first.
To use this as the buildpack for an existing application, run:
```sh
heroku buildpacks:set emk/rust
```
You will also need to create a `Procfile` pointing to the release version of your application, and commit it to `git`:
```Procfile
web: ./target/release/hello
```
...where `hello` is the name of your binary.
To deploy your application, run:
```sh
git push heroku master
```
### Running Diesel migrations during the release phase
This will install the diesel CLI at build time and make it available in your dyno. Migrations will run whenever a new version of your app is released. Add the following line to your `RustConfig`
```sh
RUST_INSTALL_DIESEL=1
```
and this one to your `Procfile`
```Procfile
release: ./target/release/diesel migration run
```
[Heroku CLI]: https://devcenter.heroku.com/articles/heroku-command-line
## Specifying which version of Rust to use
By default, your application will be built using the latest stable Rust. Normally, this is pretty safe: New stable Rust releases have excellent backwards compatibility.
But you may wish to use `nightly` Rust or to lock your Rust version to a known-good configuration for more reproducible builds. To specify a specific version of the toolchain, use a [`rust-toolchain`](https://github.com/rust-lang-nursery/rustup.rs#the-toolchain-file) file in the format rustup uses.
Note: if you previously specified a `VERSION` variable in `RustConfig`, that will continue to work, and will override a `rust-toolchain` file.
## Combining with other buildpacks
If you have a project which combines both Rust and another programming language, you can insert this buildpack before your existing one as follows:
```sh
heroku buildpacks:add --index 1 emk/rust
```
If you have a valid `Cargo.toml` in your project, this is all you need to do. The Rust buildpack will run first, and your existing buildpack will run second.
But if you only need Rust to build a particular Ruby gem, and you have no top-level `Cargo.toml` file, you'll need to let the buildpack know to skip the build stage. You can do this by adding the following line to `RustConfig`:
```sh
RUST_SKIP_BUILD=1
```
## Using the edge version of the buildpack
The `emk/rust` buildpack from the [Heroku Registry](https://devcenter.heroku.com/articles/buildpack-registry) contains the latest stable version of the buildpack. If you'd like to use the latest buildpack code from this Github repository, you can set your buildpack to the Github URL:
```sh-session
$ heroku buildpacks:set https://github.com/emk/heroku-buildpack-rust
```
## Development notes
If you need to tweak this buildpack, the following information may help.
### Testing with Docker
To test changes to the buildpack using the included `docker-compose-test.yml`, run:
```sh
./test_buildpack
```
Then make sure there are no Rust-related *.so files getting linked:
```sh
ldd heroku-rust-cargo-hello/target/release/hello
```
This uses the Docker image `heroku/cedar`, which allows us to test in an official Cedar-like environment.
We also run this test automatically on Travis CI.