Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/joseluisq/rust-linux-darwin-builder

Use the same Docker image to cross-compile Rust x86_64/ARM64 programs for Linux and macOS (osxcross).
https://github.com/joseluisq/rust-linux-darwin-builder

aarch64 amd64 arm64 arm64v8 darwin darwin-builder debian debian-bookworm debian-bullseye debian-linux docker-image linux linux-image macos musl-gcc musl-libc osxcross rust-lang x86-64

Last synced: 24 days ago
JSON representation

Use the same Docker image to cross-compile Rust x86_64/ARM64 programs for Linux and macOS (osxcross).

Host: GitHub
URL: https://github.com/joseluisq/rust-linux-darwin-builder
Owner: joseluisq
License: apache-2.0
Created: 2019-12-30T23:39:15.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2024-03-29T13:51:59.000Z (7 months ago)
Last Synced: 2024-04-22T14:23:34.352Z (7 months ago)
Topics: aarch64, amd64, arm64, arm64v8, darwin, darwin-builder, debian, debian-bookworm, debian-bullseye, debian-linux, docker-image, linux, linux-image, macos, musl-gcc, musl-libc, osxcross, rust-lang, x86-64
Language: Dockerfile
Homepage:
Size: 221 KB
Stars: 104
Watchers: 4
Forks: 15
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE

Awesome Lists containing this project

README

Rust Linux / Darwin Builder

Use the same Docker image to cross-compile Rust programs for Linux (musl libc) and macOS (osxcross)

[![Build Status](https://api.cirrus-ci.com/github/joseluisq/rust-linux-darwin-builder.svg)](https://cirrus-ci.com/github/joseluisq/rust-linux-darwin-builder) [![Docker Image Version (tag latest semver)](https://img.shields.io/docker/v/joseluisq/rust-linux-darwin-builder/1)](https://hub.docker.com/r/joseluisq/rust-linux-darwin-builder/) [![Docker Image Size (tag)](https://img.shields.io/docker/image-size/joseluisq/rust-linux-darwin-builder/1)](https://hub.docker.com/r/joseluisq/rust-linux-darwin-builder/tags) [![Docker Image](https://img.shields.io/docker/pulls/joseluisq/rust-linux-darwin-builder.svg)](https://hub.docker.com/r/joseluisq/rust-linux-darwin-builder/)

## Overview

This is a __Linux Docker image__ based on [ekidd/rust-musl-builder](https://hub.docker.com/r/ekidd/rust-musl-builder) but using the latest __Debian [12-slim](https://hub.docker.com/_/debian/tags?page=1&name=12-slim)__ ([Bookworm](https://www.debian.org/News/2023/20230610)).

It contains essential tools for cross-compile [Rust](https://www.rust-lang.org/) projects such as __Linux__ static binaries via [musl-libc / musl-gcc](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html) (`x86_64-unknown-linux-musl`) and __macOS__ binaries (`x86_64-apple-darwin`) via [osxcross](https://github.com/tpoechtrager/osxcross) just using the same Linux image.

The Docker image is [multi-arch](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/) (`amd64` and `arm64`) so you can use them in native environments.
Also, it is possible to cross-compile `arm64` Linux or Darwin apps from the `x86_64` Docker image variant.

## Usage

### Compiling an application inside a Docker container

By default, the working directory is `/root/src`.

### x86_64 (amd64)

Below are the default toolchains included in the Docker image.

#### x86_64-unknown-linux-musl

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target x86_64-unknown-linux-musl"
```

#### x86_64-unknown-linux-gnu

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target x86_64-unknown-linux-gnu"
```

#### x86_64-apple-darwin

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target x86_64-apple-darwin"
```

### aarch64 (arm64)

#### aarch64-unknown-linux-gnu

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target aarch64-unknown-linux-gnu"
```

#### aarch64-unknown-linux-musl

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target aarch64-unknown-linux-musl"
```

#### aarch64-apple-darwin

```sh
docker run --rm \
--volume "${PWD}/sample":/root/src \
--workdir /root/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
sh -c "cargo build --release --target aarch64-apple-darwin"
```

### Cargo Home advice

It's known that the [`CARGO_HOME`](https://doc.rust-lang.org/cargo/guide/cargo-home.html#cargo-home) points to `$HOME/.cargo` by default (`/root/.cargo` in this case). However, if you want to use a custom Cargo home directory then make sure to copy the Cargo `config` file to the particular directory like `cp "$HOME/.cargo/config" "$CARGO_HOME/"` before to cross-compile your program. Otherwise, you could face a linking error when for example you want to cross-compile to an `x86_64-apple-darwin` target.

### Dockerfile

You can also use the image as a base for your Dockerfile:

```Dockerfile
FROM joseluisq/rust-linux-darwin-builder:1.81.0
```

### OSXCross

You can also use o32-clang(++) and o64-clang(++) as a normal compiler.

__Notes:__

- The current *11.3 SDK* does not support i386 anymore. Use <= 10.13 SDK if you rely on i386 support.
- The current *11.3 SDK* does not support libstdc++ anymore. Use <= 10.13 SDK if you rely on libstdc++ support.

Examples:

```sh
Example usage:

Example 1: CC=o32-clang ./configure --host=i386-apple-darwin22.4
Example 2: CC=i386-apple-darwin22.4-clang ./configure --host=i386-apple-darwin22.4
Example 3: o64-clang -Wall test.c -o test
Example 4: x86_64-apple-darwin22.4-strip -x test

!!! Use aarch64-apple-darwin22.4-* instead of arm64-* when dealing with Automake !!!
!!! CC=aarch64-apple-darwin22.4-clang ./configure --host=aarch64-apple-darwin22.4 !!!
!!! CC="aarch64-apple-darwin22.4-clang -arch arm64e" ./configure --host=aarch64-apple-darwin22.4 !!!
```

### Cross-compilation example

Below is a simple example of using a `Makefile` to cross-compile a Rust app.

Notes:

- A [hello world](./tests/hello-world) app is used.
- A custom directory is used below as a working directory instead of `/root/src`.

Create a Makefile:

```sh
compile:
@docker run --rm -it \
-v $(PWD):/app/src \
-w /app/src \
joseluisq/rust-linux-darwin-builder:1.81.0 \
make cross-compile
.PHONY: compile

cross-compile:
@echo
@echo "1. Cross compiling example..."
@rustc -vV
@echo
@echo "2. Compiling application (linux-musl x86_64)..."
@cargo build --manifest-path=tests/hello-world/Cargo.toml --release --target x86_64-unknown-linux-musl
@du -sh tests/hello-world/target/x86_64-unknown-linux-musl/release/helloworld
@echo
@echo "3. Compiling application (apple-darwin x86_64)..."
@cargo build --manifest-path=tests/hello-world/Cargo.toml --release --target x86_64-apple-darwin
@du -sh tests/hello-world/target/x86_64-apple-darwin/release/helloworld
.PHONY: cross-compile
```

Just run the makefile `compile` target, then you will see two release binaries `x86_64-unknown-linux-musl` and `x86_64-apple-darwin`.

```sh
make compile
# 1. Cross compiling example...
# rustc 1.81.0 (eeb90cda1 2024-09-04)
# binary: rustc
# commit-hash: eeb90cda1969383f56a2637cbd3037bdf598841c
# commit-date: 2024-09-04
# host: x86_64-unknown-linux-gnu
# release: 1.81.0
# LLVM version: 18.1.7

# 2. Compiling application (linux-musl x86_64)...
# Finished release [optimized] target(s) in 0.01s
# 1.2M tests/hello-world/target/x86_64-unknown-linux-musl/release/helloworld

# 3. Compiling application (apple-darwin x86_64)...
# Finished release [optimized] target(s) in 0.01s
# 240K tests/hello-world/target/x86_64-apple-darwin/release/helloworld
```

For more details take a look at [Cross-compiling Rust from Linux to macOS](https://wapl.es/rust/2019/02/17/rust-cross-compile-linux-to-macos.html) by James Waples.

### Macos ARM64

See [joseluisq/rust-linux-darwin-builder#7](https://github.com/joseluisq/rust-linux-darwin-builder/issues/7)

### Building *-sys crates

If some of your crates require C bindings and you run into a compilation or linking error, try to use Clang for C/C++ builds.

For example to cross-compile to Macos:

```sh
CC=o64-clang \
CXX=o64-clang++ \
cargo build --target x86_64-apple-darwin
# Or
cargo build --target aarch64-apple-darwin
```

### OpenSSL release advice

> _Until `v1.42.0` of this project, one old OpenSSL release `v1.0.2` was used._

> _Now, since `v1.43.x` or greater, OpenSSL `v1.1.1` (LTS) is used which is supported until `2023-09-11`.

> View more at https://www.openssl.org/policies/releasestrat.html._

## Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in current work by you, as defined in the Apache-2.0 license, shall be dual licensed as described below, without any additional terms or conditions.

Feel free to send some [Pull request](https://github.com/joseluisq/rust-linux-darwin-builder/pulls) or file an [issue](https://github.com/joseluisq/rust-linux-darwin-builder/issues).

## License

This work is primarily distributed under the terms of both the [MIT license](LICENSE-MIT) and the [Apache License (Version 2.0)](LICENSE-APACHE).