Recipes

This contains recipes for common logic use cases.

Table of Contents

• OpenSSL
• sccache

OpenSSL

You can either use the vendored or system packages for the openssl crate. In order to use the system packages, see. A sample Dockerfile for aarch64 is:

FROM ghcr.io/cross-rs/aarch64-unknown-linux-gnu:edge
RUN dpkg --add-architecture arm64
RUN apt-get update && apt-get install --assume-yes libssl-dev:arm64

Build this image and use it, as is described extensively in Custom Images.

For non-GNU targets, use the vendored option by adding the following to your dependencies in Cargo.toml:

openssl = { version = "0.10", features = ["vendored"] }

sccache

sccache support can be done either by sccache from source or using a pre-built binary.

1. Create a script to install sccache in the image, either from a pre-built binary or from source.
2. Extend a Dockerfile to install sccache in the image.
3. Passthrough the appropriate environment variables in Cross.toml when using sccache.

Install Script

First, we need a script to copy into our image as sccache.sh (make sure the script is executable).

Pre-Built Binary

#!/bin/bash

set -x
set -euo pipefail

# shellcheck disable=SC1091
. lib.sh

main() {
    local triple
    local tag
    local td
    local url="https://github.com/mozilla/sccache"
    triple="${1}"

    install_packages unzip tar

    # Download our package, then install our binary.
    td="$(mktemp -d)"
    pushd "${td}"
    tag=$(git ls-remote --tags --refs --exit-code \
        "${url}" \
        | cut -d/ -f3 \
        | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
        | sort --version-sort \
        | tail -n1)
    curl -LSfs "${url}/releases/download/${tag}/sccache-${tag}-${triple}.tar.gz" \
        -o sccache.tar.gz
    tar -xvf sccache.tar.gz
    rm sccache.tar.gz
    cp "sccache-${tag}-${triple}/sccache" "/usr/bin/sccache"
    chmod +x "/usr/bin/sccache"

    # clean up our install
    purge_packages
    popd
    rm -rf "${td}"
    rm "${0}"
}

main "${@}"

From Source

When installing from source, we can toggle various features, however it is highly recommended to use the vendored OpenSSL.

#!/bin/bash

set -x
set -euo pipefail

# shellcheck disable=SC1091
. lib.sh

main() {
    local triple
    local tag
    local td
    local url="https://github.com/mozilla/sccache"
    triple="${1}"

    install_packages ca-certificates curl unzip

    # install rust and cargo to build sccache
    export RUSTUP_HOME=/tmp/rustup
    export CARGO_HOME=/tmp/cargo
    curl --retry 3 -sSfL https://sh.rustup.rs -o rustup-init.sh
    sh rustup-init.sh -y --no-modify-path
    rm rustup-init.sh
    export PATH="${CARGO_HOME}/bin:${PATH}"
    rustup target add "${triple}"

    # download the source code from the latest sccache release
    td="$(mktemp -d)"
    pushd "${td}"
    tag=$(git ls-remote --tags --refs --exit-code \
        "${url}" \
        | cut -d/ -f3 \
        | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
        | sort --version-sort \
        | tail -n1)
    curl -LSfs "${url}/archive/refs/tags/${tag}.zip" \
        -o sccache.zip
    unzip sccache.zip
    mv "sccache-${tag//v/}" sccache
    rm sccache.zip

    # build from source for the desired architecture
    # you can also use additional features here
    cd sccache
    cargo build --release --target "${triple}" \
        --features=all,"openssl/vendored"
    cp "target/${triple}/release/sccache" "/usr/bin/sccache"

    # clean up our install
    rm -r "${RUSTUP_HOME}" "${CARGO_HOME}"
    purge_packages
    popd
    rm -rf "${td}"
    rm "${0}"
}

main "${@}"

Dockerfile

Next, extend our Dockerfile and build our image, saved as Dockerfile.${target}, where ${target} is replaced by our desired target (such as x86_64-unknown-linux-musl).

FROM ghcr.io/cross-rs/${target}:main
ARG DEBIAN_FRONTEND=noninteractive

COPY sccache.sh /
RUN /sccache.sh x86_64-unknown-linux-musl

ENV RUSTC_WRAPPER="/usr/bin/sccache"

Build our Docker image with:

docker build --tag ${target}:sccache \
    --file Dockerfile.${target} .

Cross.toml

Now, we need to passthrough our environment variables and ensure they're exported when running cross. In Cross.toml, define:

[target.${target}]
image = "${target}:sccache"

[build.env]
passthrough = [
    "SCCACHE_ERROR_LOG",
    "SCCACHE_LOG",
    "SCCACHE_AZURE_CONNECTION_STRING",
    "SCCACHE_AZURE_BLOB_CONTAINER",
    "SCCACHE_DIR",
]

Building with sccache

Finally, we can run cross with our sccache environment variables defined using cross:

SCCACHE_LOG=trace SCCACHE_DIR=/path/to/sccache/cache \
    cross build --target "${target}" --verbose