src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabihf.md

   1 # armv7-unknown-linux-uclibceabihf
   2
   3 **Tier: 3**
   4
   5 This tier supports the ARMv7 processor running a Linux kernel and uClibc-ng standard library.  It provides full support for rust and the rust standard library.
   6
   7 ## Designated Developers
   8
   9 * [@skrap](https://github.com/skrap)
  10
  11 ## Requirements
  12
  13 This target is cross compiled, and requires a cross toolchain.  You can find suitable pre-built toolchains at [bootlin](https://toolchains.bootlin.com/) or build one yourself via [buildroot](https://buildroot.org).
  14
  15 ## Building
  16
  17 ### Get a C toolchain
  18
  19 Compiling rust for this target has been tested on `x86_64` linux hosts.  Other host types have not been tested, but may work, if you can find a suitable cross compilation toolchain for them.
  20
  21 If you don't already have a suitable toolchain, download one [here](https://toolchains.bootlin.com/downloads/releases/toolchains/armv7-eabihf/tarballs/armv7-eabihf--uclibc--bleeding-edge-2021.11-1.tar.bz2), and unpack it into a directory.
  22
  23 ### Configure rust
  24
  25 The target can be built by enabling it for a `rustc` build, by placing the following in `config.toml`:
  26
  27 ```toml
  28 [build]
  29 target = ["armv7-unknown-linux-uclibceabihf"]
  30 stage = 2
  31
  32 [target.armv7-unknown-linux-uclibceabihf]
  33 # ADJUST THIS PATH TO POINT AT YOUR TOOLCHAIN
  34 cc = "/TOOLCHAIN_PATH/bin/arm-buildroot-linux-uclibcgnueabihf-gcc"
  35 ```
  36
  37 ### Build
  38
  39 ```sh
  40 # in rust dir
  41 ./x.py build --stage 2
  42 ```
  43
  44 ## Building and Running Rust Programs
  45
  46 To test cross-compiled binaries on a `x86_64` system, you can use the `qemu-arm` [userspace emulation](https://qemu-project.gitlab.io/qemu/user/main.html) program.  This avoids having a full emulated ARM system by doing dynamic binary translation and dynamic system call translation.  It lets you run ARM programs directly on your `x86_64` kernel.  It's very convenient!
  47
  48 To use:
  49
  50 * Install `qemu-arm` according to your distro.
  51 * Link your built toolchain via:
  52   * `rustup toolchain link stage2 ${RUST}/build/x86_64-unknown-linux-gnu/stage2`
  53 * Create a test program
  54
  55 ```sh
  56 cargo new hello_world
  57 cd hello_world
  58 ```
  59
  60 * Build and run
  61
  62 ```sh
  63 CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABIHF_RUNNER="qemu-arm -L ${TOOLCHAIN}/arm-buildroot-linux-uclibcgnueabihf/sysroot/" \
  64 CARGO_TARGET_ARMV7_UNKNOWN_LINUX_UCLIBCEABIHF_LINKER=${TOOLCHAIN}/bin/arm-buildroot-linux-uclibcgnueabihf-gcc \
  65 cargo +stage2 run --target armv7-unknown-linux-uclibceabihf
  66 ```