From fd3101315b61a12444ecce2d03c1b60fd6e82ed0 Mon Sep 17 00:00:00 2001 From: Taesung Hwang Date: Thu, 15 Feb 2024 14:57:17 -0800 Subject: [PATCH 1/8] Configure building Rust project for Raspberry Pi - Add Cargo config to set build target platform and linker - Include setup instructions in README --- pod-operation/.cargo/config.toml | 7 ++++++ pod-operation/README.md | 41 ++++++++++++++++++++++++++++---- 2 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 pod-operation/.cargo/config.toml diff --git a/pod-operation/.cargo/config.toml b/pod-operation/.cargo/config.toml new file mode 100644 index 00000000..3d94c332 --- /dev/null +++ b/pod-operation/.cargo/config.toml @@ -0,0 +1,7 @@ +# Configuration to cross-compile for Raspberry Pi + +[build] +target = "armv7-unknown-linux-gnueabihf" + +[target.armv7-unknown-linux-gnueabihf] +linker = "armv7-unknown-linux-gnueabihf-gcc" diff --git a/pod-operation/README.md b/pod-operation/README.md index c3b707d1..85156bda 100644 --- a/pod-operation/README.md +++ b/pod-operation/README.md @@ -4,9 +4,7 @@ This Rust package is for the main program to be run on the pod. The program runs a finite-state machine to operate the pod components and acts as a Socket.IO server to communicate with the control station. -## Usage - -### First-time Setup +## First-time Setup Install cargo-watch @@ -14,10 +12,45 @@ Install cargo-watch cargo install cargo-watch ``` -### Local Development +Add the build target for the Raspberry Pi + +```shell +rustup target add armv7-unknown-linux-gnueabihf +``` + +### Cross-Compilation + +Install the compiler for the Raspberry Pi platform + +#### macOS + +A homebrew formula for macOS cross-compiler toolchains is available + +```shell +brew tap messense/macos-cross-toolchains +brew install armv7-unknown-linux-gnueabihf +``` + +#### Windows + +TBD + +## Local Development To locally run the development server with auto-reload ```shell cargo watch -x run ``` + +## Building for Production + +To build for production, use the `--release` option + +```shell +cargo build --release +``` + +This will compile the project to +`target/armv7-unknown-linux-gnueabihf/release/pod-operation` +which can be run on the Raspberry Pi. From 23bacfb2cd2195bdb3f14d5d7c596d0b63a4e9f7 Mon Sep 17 00:00:00 2001 From: Sam Der Date: Fri, 23 Feb 2024 11:11:51 -0800 Subject: [PATCH 2/8] Add instructions for cross-compiling with cross --- pod-operation/README.md | 44 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/pod-operation/README.md b/pod-operation/README.md index 85156bda..88dea89b 100644 --- a/pod-operation/README.md +++ b/pod-operation/README.md @@ -31,9 +31,49 @@ brew tap messense/macos-cross-toolchains brew install armv7-unknown-linux-gnueabihf ``` -#### Windows +#### Windows/Linux -TBD +For both of these platforms, a different process is necessary. + +**Prerequisites** + +First, install [Docker](https://docs.docker.com/). You can either install +Docker Desktop or the more lightweight Docker Engine, which is only available +on Linux distributions. + +**Please note that on Linux, non-sudo users need to be in the `docker` group or +use rootless Docker.** You can read more about adding yourself to the group +[here](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). + +Next, install the [`cross`](https://github.com/cross-rs/cross) package by +running the below command in the `pod-operation/` directory. + +```shell +cargo install cross --git https://github.com/cross-rs/cross +``` + +This is the library that will facilitate cross-compilation without much +configuration on our end. It requires Docker in order to function. + +Ensure that `cross` is now on your `PATH`. Usually, it +is located in the `.cargo/bin` folder of your home directory, so if `cross` is not in your `PATH`, you can check this directory and add it to `PATH`. + +Now run + +```shell +cross build +``` + +and the program should build. On Linux, if an error appears about `GLIBC`, +you may need to install the `glibc` library. You can do this by running + +```shell +# Ubuntu/Debian-based distributions +sudo apt install glibc + +# Arch-based distributions +sudo pacman -S glibc +``` ## Local Development From e81fae6b5df590665d252420698768e7361a7823 Mon Sep 17 00:00:00 2001 From: Sam Der Date: Tue, 27 Feb 2024 14:49:39 -0800 Subject: [PATCH 3/8] Add Windows/Linux native building instructions --- pod-operation/.cargo/config.toml | 3 ++- pod-operation/README.md | 9 +++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/pod-operation/.cargo/config.toml b/pod-operation/.cargo/config.toml index 3d94c332..64494c9c 100644 --- a/pod-operation/.cargo/config.toml +++ b/pod-operation/.cargo/config.toml @@ -4,4 +4,5 @@ target = "armv7-unknown-linux-gnueabihf" [target.armv7-unknown-linux-gnueabihf] -linker = "armv7-unknown-linux-gnueabihf-gcc" +# linker = "armv7-unknown-linux-gnueabihf-gcc" +linker = "arm-none-linux-gnueabihf-gcc" diff --git a/pod-operation/README.md b/pod-operation/README.md index 88dea89b..06e8696e 100644 --- a/pod-operation/README.md +++ b/pod-operation/README.md @@ -33,6 +33,15 @@ brew install armv7-unknown-linux-gnueabihf #### Windows/Linux +For building natively, a different linker is required from the one +specified in `.cargo/config.toml`. Instead of `armv7-unknown-linux-gnueabihf-gcc` +for MacOS, we instead use `arm-none-linux-gnueabihf-gcc`, which can be downloaded +and installed [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads). +You will want to select the **AArch32 GNU/Linux target with hard float** to download. +Then in `.cargo/config.toml`, uncomment the line that has the appropriate linker. + + +#### Alternative Building Process With `cross` For both of these platforms, a different process is necessary. **Prerequisites** From a3c6101a7551902362a133abcce379ec560313e2 Mon Sep 17 00:00:00 2001 From: Sam Der Date: Tue, 27 Feb 2024 15:05:42 -0800 Subject: [PATCH 4/8] Update workflow to cross compile during build --- .github/workflows/run-checks.yml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/run-checks.yml b/.github/workflows/run-checks.yml index ed2cb595..1c6915a7 100644 --- a/.github/workflows/run-checks.yml +++ b/.github/workflows/run-checks.yml @@ -74,6 +74,12 @@ jobs: uses: dtolnay/rust-toolchain@stable with: components: clippy, rustfmt + + - name: Add target + run: rustup target add armv7-unknown-linux-gnueabihf + + - name: Install target building dependencies + run: sudo apt-get -qq install crossbuild-essential-armhf - name: Run cargo test run: cargo test @@ -84,5 +90,8 @@ jobs: - name: Lint pod operation run: cargo clippy -- -D warnings - - name: Build Pod Operation Program - run: cargo build + - name: Build Pod Operation Program (debug) + run: cargo build --config target.armv7-unknown-linux-gnueabihf.linker=\"arm-linux-gnueabihf-gcc\" + + - name: Build Pod Operation Program (release) + run: cargo build --config target.armv7-unknown-linux-gnueabihf.linker=\"arm-linux-gnueabihf-gcc\" --release \ No newline at end of file From d93ef74c5d80452397d506be32a911081b90d798 Mon Sep 17 00:00:00 2001 From: Taesung Hwang Date: Tue, 27 Feb 2024 23:22:34 -0800 Subject: [PATCH 5/8] Specify default target for cross in `Cross.toml` --- pod-operation/.cargo/config.toml | 5 +++-- pod-operation/Cross.toml | 2 ++ 2 files changed, 5 insertions(+), 2 deletions(-) create mode 100644 pod-operation/Cross.toml diff --git a/pod-operation/.cargo/config.toml b/pod-operation/.cargo/config.toml index 64494c9c..b830ab67 100644 --- a/pod-operation/.cargo/config.toml +++ b/pod-operation/.cargo/config.toml @@ -1,8 +1,9 @@ # Configuration to cross-compile for Raspberry Pi +# Uncomment lines as needed [build] -target = "armv7-unknown-linux-gnueabihf" +# target = "armv7-unknown-linux-gnueabihf" [target.armv7-unknown-linux-gnueabihf] # linker = "armv7-unknown-linux-gnueabihf-gcc" -linker = "arm-none-linux-gnueabihf-gcc" +# linker = "arm-none-linux-gnueabihf-gcc" diff --git a/pod-operation/Cross.toml b/pod-operation/Cross.toml new file mode 100644 index 00000000..703c6cb1 --- /dev/null +++ b/pod-operation/Cross.toml @@ -0,0 +1,2 @@ +[build] +default-target = "armv7-unknown-linux-gnueabihf" From 4acaffaea4a7ef5d6eeb85acb11f2bf8c7c430fc Mon Sep 17 00:00:00 2001 From: Taesung Hwang Date: Tue, 27 Feb 2024 23:23:00 -0800 Subject: [PATCH 6/8] Clean up cross-compilation directions in README --- pod-operation/README.md | 53 ++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/pod-operation/README.md b/pod-operation/README.md index 06e8696e..2d34fc1f 100644 --- a/pod-operation/README.md +++ b/pod-operation/README.md @@ -20,7 +20,8 @@ rustup target add armv7-unknown-linux-gnueabihf ### Cross-Compilation -Install the compiler for the Raspberry Pi platform +To compile for the Raspberry Pi target, a specific linker is needed for each operating system, +or [`cross`](https://github.com/cross-rs/cross) can be used to build inside a container. #### macOS @@ -33,16 +34,15 @@ brew install armv7-unknown-linux-gnueabihf #### Windows/Linux -For building natively, a different linker is required from the one -specified in `.cargo/config.toml`. Instead of `armv7-unknown-linux-gnueabihf-gcc` -for MacOS, we instead use `arm-none-linux-gnueabihf-gcc`, which can be downloaded -and installed [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads). -You will want to select the **AArch32 GNU/Linux target with hard float** to download. -Then in `.cargo/config.toml`, uncomment the line that has the appropriate linker. - +To cross-compile on Windows and Linux, a different compiler toolchain is needed. From the +[Arm GNU Toolchain Downloads](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), +download and install the **AArch32 GNU/Linux target with hard float (arm-none-linux-gnueabihf)** +for Windows or Linux. #### Alternative Building Process With `cross` -For both of these platforms, a different process is necessary. + +An alternative to installing cross-compilers is using `cross` to build and run the Rust project +using containers and emulation. This can be used on any operating system (macOS, Windows, Linux). **Prerequisites** @@ -54,27 +54,16 @@ on Linux distributions. use rootless Docker.** You can read more about adding yourself to the group [here](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). -Next, install the [`cross`](https://github.com/cross-rs/cross) package by -running the below command in the `pod-operation/` directory. +Next, install the `cross` package. ```shell -cargo install cross --git https://github.com/cross-rs/cross +cargo install cross ``` This is the library that will facilitate cross-compilation without much -configuration on our end. It requires Docker in order to function. - -Ensure that `cross` is now on your `PATH`. Usually, it -is located in the `.cargo/bin` folder of your home directory, so if `cross` is not in your `PATH`, you can check this directory and add it to `PATH`. - -Now run - -```shell -cross build -``` +configuration on our end. It requires Docker (or Podman) in order to function. -and the program should build. On Linux, if an error appears about `GLIBC`, -you may need to install the `glibc` library. You can do this by running +On Linux, if an error appears during build about `GLIBC`, install the `glibc` library. ```shell # Ubuntu/Debian-based distributions @@ -94,12 +83,22 @@ cargo watch -x run ## Building for Production -To build for production, use the `--release` option +Uncomment the arm-linux linker for your operating system in `.cargo/config.toml`. + +To build for production, use the `--release` option: + +```shell +cargo build --target armv7-unknown-linux-gnueabihf --release +``` + +Alternatively, use `cross` to compile in a container: ```shell -cargo build --release +cross build --release ``` -This will compile the project to +Note: the default target is already specified in `Cross.toml`. + +Either approach will compile the project to `target/armv7-unknown-linux-gnueabihf/release/pod-operation` which can be run on the Raspberry Pi. From 9f5aeb185100bdfb9e98ad41150791f52ebcb206 Mon Sep 17 00:00:00 2001 From: Taesung Hwang Date: Wed, 28 Feb 2024 00:20:35 -0800 Subject: [PATCH 7/8] Fix crossbuild installation in Actions runner --- .github/workflows/run-checks.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/run-checks.yml b/.github/workflows/run-checks.yml index 1c6915a7..cdd6db33 100644 --- a/.github/workflows/run-checks.yml +++ b/.github/workflows/run-checks.yml @@ -66,6 +66,8 @@ jobs: defaults: run: working-directory: ./pod-operation + env: + TARGET: armv7-unknown-linux-gnueabihf steps: - name: Check out repository uses: actions/checkout@v4 @@ -74,12 +76,12 @@ jobs: uses: dtolnay/rust-toolchain@stable with: components: clippy, rustfmt - + - name: Add target - run: rustup target add armv7-unknown-linux-gnueabihf - + run: rustup target add $TARGET + - name: Install target building dependencies - run: sudo apt-get -qq install crossbuild-essential-armhf + run: sudo apt-get update && sudo apt-get -qq install crossbuild-essential-armhf - name: Run cargo test run: cargo test @@ -91,7 +93,7 @@ jobs: run: cargo clippy -- -D warnings - name: Build Pod Operation Program (debug) - run: cargo build --config target.armv7-unknown-linux-gnueabihf.linker=\"arm-linux-gnueabihf-gcc\" + run: cargo build --target $TARGET --config target.$TARGET.linker=\"arm-linux-gnueabihf-gcc\" - name: Build Pod Operation Program (release) - run: cargo build --config target.armv7-unknown-linux-gnueabihf.linker=\"arm-linux-gnueabihf-gcc\" --release \ No newline at end of file + run: cargo build --target $TARGET --config target.$TARGET.linker=\"arm-linux-gnueabihf-gcc\" --release From d525067cf5c8259ac772709be9fca197b371dbef Mon Sep 17 00:00:00 2001 From: Taesung Hwang Date: Wed, 28 Feb 2024 13:12:10 -0800 Subject: [PATCH 8/8] Revise README once more --- pod-operation/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pod-operation/README.md b/pod-operation/README.md index 2d34fc1f..42db5132 100644 --- a/pod-operation/README.md +++ b/pod-operation/README.md @@ -25,7 +25,7 @@ or [`cross`](https://github.com/cross-rs/cross) can be used to build inside a co #### macOS -A homebrew formula for macOS cross-compiler toolchains is available +A Homebrew formula for macOS cross-compiler toolchains is available ```shell brew tap messense/macos-cross-toolchains @@ -37,7 +37,7 @@ brew install armv7-unknown-linux-gnueabihf To cross-compile on Windows and Linux, a different compiler toolchain is needed. From the [Arm GNU Toolchain Downloads](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), download and install the **AArch32 GNU/Linux target with hard float (arm-none-linux-gnueabihf)** -for Windows or Linux. +for your operating system. #### Alternative Building Process With `cross` @@ -60,8 +60,9 @@ Next, install the `cross` package. cargo install cross ``` -This is the library that will facilitate cross-compilation without much -configuration on our end. It requires Docker (or Podman) in order to function. +This is the library that will facilitate cross-compilation with minimal additional configuration. +`cross` requires Docker (or Podman) in order to function and will also emulate the ARM architecture +inside the container using QEMU. On Linux, if an error appears during build about `GLIBC`, install the `glibc` library.