Using Rust with the Kubos SDK¶

The Kubos SDK Vagrant box comes with support for Rust, Cargo, and several helper tools to integrate C-based Kubos libraries with Rust projects.

Note

All of the following instructions are assumed to be run inside of the Kubos SDK Vagrant environment.

New Project¶

A new Rust project can be created by running either of the following commands:

Executable project:

cargo new --bin bin_name

Library project:

cargo new lib_name

Cargo will create the project folder and a basic folder structure.

Compiling¶

To compile the project use the normal Cargo build command:

$ cargo build --target [target]

The resulting binary will be located in {project directory}/target/{target}/debug/{project name}.

This binary can then be transferred to the target OBC for execution.

You may also omit the --target parameter in order to build the project to run directly in your Vagrant image. Use cargo run to trigger execution in this case.

Cross-compilation¶

The Kubos SDK provides Rust cross-compilation targets for each of the supported OBCs.

The target name varies depending which command is used to compile the project.

OBC	`cargo build`
Beaglebone Black	arm-unknown-linux-gnueabihf
ISIS-OBC	armv5te-unknown-linux-gnueabi
Pumpkin MBM2	arm-unknown-linux-gnueabihf

Some Rust crates require that the C compiler be explicitly declared when cross-compiling.

OBC	Compiler Path
Beaglebone Black	/usr/bin/bbb_toolchain/usr/bin/arm-linux-gcc
ISIS-OBC	/usr/bin/iobc_toolchain/usr/bin/arm-linux-gcc
Pumpkin MBM2	/usr/bin/bbb_toolchain/usr/bin/arm-linux-gcc

This can be done by specifying the C compiler path in the CC envar like so:

$ CC={path} cargo build --target {target}

For example:

$ CC=/usr/bin/iobc_toolchain/usr/bin/arm-linux-gcc cargo build --target armv5te-unknown-linux-gnueabi

Some crates depend on pkg-config, which requires that an additional flag, PKG_CONFIG_ALLOW_CROSS, be set in order to enable cross-compiling:

$ PKG_CONFIG_ALLOW_CROSS=1 CC=/usr/bin/iobc_toolchain/usr/bin/arm-linux-gcc cargo build --target armv5te-unknown-linux-gnueabi

Flashing¶

Note

The addition of Rust to the Kubos SDK is pretty recent and SDK tooling is currently undergoing revision to make the flashing process smoother!

Rust binaries can be transferred to the target OBC via a supported file transfer method.

Binaries may be transferred to any location on the target board, however, they should be copied to /home/system/usr/bin if you would like them to be automatically accessible via the system PATH.

Running on Target¶

Once transferred, the binary can be started with ./binary-name if you log in to the board and navigate to the specific directory in which the file is located, or without the ./ characters from any location if the file was transferred to a system PATH directory.

Formatting¶

The rustfmt tool can be used to automatically edit your source code to match the current Rust standards.

To format your code:

Install rustfmt:
```
$ rustup component add rustfmt-preview
```
Navigate to your project folder
Run the formatting tool via Cargo:
```
$ cargo fmt
```

Important Notes¶

Kubos is currently using the 0.4.2-stable version of rustfmt.
Using cargo install rustfmt to install rustfmt will result in the deprecated version being installed, which has slightly different formatting rules. Please use the rustup installation method instead.