> For the complete documentation index, see [llms.txt](https://docs.auterion.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auterion.com/app-development/resources/cross-compilation-faster-builds.md).

# Cross Compilation - Faster Builds

When building an app with auterion-cli, it calls `docker build --platform linux/arm64` under the hood. This makes docker run the build step in an emulated environment using QEMU.

This is convenient, as one can use the normal compilation steps for ones app as you would on the host, without having to worry about cross compilation. However, in larger projects, build times can grow quite long since the entire compilation is done in an emulated environment.

Cross compilation can improve the situation, but is generally fairly complex to set up. We provide tooling to allow for faster cross compilation.

### Multi-stage build

We use dockers multi-stage build process for easier cross compilation

1. **Sysroot stage**: Runs emulated in the target arch (arm64), install all dependencies your app needs. This prepares a sysroot we can then later use to link against
2. **Compile stage**: Runs on your native arch (amd64). Compile your app using the supplied cross compiler. Link against the libraries installed in the first stage.
3. **Run stage**: Runs emulated in the target arch, and on the target. Based off the sysroot stage, copy over the compiled binaries from the build stage

### Dockerfile setup

```docker
# 1. -- Sysroot stage. Runs in arm64 emulation (QEMU) --
# Install library dependencies
FROM auterion/app-base:v2 as sysroot-stage

RUN apt update && apt install -y \
    <DEPENDENCIES>

# 2. -- Cross-compile build stage. Runs native on x86 --
FROM --platform=$BUILDPLATFORM auterion/app-cross-buildenv:v2 as build-stage

# Variable to contain the target arch. Set automatically by docker to either "arm64" or "amd64"
ARG TARGETARCH

# This is the magic part - copy the entire sysroot from the first stage into
# /opt/sysroot. This path is indicated in the Toolchain file as the place
# to look for libraries to link against. This makes sure, we link against the
# right libraries (the arm64 versions)
COPY --from=sysroot-stage / /opt/sysroot

# Copy and compile the app
COPY app /app
WORKDIR /app
# Build your app using the right toolchain file. Selected by $TARGETARCH variable
RUN cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/Toolchain_$TARGETARCH.cmake && \
    cmake --build build

# 3. -- Runtime stage. Runs in arm64 emulation and on target --
FROM sysroot-stage as run-stage

COPY --from=build-stage /app/build /app/build
CMD /app/my_app

```

### app-cross-buildenv contents

This image contains everything from auterion/app-base plus:

* Cross-compilers for arm64 and amd64
  * `aarch64-linux-gnu-*`
  * `x86_64-linux-gnu-*`
* CMake toolchain files for cross-compiling
  * `/Toolchain_amd64.cmake`
  * `/Toolchain_arm64.cmake`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.auterion.com/app-development/resources/cross-compilation-faster-builds.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.