Home

Awesome

meedamian/simple-qemu

action_img lasttag_img pulls_img size_img

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. i386 (AKA x86, i686)
  2. arm (AKA arm32v7)
  3. aarch64 (AKA arm64v8, arm64)
  4. riscv32
  5. 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: :v5.1.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: :v5.1.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: v5.1.0-arm, or aarch64.

Simple tags

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

v5.1.0

v5.0.1

v4.2.1

v4.1.1

v4.0.1

v3.1.1

<details> <summary>Older versions here</summary>

v5.0.0

v4.2.0

v4.1.0

v4.0.0

v3.1.0

</details>

Usage

First, enabling emulation needs to be coordinated with host's kernel:

docker run --rm --privileged meedamian/simple-qemu -p yes

Once that's done, two things become possible:

Running

To run image built for a different CPU architecture:

docker run --rm  arm32v7/alpine  uname -m

Alternatively (buildx style):

docker run --rm  --platform=linux/arm/v7  alpine  uname -m

Extending

To build FROM different CPU architecture image:

FROM arm32v7/alpine

# Everything written here will be run on an emulated architecture

Alternatively (buildx style):

FROM --platform=linux/arm/v7 alpine

# Everything written here will be run on an emulated architecture

It's that simple :).

Note: To learn what architectures are available for the given base image you can use docker manifest inspect command, for example:

$ docker manifest inspect alpine | jq -r '.manifests[].platform | .os + "/" + .architecture + "/" + .variant'
linux/amd64
linux/arm/v6
linux/arm/v7
linux/arm64/v8
linux/386
linux/ppc64le
linux/s390x

Performance

Depending on qemu version used, the speed of emulation can vary from hardly bearable all the way to nightmarishly slow.

For daily generated speed comparisons see: https://github.com/lncm/docker-bitcoind/issues/9

Bugs and feedback

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

Mail me at bugs@meedamian.com, or on twitter @meeDamian.

License

MIT @ Damian Mee