Docs menu

Customizing the build

How to shape an sbt build on Primcloud: pre and post tasks, subproject builds, sbt options, native dependencies, and Debian packages.

On this page

Most Scala apps deploy with no customization at all. Primcloud runs sbt compile stage and that's the whole story. When you need more, it's sbt's own extension points doing the work: task overrides from system.properties or the environment, JVM options through SBT_OPTS, and, for OS-level libraries, Debian packages declared in project.toml.

Build hooks#

Custom pre- and post-build work goes through sbt tasks. Define them in build.sbt and hook them in one of two ways.

Prepend tasks with sbt.pre-tasks or SBT_PRE_TASKS. These run between clean (if enabled) and the default compile stage:

system.properties
sbt.pre-tasks=my-pre-task

Multiple tasks are space-separated (sbt.pre-tasks=task1 task2), which makes the build sbt task1 task2 compile stage. The environment variable SBT_PRE_TASKS does the same.

Or wire the task into compile or stage inside sbt. Standard sbt dependency wiring works, with no Primcloud configuration needed:

build.sbt
lazy val stampBuildInfo = taskKey[Unit]("Write BUILD_SHA to the staging output")

stampBuildInfo := {
  val sha = sys.env.getOrElse("BUILD_SHA", "unknown")
  IO.write(baseDirectory.value / "target" / "universal" / "stage" / "BUILD_SHA", sha)
}

stage := stage.dependsOn(stampBuildInfo).value

Environment variables you set under Settings → Secrets reach sbt tasks through sys.env.

Task and project overrides#

Primcloud exposes a small set of build knobs, readable from system.properties or environment variables. When both set the same key, system.properties wins.

system.properties Environment Effect
sbt.project SBT_PROJECT Build one subproject; the default tasks become {project}/compile and {project}/stage.
sbt.pre-tasks SBT_PRE_TASKS Space-separated tasks prepended to the default.
sbt.tasks SBT_TASKS Space-separated tasks that replace compile stage entirely.
sbt.clean SBT_CLEAN true prepends a clean task.
sbt.available-at-launch SBT_AVAILABLE_AT_LAUNCH true keeps sbt available to your running app (rarely useful).

Build a subproject. For a multi-project build where only one project deploys:

system.properties
sbt.project=web-server

The build becomes sbt web-server/compile web-server/stage.

Replace the default tasks. When your build doesn't fit the compile stage shape:

system.properties
sbt.tasks=assembly

The build becomes sbt assembly, and you're now on the hook for producing whatever your Procfile invokes. Primcloud no longer runs stage.

Clean before every build. Discouraged (it turns off sbt's incremental compilation and lengthens every deploy), but supported:

system.properties
sbt.clean=true

Passing options to sbt's JVM#

SBT_OPTS is passed straight to the JVM that runs sbt. Prefix each JVM flag with -J:

Set under Settings → Secrets:

SBT_OPTS=-J-Xss4m -J-Xmx2g

If your repo has an .sbtopts file at the root, its contents are appended to SBT_OPTS at build time. Use .sbtopts for options that should ride with the code, and the environment variable for values you'd rather not commit.

Native dependencies#

Two shapes of "native" a Scala app can lean on.

JNI bindings shipped inside JARs. Libraries like sqlite-jdbc, netty-tcnative, and jnr-posix bundle platform-specific .so files inside their JARs and load them at runtime. sbt resolves these like any other dependency; the JARs land on the classpath and the natives load with no extra setup.

OS-level shared libraries that a JNI library links against, or that your app shells out to: libpq, libmariadb, libtensorflow, and the like. These come from the operating system, not from sbt. Install them as Debian packages, 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:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  "libpq5",
  "libmariadb-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 with uri, suites, components, arch, and signed_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.