Add support for Cargo

[dbrgn]

Cargo is the Rust package manager. It handles metadata, compilation and dependencies.

If we want to properly integrate with the Rust library ecosystem, we should support Cargo.

This would replace #7 and #8.

[tjpeden]

I actually took a stab at this the other day. I am really close but ran into an issue. I am happy to dig into it more tonight and this weekend.

[tjpeden]

Here's my progress so far: tjpeden@38529b1

There are some formatting changes in application.rs that aren't really important, but what is important is that I changed the delay parameters down to 100ms but my photon is still blinking as if it were 500ms (from when I flashed the original code). The DFU shows successful in the output of make PLATFORM=photon all program-dfu in main/ So, that is what I will figure out next.

Let me know if you want/need me to change anything I've done. I'm compiling a few other libraries from rust but I'm not 100% sure if we need/want them?

[tjpeden]

I'm now sure how to tell Cargo to let the makefiles dictate the target dirs. Thoughts?

[japaric]

@tjpeden Did you forget to commit the Cargo.toml file? AFAIK, you can't call cargo without a Cargo.toml file and a project directory. See http://doc.crates.io/guide.html

I'm compiling a few other libraries from rust but I'm not 100% sure if we need/want them?

We only need the core crate in this case.

I'm now sure how to tell Cargo to let the makefiles dictate the target dirs. Thoughts?

If you mean telling cargo to use a custom target directory, then you can use a configuration file with the following key:

# .cargo/config
[build]
target-dir = "custom/target/directory"

Then cargo will output the binary/docs to "custom/target/directory" instead of the default "target" directory.

[japaric]

Other thoughts:

With cargo support we wouldn't need the build_core.sh script. There is cargo crate: rust-libcore that builds the core crate when used as a dependency.

Ideally, I'd like to only use cargo to build particle applications. I'm envisioning something like this:

$ cargo new --bin app
$ cd app

# depend on particle libraries
$ vim Cargo.toml
$ cat Cargo.toml
[package]
name = "app"
version = "0.1.0"
authors = ["me"]

[dependencies]
particle = "0.1.0"

# write app
$ vim src/main.rs

# builds the core crate, particle's C dependencies, and the app
$ cargo build --target=photon

# This installs the cargo-flash and cargo-debug binaries used below
$ cargo install particle-tools

# Custom cargo subcommand that flashes the application
# This subcommand can just shell out to `particle flash ...`
$ cargo flash

# Or, start a remote gdb session
$ cargo debug

I'm sure this is feasible because I have done the cargo build part here. Check the "apps" and the travis output, specially the *-size and *-objdump calls. But, I'm not sure how to expand this to produce a binary or ELF file that's usable by particle's bootloader because I'm not familiar with bootloaders in general as I always flash programs directly at the start of the flash memory (0x08000000).

Can anyone point me to information about particle's bootloader or bootloaders in general. Does the bootloader expect an ELF file that starts at some specific address, other than 0x08000000? Does the particle's bootloader expect the ELF file to contain some specific symbols?

[dbrgn]

@japaric woah, that would be pretty awesome :)

[tjpeden]

@japaric, you're right, I did. Fixed. Also just committed my attempt at using .cargo/config. The problem is I think that the path is based on a couple make variables (if I understand the make spaghetti correctly lol). Either way, it doesn't place the output files where make expects them, even if I specify the directory that the .o is normally placed, cargo will still use it's own directory structure from there. Not to mention I currently have it outputting a .a file.

All of that aside, everything I've seen online has cautioned against using that crate, but maybe that's wrong? I like the idea of using only cargo for building and programming the rust code.

What crate should we use to test being able to use extern crate to make sure it works?

Unfortunately, my fiance won't let me work on it anymore today. lol

[tjpeden]

@japaric, I really like that project you linked. I think that would be an awesome way to model the Particle Rust support

[towynlin]

@japaric This is looking great. Thank you!

Photon firmware consists of several dynamically linked modules. If you run make in the modules folder 3 of the modules will be built if you want to see some examples.

• 0x08000000 Bootloader
• 0x08020000 System part 1
• 0x08060000 System part 2
• 0x080a0000 User application

The addresses and number of modules may be different on different platforms. I often reference this file in the CLI: https://github.com/spark/particle-cli/blob/master/lib/deviceSpecs/specifications.js

Additionally, there are several pieces of data prepended and appended to our modules using linker scripts. Here's a tool for reading them: https://github.com/spark/binary-version-reader

Hope that helps!

[japaric]

@tjpeden

@japaric, you're right, I did. Fixed. Also just committed my attempt at using .cargo/config. The problem is I think that the path is based on a couple make variables (if I understand the make spaghetti correctly lol). Either way, it doesn't place the output files where make expects them, even if I specify the directory that the .o is normally placed, cargo will still use it's own directory structure from there. Not to mention I currently have it outputting a .a file.

I guess you can let cargo output its files in the default target directory, and add some cp commands to the Makefile to move the files when the rest of the build system expects them.

About the *.a file, you should be able to use something like cargo rustc -- --emit=obj to make cargo output *.o files.

All of that aside, everything I've seen online has cautioned against using that crate, but maybe that's wrong? I like the idea of using only cargo for building and programming the rust code.

You mean the rust-libcore crate? What's the argument against it? The zinc project also uses that crate to build the core crate.

What crate should we use to test being able to use extern crate to make sure it works?

You can test with the spin crate, that crate works with just the core crate.

---

@towynlin That's pretty helpful. I took a quick look and I'm starting to understand how the pieces fall together. Looks like the setup and loop symbols are mandatory, right? During the weekend, I'll take a closer look to the linker scripts and see if I can hack my copper cargo project to generate an ELF file that matches the layout of the user-part example you pointed out. I don't have hardware yet so that's as far I can go right now.

[tjpeden]

Added the spin crate and got the following error running make PLATFORM=photon all program-dfu from main/:

...
cargo rustc --target thumbv7m-none-eabi -- -O -Z no-landing-pads -g -L ../build/arm/rust
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Compiling spin v0.3.5
/home/tjp/.multirust/toolchains/nightly/cargo/registry/src/github.com-88ac128001ac3a9a/spin-0.3.5/src/lib.rs:1:1: 1:1 error: can't find crate for `core` [E0463]

This is how I have the Cargo.toml configured:

[package]
name = "application"
version = "0.1.0"
authors = ["TJ Peden <tj@tjcoding.com>"]

[lib]
crate-type = ["staticlib"]

[dependencies]
rust-libcore = "0.0.3"
spin = "0.3.5"

I'm not sure how to fix that.

[japaric]

@tjpeden Ah right, spin can't be cross compiled like this because it (spin) would need to depend on rust-libcore but it doesn't. One "solution" would be install the libcore.rlib that cargo build --target= generated in your rust installation directory. But I don't like this solution because it pollutes your Rust install. Let me discuss this with other Rust devs to see if there's a cleaner solution.

[tjpeden]

IRC?