From 7861568ca1e3e52ccdfd861f518e342cf7c2a767 Mon Sep 17 00:00:00 2001
From: Nadja Reitzenstein <me@dequbed.space>
Date: Tue, 31 May 2022 11:54:46 +0200
Subject: [PATCH] Cross-compilation docs

---
 .cargo/config.toml |  2 --
 CONTRIBUTING.md    | 37 +++++++++++++++++++++++++++++++++++++
 INSTALL.md         | 13 ++++++++++---
 3 files changed, 47 insertions(+), 5 deletions(-)
 delete mode 100644 .cargo/config.toml

diff --git a/.cargo/config.toml b/.cargo/config.toml
deleted file mode 100644
index d5135e9..0000000
--- a/.cargo/config.toml
+++ /dev/null
@@ -1,2 +0,0 @@
-[build]
-rustflags = ["-C", "target-cpu=native"]
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5495986..ffa76e6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -75,6 +75,43 @@ When you want feedback on your current progress or are ready to have it merged u
 request. Don't worry we don't bite! ^^
 
 
+# Development Setup
+
+## Cross-compilation
+
+If you want to cross-compile you need both a C-toolchain for your target
+and install the Rust stdlib for said target.
+
+As an example for the target `aarch64-unknown-linux-gnu` (64-bit ARMv8
+running Linux with the glibc, e.g. a Raspberry Pi 3 or later with a 64-bit
+Debian Linux installation):
+
+1. Install C-toolchain using your distro package manager:
+    - On Archlinux: `pacman -S aarch64-unknown-linux-gnu-gcc`
+2. Install the Rust stdlib:
+    - using rustup: `rustup target add aarch64-unknown-linux-gnu`
+3. Configure your cargo config:
+
+### Configuring cargo
+
+You need to tell Cargo to use your C-toolchain. For this you need to have
+a block in [your cargo config](https://doc.rust-lang.org/cargo/reference/config.html) setting at
+least the paths to the gcc as `linker` and ar as `ar`:
+
+```toml
+[target.aarch64-unknown-linux-gnu]
+# You must set the gcc as linker since a lot of magic must happen here.
+linker = "aarch64-linux-gnu-gcc"
+ar = "aarch64-linux-gnu-ar"
+```
+
+To actually compile for the given triple you need to call `cargo build`
+with the `--target` flag:
+
+```
+$ cargo build --release --target=aarch64-unknown-linux-gnu
+```
+
 ## Tests
 
 Sadly, still very much `// TODO:`. We're working on it! :/
diff --git a/INSTALL.md b/INSTALL.md
index 0be015f..bab36ef 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,4 +1,4 @@
-## Installation
+# Installation
 
 Currently there are no distribution packages available.
 However installation is reasonably straight-forward, since Diflouroborane compiles into a single
@@ -7,7 +7,7 @@ mostly static binary with few dependencies.
 At the moment only Linux is supported. If you managed to compile Diflouroborane please open an issue
 outlining your steps or add a merge request expanding this part. Thanks!
 
-### Requirements
+## Requirements
 
 General requirements; scroll down for distribution-specific instructions
 
@@ -24,7 +24,7 @@ General requirements; scroll down for distribution-specific instructions
 $ pacman -S gsasl rust capnproto
 ```
 
-### Compiling from source
+## Compiling from source
 
 Diflouroborane uses Cargo, so compilation boils down to:
 
@@ -33,3 +33,10 @@ $ cargo build --release
 ```
 
 The compiled binary can then be found in `./target/release/diflouroborane`
+
+### Cross-compiling
+
+If you need to compile for a different CPU target than your own (e.g. you want
+to use BFFH on a raspberry pi but compile on your desktop PC), you need to
+setup a cross-compilation toolchain and configure your Cargo correctly.
+[The `CONTRIBUTING.md` has a section on how to setup a cross-compilation system.](CONTRIBUTING.md#cross-compilation)