Role of xargo and generally getting started

[ninjasource]

Hi Jorge,

Thanks for your epic contributions to the whole embedded rust ecosystem, very impressive. Unfortunately though, I am having trouble running your example. Consider the Documentation section of your crate (copied) below:

---

$ git clone https://github.com/japaric/stm32f103xx-hal

// on another terminal
$ openocd -f interface/$INTERFACE.cfg -f target/stm32f1x.cfg

// flash and debug the "Hello, world" example
// NOTE examples assume 64KB of Flash and 20KB of RAM; you can tweak layout in memory.x
$ cd stm32f103xx-hal
$ xargo run --example hello

---

A beginner is going to be very confused by your openocd command there especially since some setups won't know where to locate the $INTERFACE.cfg file or what that means at all. Consider all OS's this will be run on. I think that it would be better to include a basic openocd.cfg file in the root of this project for convenience. Also, just saying what openocd does with a brief description and how it relates to this project goes a long way.

Furthermore, the role of xargo is not clear. The first thing you read about xargo when visiting your github repo is that it is in maintenance mode. To the newbie, this indicates that it is no longer required (or needed) for embedded rust development on coretex-m devices. This is further reinforced when you read the embedded rust book. Xargo is just a side note. It would be useful to say why it is important. For example, why do you have to build libcore (my understanding of the reason for xargo's existence) for the stm32f103xx examples when you can build a simple hello world in the coretex_m_quickstart and run it on a stm32f103xx device without xargo altogether?

Right now, the command "xargo run --example hello" fails with the following error message: "error: Could not compile compiler_builtins". This is being actively being discussed in the github xargo Issues section but it is difficult to figure out what to do. This looks like a new problem but using previous versions of nightly does not seem to work either. Perhaps you could state a nightly build number that your repo was known to build successfully on.

Keep up the great work, I hope I can contribute something soon!

[burrbull]

You are using outdated manual.
Xargo is not needed.

Read Embedded Book or
cortex_m_quickstart v 0.3.1.

[ninjasource]

Thanks!

The reason I ask is because a regular cargo build does not work either and I assumed that it had something to do with xargo (probably best to remove that old documentation)

For example, running the following:
cargo build --example blinky

Gives the following error on Nightly
Compiling cortex-m-rtfm-macros v0.4.0
error[E0658]: use of extern prelude names introduced with extern crate items is unstable (see issue #54658)
--> C:\Users\xxxxx.cargo\registry\src\github.com-1ecc6299db9ec823\cortex-m-rtfm-macros-0.4.0\src\lib.rs:6:5
|
6 | use proc_macro::TokenStream;
| ^^^^^^^^^^
|
= help: add #![feature(extern_crate_item_prelude)] to the crate attributes to enable

Toolchain:
nightly-x86_64-pc-windows-msvc unchanged - rustc 1.33.0-nightly (75a369c5b 2019-01-12)

Adding that attribute to the blinky.rs example does not fix it either.

[therealprof]

@ninjasource Yeah, there's something wonky going on with the latest nightlies. We're also picking up spurious errors with our CI systems. Is stable rust not an option for you?

[ninjasource]

Unfortunately it does not build on stable either. Same error. Do you know what version of nightly these examples build against? I've tried going back to October with no success.

It looks like this has something to do with the latest release of rtfm (0.4.0)

[therealprof]

@ninjasource Sorry I forgot that this crate doesn't build on stable. May I humbly recommend you try https://github.com/stm32-rs/stm32f1xx-hal on stable instead?

The examples compile as follows:

cargo build --release --example blinky --features="stm32f103,rt"

[TeXitoi]

This crate should build on stable.

[therealprof]

@TeXitoi The lib part does, the examples do not:

error[E0554]: #![feature] may not be used on the stable release channel
 --> /Users/egger/.cargo/registry/src/github.com-1ecc6299db9ec823/untagged-option-0.1.1/src/lib.rs:5:1
  |
5 | #![feature(untagged_unions, const_fn)]
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to previous error

[TeXitoi]

Ha, OK.

[ninjasource]

@ninjasource Sorry I forgot that this crate doesn't build on stable. May I humbly recommend you try https://github.com/stm32-rs/stm32f1xx-hal on stable instead?

The examples compile as follows:

cargo build --release --example blinky --features="stm32f103,rt"

Thanks Daniel, that works!

If anyone else reads this thread then be aware that you need to install the thunmv7m-non-eabi triple target on stable before you can do this. This can be achieved with the following command:
rustup target install thumbv7m-none-eabi
Also note that the features compile flag above is important too. It won't simply build with "cargo build"

[ninjasource]

Hi,

Is there any way to specify the features in the ./cargo/config file?
Under the [build] section there is a rustflags key but it is not clear if that can be used to pass in the features. Ideally it would be nice for developers to download this repo and simply type cargo build to build it. It is also nicer for IDE tooling.

Here are the docs which don't mention features unfortunately:
https://doc.rust-lang.org/cargo/reference/config.html

David

[burrbull]

You need not download this repo.
You should create new program with cargo new or cargo generate and make dependency from hal.

[dependencies.stm32f1xx-hal]
version = "0.1"
features = ["stm32f103", "rt"]

in your program Cargo.toml

[ninjasource]

Thanks burrbull but surely if you clone this repo and simply type "cargo build --example blinky" it should "just work" and if it doesn't then there should be instructions on how to make it work in the README.md file. For example, why does "cargo build --example blinky --features "stm32f103,rt" " not work? I think it would lower the barrier to entry if devs at least knew how to build it.

Also, if library builds on stable but the examples do not then that should be in the README.md file too.