Docs menu
Customizing the build
How to shape the Rust build on Primcloud: which binaries ship, release profile settings, Cargo configuration, native dependencies, and Debian packages via project.toml.
On this page
Most Rust apps deploy on Primcloud with no custom build steps. The build compiles every binary in your package or workspace in release mode and ships the results. When you need more, Cargo's own configuration covers the common cases: which binaries get built, how the release profile is tuned, how native code is compiled, and how OS-level libraries are installed.
There are no pre- or post-build hook scripts for Rust. Anything that needs to run during the build has to fit into what cargo build does: a build.rs script, a Cargo profile setting, or the frontend build that runs ahead of Cargo when the repo has a package.json.
Selecting binaries to build#
By default, every binary target of every workspace member is compiled and shipped. The build command is fixed, so selection happens in your manifests:
Gate a binary behind a feature. Cargo skips a binary whose required-features aren't enabled, and the build passes no feature flags, so only default features are on:
[features]
dev-tools = []
[[bin]]
name = "seed"
required-features = ["dev-tools"]
seed isn't built or shipped, and it gets no process. The build log lists it as skipped. To ship a feature-gated binary, add its feature to default.
Choose which binaries run. Building a binary doesn't mean running it. Without a Procfile, every binary becomes a formation, but only web starts running; the rest start with Instances at 0. To name the processes yourself, ship a Procfile:
web: api
worker: worker
Release profile#
The build always runs with --release. Tune that profile in the root Cargo.toml the way you would locally:
[profile.release]
lto = "thin"
codegen-units = 1
strip = true
Cargo also reads profile settings from the environment, so you can change them per environment without a commit. Set them under Settings → Secrets:
CARGO_PROFILE_RELEASE_DEBUG=true: keep debug info in the deployed binary.RUSTFLAGS: extra flags passed to everyrustcinvocation.
A .cargo/config.toml in the repo is honored too, including build.target. The build installs binaries from wherever Cargo reports writing them.
Build scripts#
build.rs scripts run as part of cargo build, exactly as they do locally. That's the place for code generation, compiling bundled C sources, or embedding build metadata.
Native dependencies#
Two shapes of "native" your Rust app can lean on:
C and C++ compiled from source. Crates that build bundled native code (through the cc or cmake crates, say) need a compiler at build time. gcc, g++, make, and cmake are available during the build, so these compile as they would on a Linux workstation.
OS-level shared libraries. Crates that link against a system library need its headers at build time and the shared object at runtime. If a library isn't already installed, add it through project.toml, covered below.
Debian packages#
When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:
[_]
schema-version = "0.2"
[com.heroku.buildpacks.deb-packages]
install = [
"libgeos-dev",
"libpq-dev",
]
Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.
Advanced options (rarely needed):
- Skip a package's dependencies:
{ name = "some-package", skip_dependencies = true } - Force a reinstall:
{ name = "some-package", force = true } - Install from a URL:
download = ["https://example.com/package-1.2.3.deb"] - Add a package repository: a
[[com.heroku.buildpacks.deb-packages.sources]]table withuri,suites,components,arch, andsigned_by(the repository's key as an ASCII-armored PGP block).
Note
The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.