Creating a project with zinc

Creating a project with zinc

This document explains how to get started creating your own project based on zinc.

Prerequisites

Before continuing, install a cross-compiler toolchain for your chosen target triple. As zinc only supports ARM a the moment, your target triple is most likely arm-none-eabi.

Project Setup

Step 1: Creating a cargo project

Create a new cargo project that builds a binary

$ cargo new --bin my-zinc-project
$ cd my-zinc-project

Step 2: Add zinc as dependency in Cargo.toml

Add the following to your the Cargo.toml in the root of your new project, replacing <platform> with the name of your platform.

[dependencies.zinc]
git = "https://github.com/hackndev/zinc.git"
features = ["<platform>"]

[dependencies.macro_zinc]
git = "https://github.com/hackndev/zinc.git"
path = "macro_zinc"

If you want to access features from libcore, please use the version of libcore that zinc uses, to avoid re-defining a lot of rust's lang-items and to ensure that you're using the right version of libcore for your compiler. It is very likely that you will need this.

[dependencies.core]
git = "https://github.com/hackndev/rust-libcore.git"

If you plan on using the platformtree features of zinc, you will need the following dependency.

[dependencies.macro_platformtree]
git = "https://github.com/hackndev/zinc.git"
path = "macro_platformtree"

If you plan on using the ioreg crate from zinc manually in your code, then you will need the following dependency.

[dependencies.ioreg]
git = "https://github.com/hackndev/zinc.git"
path = "ioreg"

Step 3: Copy a target-spec file from zinc

Copy the target spec file for your target from zinc to the root of your project (i.e. thumbv7m-none-eabi.json for cortex-m3 processors).

Step 4: Tell cargo about your toolchain

NOTE: This may be done with autotools or some kind of conifguration tool (see the zinc repository) but a manual method will be described here.

Cargo needs to know which archiver and linker to use when compiling things for your target. This can be done easily by using a cargo configuration script. Simply add your version of ar and linker and triple where applicable in .cargo/config. The desired triple is the rustc triple not necessarily the triple of your toolchain (i.e. thumbv7m-none-eabi or thumbv7em-none-eabi).

[target.$triple]
ar = "$ar"
linker = "$linker"

Step 5: Conversion from ELF binary to artifacts

Depending on the target, you will probably have to create a Makefile or something similar to convert the resulting ELF binary produced by cargo build to the file you need for your target. A simple example by @posborne can be seen below.

# Toolchain
OBJCOPY=arm-none-eabi-objcopy
OBJDUMP=arm-none-eabi-objdump

# Target
TARGET=thumbv7m-none-eabi

# Files
OUT_DIR=target/$(TARGET)/release
OUT_FILE=$(OUT_DIR)/blink

.PHONY: build clean listing $(OUT_FILE)

all: build listing
build: $(OUT_FILE).bin
listing: $(OUT_FILE).lst

$(OUT_FILE):
	cargo build --release --target=$(TARGET) --verbose

$(OUT_DIR)/%.bin: $(OUT_DIR)/%
	$(OBJCOPY) -O binary $< $@

$(OUT_DIR)/%.lst: $(OUT_DIR)/%
	$(OBJDUMP) -D $< > $@

clean:
	cargo clean

Step 6: Develop your project

Now, start developing your project using zinc! You can use the zinc examples as a starting place.