cargo-chef

Table of Contents

1. How to install
2. How to use
3. Benefits vs Limitations
4. License

How To Install

You can install

cargo-chef

cargo install cargo-chef --locked

How to use

:warning: cargo-chef is not meant to be run locally
Its primary use-case is to speed up container builds by running BEFORE the actual source code is copied over. Don't run it on existing codebases to avoid having files being overwritten.

cargo-chef

prepare

cook

cargo chef --help

cargo-chef

USAGE:
    cargo chef 
SUBCOMMANDS:
    cook       Re-hydrate the minimum project skeleton identified by cargo chef prepare and
               build it to cache dependencies
    prepare    Analyze the current project to determine the minimum subset of files (Cargo.lock
               and Cargo.toml manifests) required to build it and cache dependencies

prepare

cargo chef prepare --recipe-path recipe.json

Nothing too mysterious going on here, you can examine the

recipe.json

Cargo.toml

Cargo.lock

Cargo.toml

src/main.rs

src/lib.rs

The

recipe.json

requirements.txt

cargo chef cook

cargo chef cook --recipe-path recipe.json

If you want to build in

--release

cargo chef cook --release --recipe-path recipe.json

You can leverage it in a Dockerfile:

FROM lukemathwalker/cargo-chef:latest-rust-1.53.0 AS chef
WORKDIR app

FROM chef AS planner
COPY . .
RUN cargo chef prepare --recipe-path recipe.json
FROM chef AS builder 
COPY --from=planner /app/recipe.json recipe.json
Build dependencies - this is the caching Docker layer!
RUN cargo chef cook --release --recipe-path recipe.json
Build application
COPY . .
RUN cargo build --release --bin app
We do not need the Rust toolchain to run the binary!
FROM debian:buster-slim AS runtime
WORKDIR app
COPY --from=builder /app/target/release/app /usr/local/bin
ENTRYPOINT ["/usr/local/bin/app"]

We are using three stages: the first computes the recipe file, the second caches our dependencies and builds the binary, the third is our runtime environment.
As long as your dependencies do not change the

recipe.json

cargo cargo chef cook --release --recipe-path recipe.json

Pre-built images

We offer

lukemathwalker/cargo-chef

cargo-chef

The tagging scheme is

-rust-

0.1.22-rust-1.53.0

cargo-chef

rust

latest-rust-1.53.0

cargo-chef

0.1.22-rust-latest

cargo-chef

:warning: You must use the same Rust version in all stages
If you use a different Rust version in one of the stages caching will not work as expected.

Without the pre-built image

If you do not want to use the

lukemathwalker/cargo-chef

FROM rust:1.53.0 AS chef 
# We only pay the installation cost once, 
# it will be cached from the second build onwards
RUN cargo install cargo-chef 
WORKDIR app

FROM chef AS planner
COPY . .
RUN cargo chef prepare  --recipe-path recipe.json
FROM chef AS builder
COPY --from=planner /app/recipe.json recipe.json
Build dependencies - this is the caching Docker layer!
RUN cargo chef cook --release --recipe-path recipe.json
Build application
COPY . .
RUN cargo build --release --bin app
We do not need the Rust toolchain to run the binary!
FROM debian:buster-slim AS runtime
WORKDIR app
COPY --from=builder /app/target/release/app /usr/local/bin
ENTRYPOINT ["/usr/local/bin/app"]

Running the binary in Alpine

If you want to run your application using the

alpine

x86_64-unknown-linux-musl

rust-musl-builder

cargo-chef

x86_64-unknown-linux-musl

A sample Dockerfile looks like this:

# Using the `rust-musl-builder` as base image, instead of 
# the official Rust toolchain
FROM ekidd/rust-musl-builder:1.51.0 AS chef
USER root
RUN cargo install cargo-chef
WORKDIR /app

FROM chef AS planner
COPY . .
RUN cargo chef prepare --recipe-path recipe.json
FROM chef AS builder
COPY --from=planner /app/recipe.json recipe.json
Notice that we are specifying the --target flag!
RUN cargo chef cook --release --target x86_64-unknown-linux-musl --recipe-path recipe.json
COPY . .
RUN cargo build --release --target x86_64-unknown-linux-musl --bin app
FROM alpine AS runtime
RUN addgroup -S myuser && adduser -S myuser -G myuser
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/app /usr/local/bin/
USER myuser
CMD ["/usr/local/bin/app"]

Benefits vs Limitations

cargo-chef

cargo build

Benefits of

cargo-chef

:

A common alternative is to load a minimal

main.rs

Cargo.toml

Cargo.lock

cargo-chef

• automatically pick up all crates in a workspace (and new ones as they are added)
• keep working when files or crates are moved around, which would instead require manual edits to the

  Dockerfile

  using the "manual" approach
• generate fewer intermediate Docker layers (for workspaces)

Limitations and caveats:

• cargo cook

  and

  cargo build

  must be executed from the same working directory. If you examine the

  *.d

  files under

  target/debug/deps

  for one of your projects using

  cat

  you will notice that they contain absolute paths referring to the project

  target

  directory. If moved around,

  cargo

  will not leverage them as cached dependencies;

• cargo build

  will build local dependencies (outside of the current project) from scratch, even if they are unchanged, due to the reliance of its fingerprinting logic on timestamps (see this long issue on

  cargo

  's repository);

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.