Repository files navigation

This is a Heroku buildpack for Rust with support forcargo andrustup. 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 forexport so that other buildpacks can access the Rust toolchain.
• Support for compiling Rust-based extensions for projects written in other languages.

Here are several example projects:

• rust-buildpack-example-actix uses the popularActix framework, and runs on stable Rust.
• rust-buildpack-example-rocket uses the innovativeRocket framework, which currently requires nightly Rust.

To deploy an application to Heroku, we recommend installing theHeroku CLI.

If you're creating a new Heroku application,cd to the directory containing your code, and run:

heroku create --buildpack emk/rust

This will only work if your application has aCargo.toml and usesgit. If you want to set a particular name for application, seeheroku create --help first.

To use this as the buildpack for an existing application, run:

heroku buildpacks:set emk/rust

You will also need to create aProcfile pointing to the release version of your application, and commit it togit:

web: ./target/release/hello

...wherehello is the name of your binary.

To deploy your application, run:

git push heroku master

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 yourRustConfig

RUST_INSTALL_DIESEL=1

and this one to yourProcfile

release: ./target/release/diesel migration run

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 usenightly 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 arust-toolchain file in the format rustup uses.

Note: if you previously specified aVERSION variable inRustConfig, that will continue to work, and will override arust-toolchain file.

If you have a project which combines both Rust and another programming language, you can insert this buildpack before your existing one as follows:

heroku buildpacks:add --index 1 emk/rust

If you have a validCargo.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-levelCargo.toml file, you'll need to let the buildpack know to skip the build stage. You can do this by adding the following line toRustConfig:

RUST_SKIP_BUILD=1

If you want to change the cargo build command, you can set theRUST_CARGO_BUILD_FLAGS variable inside theRustConfig file.

RUST_CARGO_BUILD_FLAGS="--release -p some_package --bin some_exe --bin some_bin_2"

The default value ofRUST_CARGO_BUILD_FLAGS is--release.If the variable is not set inRustConfig, the default value will be used to build the project.

Theemk/rust buildpack from theHeroku 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:

heroku buildpacks:set https://github.com/emk/heroku-buildpack-rust

If you need to tweak this buildpack, the following information may help.

To test changes to the buildpack using the includeddocker-compose-test.yml, run:

./test_buildpack

Then make sure there are no Rust-related *.so files getting linked:

ldd heroku-rust-cargo-hello/target/release/hello

This uses the Docker imageheroku/cedar, which allows us to test in an official Cedar-like environment.

We also run this test automatically on Travis CI.