meedamian/simple-qemu repository overview

⁠meedamian/simple-qemu

This project aims to make cross-compilation, and running programs and images built for a different CPU architecture simple.

Currently the only host architecture supported is amd64 (AKA x86_64), while the architectures that can be emulated are:

1. arm (AKA arm32v7)
2. aarch64 (AKA arm64v8, arm64)
3. riscv32
4. riscv64

⁠Image categories

There are 3 distinct categories of images below:

1. An image containing binaries for all architectures⁠. Tagged with a version alone, ex: :v4.2.0, or :latest.
2. An enable-emulation-only image. It contains no qemu binaries, but can be used to enable emulation for use with your own qemu binary. Tagged with the keyword enable, ex: :v4.2.0-enable, or :enable.
3. A single-architecture image. These images contain a single architecture plus a script to enable emulation. Tagged with the name of the architecture, ex: v4.2.0-arm, or aarch64.

⁠Simple tags

For a complete list of available tags see: r/meedamian/simple-qemu/tags⁠

⁠v4.2.0

• v4.2.0, v4.2, v4, latest
• v4.2.0-arm, v4.2-arm, v4-arm, arm (or: arm32v7)
• v4.2.0-aarch64, v4.2-aarch64, v4-aarch64, aarch64 (or: arm64v8 & arm64)
• v4.2.0-riscv32, v4.2-riscv32, v4-riscv32, riscv32
• v4.2.0-riscv64, v4.2-riscv64, v4-riscv64, riscv64
• v4.2.0-enable, v4.2-enable, v4-enable, enable

⁠v4.1.1

• v4.1.1, v4.1
• v4.1.1-arm, v4.1-arm (or: -arm32v7)
• v4.1.1-aarch64, v4.1-aarch64 (or: -arm64v8 & -arm64)
• v4.1.1-riscv32, v4.1-riscv32
• v4.1.1-riscv64, v4.1-riscv64
• v4.1.1-enable, v4.1-enable

⁠v4.1.0

• v4.1.0
• v4.1.0-arm (or: -arm32v7)
• v4.1.0-aarch64 (or: -arm64v8 & -arm64)
• v4.1.0-riscv32
• v4.1.0-riscv64
• v4.1.0-enable

⁠v4.0.1

• v4.0.1, v4.0
• v4.0.1-arm, v4.0-arm (or: -arm32v7)
• v4.0.1-aarch64, v4.0-aarch64 (or: -arm64v8 & -arm64)
• v4.0.1-riscv32, v4.0-riscv32
• v4.0.1-riscv64, v4.0-riscv64
• v4.0.1-enable, v4.0-enable

⁠v4.0.0

• v4.0.0
• v4.0.0-arm (or: -arm32v7)
• v4.0.0-aarch64 (or: -arm64v8 & -arm64)
• v4.0.0-riscv32
• v4.0.0-riscv64
• v4.0.0-enable

⁠v3.1.1

• v3.1.1, v3.1, v3
• v3.1.1-arm, v3.1-arm, v3-arm (or: -arm32v7)
• v3.1.1-aarch64, v3.1-aarch64, v3-aarch64 (or: -arm64v8 & -arm64)
• v3.1.1-riscv32, v3.1-riscv32, v3-riscv32
• v3.1.1-riscv64, v3.1-riscv64, v3-riscv64
• v3.1.1-enable, v3.1-enable, v3-enable

⁠v3.1.0

• v3.1.0
• v3.1.0-arm (or: -arm32v7)
• v3.1.0-aarch64 (or: -arm64v8 & -arm64)
• v3.1.0-riscv32
• v3.1.0-riscv64
• v3.1.0-enable

⁠Usage

The simplest way to run an image built for a different architecture is to run:

# Enable emulation on the host system
docker run --rm --privileged meedamian/simple-qemu -p yes
 
# Verify it worked
docker run --rm arm32v7/alpine uname -m

If you want to emulate build on your amd64 machine, then:

# Enable emulation on the host system
docker run --rm --privileged meedamian/simple-qemu -p yes

And then in your Dockerfile specify exact base architecture, you want to use:

FROM arm32v7/alpine:3.11

# Everything written here will be run on an emulated architecture

It's that simple :).

⁠Performance

Emulation can be nightmarishly slow. Here's⁠ a (not very scientific) comparison. It uses a random project⁠ of mine, and compares it again't baseline (no emulation), and another project I know of (multiarch/qemu-user-static⁠).

⁠Bugs and feedback

If you discover a bug please report it here⁠. Express gratitude here⁠.

Mail me at [email protected]⁠, or on twitter @meeDamian⁠.

⁠License

MIT @ Damian Mee⁠