Repository files navigation

This guide will show how Rust programs can be cross compiled for the RaspberryPi using Cargo. These instructions may or may not work for your particularsystem, so you may have to adjust the procedure to fit your configuration.

There is also a docker container version of the Rust cross-compilerfor the Raspberry:https://github.com/Ragnaroek/rust-on-raspberry-docker.If you are using docker this may be a easier solution for cross-compilingyour project.

These instructions are based onthe rusty-pi guide,but with some additions and adaptations for the current build systems.

The first step is to download the Raspberry Pi toolchain. It's a collection ofbinaries and libraries for cross compiling. Begin by installinggit if it'snot already installed:

sudo apt-get install git

(replaceapt-get install with the install command for your favorite packagemanager)

and procede by cloning the toolchain repository:

git clone https://github.com/raspberrypi/tools.git ~/pi-tools

The next step is to compile the Rust compiler and standard libraries. Thestandard libraries are particularly important, since they have to be compiledfor the ARM platform to make them usable in your program. See Appendix Afor information on how to add more libraries.

start by cloning the Rust repository andcd into it:

git clone http://github.com/rust-lang/rust.gitcd rust

You may want to check out the same revision as your current copy ofrustc tokeep everything in sync. You can find the revision hash by runningrustcwith the-V flag:

$ rustc -Vrustc 1.0.0-nightly (30e1f9a1c 2015-03-14) (built 2015-03-15)                     ^-------^ This is what you are looking for

Copy the hash and use it to reset the repository to the same revision:

git reset --hard 30e1f9a1c

Alright, finally time to build it. Begin by adding the binary directory fromthe Raspberry Pi toolchain to your path. Use the following command to use the64 bit tools:

export PATH=~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin:$PATH

or use this command for the 32 bit tools:

export PATH=~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin:$PATH

Configure the compiler to build everything for ARM Linux and set the installdestination to$HOME/pi-rust:

./configure --target=arm-unknown-linux-gnueabihf --prefix=$HOME/pi-rust

And build+install!

make -j4 && make install

(Change the 4 to your preferred number of parallel build processes)

This is will take a while, so go and grab some coffee or take a walk whilewaiting.

Is it done? Great! Now, move on to the next part.

We are almost ready to actually build things. You may actually be able to userustc directly, but we want more, right? We want the convenience of Cargo!But Cargo doesn't come without demands. It has to know what we are using tolink our program, so let's tell it. Cargo will be looking forconfigurationfiles where we can specify what to use whenbuilding ARM programs.

You may already have a directory in your$HOME called.cargo. Create one,if you don't have it. Now, create a file calledconfig, or edit an existingone, and add the following lines to associate the target triplearm-unknown-linux-gnueabihf with our cross compilers:

[target.arm-unknown-linux-gnueabihf]ar = "arm-linux-gnueabihf-gcc-ar"linker = "gcc-sysroot"

Wait a minute! What isgcc-sysroot? Well, that is a semi ugly hack and weare going to use it.

The thing is that Cargo has some problems when it comes to cross compilingwhile depending on share libraries. These libraries are placed somewhere inthesysroot andgcc is usingld to link them. The problem is that thedefaultsysroot is where the host libraries are located and those are notbuilt for ARM. There is currently no good way to tell Cargo to tellrustc totellgcc to tellld to look somewhere else, so we have to do it for them.

The Raspberry Pi toolchain contains a directory with various systemdirectories filled with common libraries (if you want to add more libraries,see Appendix A). This is where we wantld to lookfor things, so we are going to use a simple script to tellgcc to tell itwhere this directory can be found. Create a file in the binary directory youadded to your$PATH before(~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/binif you used the 64 bit tools or~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/binif you prefer the 32 bit tools) and call itgcc-sysroot.

Add the following lines ingcc-sysroot:

#!/bin/basharm-linux-gnueabihf-gcc --sysroot=$HOME/pi-tools/arm-bcm2708/arm-bcm2708hardfp-linux-gnueabi/arm-bcm2708hardfp-linux-gnueabi/sysroot "$@"

This is basically an alias forarm-linux-gnueabihf-gcc, but with the--sysroot set to where the libraries are kept. The"$@" part is there topass all the incoming argument forwards toarm-linux-gnueabihf-gcc. Alright,make the file executable:

chmod +x ~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/gcc-sysroot

or

chmod +x ~/pi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/gcc-sysroot

If your crate requires building C++ code, then you'll need to create ag++-sysroot justlikegcc-sysroot, substitutingarm-linux-gnueabihf-g++ forarm-linux-gnueabihf-gccinside.

And you should be done! Or, kind of done. There is one thing left.

It would be nice to just be able to runcargo build and be done with it, butthe reality is not exactly that nice. Almost, but not exactly. You will haveto add the binaries to your$PATH every time you open a new terminal and getready for compiling. You may also have to define some other variables tosatisfy some other systems. Sound tedious and boring, right? Well, that's whatwe have scripts for.

This repository contains two versions of the same script (cross32 for 32 bitandcross64 for 64 bit). They can be used as a substitute for Cargo, likethis:

./cross64 cargo-command path/to/rust path/to/pi/toolchainExamples:./cross64 build ~/some-other-rust ~/some-other-pi-tools./cross64 doc./cross64 "build --release"

The first argument is what you would normally pass tocargo. It can besingle commands, likebuild ordoc, or multiple arguments like"build --release". Note that the combined commands have to be passed as a singlestring.path/to/rust andpath/to/pi/toolchain are optional and should onlybe used if you want to use tools from somewhere else than what this guiderecommends.

These scripts will set up the required environment variables and run cargo foryou. All without polluting the external environment. You can include them inyour projects and modify them however you want.

That's it! You should now be ready to cross compile your Raspberry Piprojects.

Have fun!

Let's say your project uses some crate that depends on having opensslinstalled on the system. In this case you have to install the packagemanually into the ARM toolset.

Get these packages either from the raspberry, or download them online.

We'll assume that you're running Raspbian (i.e. deb files), but it should bestraight forward to adapt the steps to your dist/packages.

If you doapt-cache show libssl1.0.0 on the raspberry, you'll see this in theoutput:

Filename:    pool/main/o/openssl/libssl1.0.0_1.0.1e-2+rvt+deb7u17_armhf.deb

You should be able to find a match for that under ftp.debian.org/debian/pool, sothe resulting URL in this case is

http://ftp.debian.org/debian/pool/main/o/openssl/libssl-dev_1.0.1e-2+deb7u17_armhf.deb

If it's not there, see if it is still on the raspberry under/var/cache/apt/archive.

If you still can't find it, try searching for the filename online.

When you have the dependencies downloaded, extract them into the ARM toolchain:

# cd into the sysroot of the arm toolchaincd ~/pi-tools/arm-bcm2708/arm-bcm2708hardfp-linux-gnueabi/arm-bcm2708hardfp-linux-gnueabi/sysroot/# move the deb files here and use `ar` to extract the contents:ar p libssl1.0.0_1.0.1e-2+rvt+deb7u17_armhf.deb data.tar.gz | tar zx# Repeat for any other dependencies you may have..ar p libssl-dev_1.0.1e-2+rvt+deb7u17_armhf.deb data.tar.gz | tar zxar p zlib1g_1.2.7.dfsg-13_armhf.deb data.tar.gz | tar zxar p zlib1g-dev_1.2.7.dfsg-13_armhf.deb data.tar.gz | tar zx

Now you're ready to build the project.

Pull requests with enhancements, corrections or additional instructions arevery much appreciated. Good luck!