Skip to content

add "the path towards stable" announcement #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 13, 2018
Merged

add "the path towards stable" announcement #96

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c486c54
add "the path towards stable" announcement
japaric May 12, 2018
30a87d5
update / fix links
japaric May 12, 2018
cddf3a8
address review comments
japaric May 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 195 additions & 0 deletions newsletters/2018-05-12-the-path-towards-stable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
# Cortex-M library development now possible on beta and the path towards stable embedded Rust

> 2018-05-12

We are happy to announce that *library* development for the Cortex-M targets is now possible on the
Copy link
Member

@jamesmunns jamesmunns May 12, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be good to have a tl;dr at the top for those that are passively watching the ecosystem. I would suggest something like this:

Larger TL;DR:

> **TL;DR**
>
> As we make progress to getting embedded development as a first class member of the
> Rust ecosystem, we are making (necessary) changes which may break a number of crates
> in the short term. Once we have landed all of the changes to make stable embedded
> development possible, we expect this breakage to stop.
>
> If you are an embedded crate maintainer, keep an eye out for changes that affect your
> crates (see below for more details). Make sure to test your crates on the current
> `beta` release, and ping someone on the #rust-embedded IRC channel if you see something
> broken!

Shorter TL;DR:

> **TL;DR**
>
> * We are making breaking changes in order to move towards stable development
> * Some crates will break with these changes, if you notice something, file an issue and/or ping us on the #rust-embedded IRC channel
> * These breaking changes will slow down once we have landed necessary features in stable
> * If you are a crate maintainer, make sure you test your crates with the new versions of `cortex-m` (and similar) on the current `beta` release of Rust
> * Thanks for your patience!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jamesmunns. I think this a great idea; I'll add one of those.

I think something that should be explicitly noted is that stability / breakage is mainly referring to the compiler and language features, and that the libraries are not becoming stable in the 1.0 sense so more iteration with breaking changes in new minor version releases will continue to happen.

beta channel! :tada:

For example, to cross compile a library crate for the Cortex-M3 you would run these commands:

``` console
$ # switch to the beta channel
$ rustup default beta

$ # install the rust-std component (pre-compiled core) for the target
$ rustup target add thumbv7m-none-eabi

$ # get some source to build
$ cargo clone cortex-m --vers 0.5.0 && cd cortex-m

$ # then It Just Works
$ cargo build --target thumbv7m-none-eabi
```

What about embedded *application* development? There is just a single unstable feature that prevents
us from building a `no_std` binary on stable: the `panic_fmt` lang item. This unstable feature will
soon be removed in favor of the `#[panic_implementation]` feature ([implementation PR]), which is
slated for stabilization in time for the edition release (we are hoping to stabilize it as early as
1.28 but we'll see).

[implementation PR]: https://github.com/rust-lang/rust/pull/50338

## Making the Cortex-M ecosystem work on stable

"`no_std` binaries are *possible* on stable" is very different from "*my* embedded application
builds on stable". The later requires all the dependencies to also compile on stable. So we are
starting to migrate the Cortex-M ecosystem to work on stable. All the crates listed below are now
compiling on the beta channel.

Legend: `crate-name` - link to CHANGELOG - link to stabilization PR - ~removed unstable features~

- [`cortex-m-quickstart`][c0] - [CHANGELOG][ch0] - [PR][p0]

[c0]: https://docs.rs/cortex-m-quickstart/~0.3
[ch0]: https://github.com/japaric/cortex-m-quickstart/blob/master/CHANGELOG.md#v030---2018-05-12
[p0]: https://github.com/japaric/cortex-m-quickstart/pull/29

- [`cortex-m-rt`][c1] - [CHANGELOG][ch1] - [PR][p1] - ~asm!~ ~core_intrinsics~ ~global_asm!~
~lang_items~ ~linkage~ ~naked_functions~ ~used~

[c1]: https://crates.io/crates/cortex-m-rt/0.5.0
[ch1]: https://github.com/japaric/cortex-m-rt/blob/master/CHANGELOG.md#v050---2018-05-12
[p1]: https://github.com/japaric/cortex-m-rt/pull/69

- [`cortex-m-semihosting`][c2] - [CHANGELOG][ch2] - [PR][p2]

[c2]: https://crates.io/crates/cortex-m-semihosting/0.3.0
[ch2]: https://github.com/japaric/cortex-m-semihosting/blob/master/CHANGELOG.md#v030---2018-05-10
[p2]: https://github.com/japaric/cortex-m-semihosting/pull/16

- [`cortex-m`][c3] - [CHANGELOG][ch3] - [PR][p3] - ~asm!~ ~const_fn~

[c3]: https://crates.io/crates/cortex-m/0.5.0
[ch3]: https://github.com/japaric/cortex-m/blob/master/CHANGELOG.md#v050---2018-05-11
[p3]: https://github.com/japaric/cortex-m/pull/88

- [`embedded-hal`][c4] - [CHANGELOG][ch4] - [PR][p4] - ~never_type~

[c4]: https://crates.io/crates/embedded-hal/0.2.0
[ch4]: https://github.com/japaric/embedded-hal/blob/master/CHANGELOG.md#v020---2018-05-12
[p4]: https://github.com/japaric/embedded-hal/pull/80

- [`f3`][c5] - [CHANGELOG][ch5] - [PR][p5]

[c5]: https://crates.io/crates/f3/0.6.0
[ch5]: https://github.com/japaric/f3/blob/master/CHANGELOG.md#v060---2018-05-12
[p5]: https://github.com/japaric/f3/pull/93

- [`l3gd20`][c6] - [CHANGELOG][ch6] - [PR][p6] - ~Unsized~

[c6]: https://crates.io/crates/l3gd20/0.2.0
[ch6]: https://github.com/japaric/l3gd20/blob/master/CHANGELOG.md#v020---2018-05-12
[p6]: https://github.com/japaric/l3gd20/pull/4

- [`lsm303dlhc`][c7] - [CHANGELOG][ch7] - [PR][p7] - ~Unsized~

[c7]: https://crates.io/crates/lsm303dlhc/0.2.0
[ch7]: https://github.com/japaric/lsm303dlhc/blob/master/CHANGELOG.md#v020---2018-05-12
[p7]: https://github.com/japaric/lsm303dlhc/pull/4

- [`stm32f103xx`][c8] - [CHANGELOG][ch8] - [PR][p8] - ~const_fn~ ~global_asm!~ ~try_from~
~use_extern_macros~ ~used~

[c8]: https://crates.io/crates/stm32f103xx/0.10.0
[ch8]: https://github.com/japaric/stm32f103xx/blob/master/CHANGELOG.md#v0100---2018-05-12
[p8]: https://github.com/japaric/stm32f103xx/pull/24

- [`stm32f30x-hal`][c9] - [CHANGELOG][ch9] - [PR][p9] - ~never_type~

[c9]: https://crates.io/crates/stm32f30x-hal/0.2.0
[ch9]: https://github.com/japaric/stm32f30x-hal/blob/master/CHANGELOG.md#v020---2018-05-12
[p9]: https://github.com/japaric/stm32f30x-hal/pull/25

- [`stm32f30x`][c10] - [CHANGELOG][ch10] - [PR][p10] - ~const_fn~ ~global_asm!~ ~try_from~
~use_extern_macros~ ~used~

[c10]: https://crates.io/crates/stm32f30x/0.7.0
[ch10]: https://github.com/japaric/stm32f30x/blob/master/CHANGELOG.md#v070---2018-05-12
[p10]: https://github.com/japaric/stm32f30x/pull/16

- [`svd2rust`][c11] - [CHANGELOG][ch11] - [PR][p11]

[c11]: https://crates.io/crates/svd2rust/0.13.0
[ch11]: https://github.com/japaric/svd2rust/blob/master/CHANGELOG.md#v0130---2018-05-12
[p11]: https://github.com/japaric/svd2rust/pull/203

There's a lot of breaking changes there but the most visible one is `cortex-m-rt` because it changes
how applications are structured. Check the [`cortex-m-quickstart`][c0] template for instructions on
how to set up an embedded application using the latest versions of everything.

There are still a lot of crates that will need to be updated to work on beta. Among the more general
purpose ones we have [`heapless`] and [`cortex-m-rtfm`], which needs to be update to work with
`cortex-m-rt` v0.5.0.

[`heapless`]: https://crates.io/crates/heapless
[`cortex-m-rtfm`]: https://crates.io/crates/cortex-m-rtfm

### How you can help us

Try to compile your Cortex-M crate using the beta channel! If your crate is an application the build
will certainly fail, but check if all the dependencies, excluding the [panic handler crate][phc],
compile on beta. If any dependency doesn't compile on the beta channel let the author know, but
first check if there's a new version of the crate that already compiles on the beta channel. And if
you feel up to the task you could even send a PR to the dependency to make it compile on beta -- the
list of stabilization PRs in the previous section may give you a clue on how to move the crate to
beta.

If you are the author of a Cortex-M device crate, a crate generated using `svd2rust`, moving it to
stable only requires regenerating it using `svd2rust` v0.13.0. Do note that the generation process
[has changed] for the Cortex-M target, and make sure you bump the minor version when you publish a
new version.

[has changed]: https://docs.rs/svd2rust/0.13.0/svd2rust/#usage

If you are the author of a driver crate or a HAL implementation, please update your crate to use
v0.2.0 of `embedded-hal` and test that it builds on beta. Make sure you bump the minor version when
you publish a new version of your crate -- bumping the version of the `embedded-hal` dependency is a
breaking change (drivers that depend on `embedded-hal` v0.1.0 can't be used with HAL implementation
crates that depend on `embedded-hal` v0.2.0).

## What does this all mean for you?

To those of you who have been doing embedded development on nightly: things will get *much easier*
from now on. We have reduced the number of unstable features in core crates of the Cortex-M
ecosystem to **zero**. Although you will have to continue to use nightly for application development
you can expect zero breakage from these crates when updating the nightly compiler. There is one
expected breakage coming soon though: `panic_fmt` will be removed as announced above. This will
break the [panic handler crates][phc]; however, the breakage will be isolated to those crates and
the fix will consist of simply updating the dependency version.

[phc]: https://crates.io/keywords/panic-impl

To those of you who have been meaning to dive into embedded Rust development: we'll soon be done
with our "embedded Rust on stable" tasks and we'll move our focus to documenting the embedded
development process, tooling and ecosystem. The [embedded Rust book][book] will become the resource
to get started on embedded Rust, but it doesn't quite exist right now.

[book]: https://github.com/rust-lang-nursery/embedded-wg/blob/master/books/embedded-rust-book/README.md

## What about architectures other than ARM Cortex-M?

The path carved for ARM Cortex-M can be followed by the other architectures (ARM Cortex-R, AVR,
MSP430, RISCV, etc.). Each architecture presents its own extra set of challenges though:

- MSP430 being the second oldest embedded / `no_std` target is the closest one to make it to stable
(as a tier 2 target) by the edition release. The main blocker is that `extern "msp430-interrupt"`
is not available on stable but I think that may be possible to work around using external C /
assembly files + FFI.

- Both AVR and RISCV are blocked from being included in the Rust compiler due to either the
immaturity of the LLVM backend or LLVM backend bugs. Not many (embedded) Rust developers can also
hack LLVM backends so we are short handed on the AVR front; OTOH, the RISCV is being actively
developed by third parties so it's probably just a matter of time before we add it to rustc.

- ARM Cortex-R LLVM backend is probably in good shape due to the similarities between its
instruction set and the ARM Cortex-M instruction set, so adding the target to the compiler should
be straightforward. However, the crate ecosystem is nonexistent at this point so there's a lot of
work to be done on that front.

---

This work is part of the [embedded WG][ewg] effort towards [making embedded development possible on
the stable channel][stable]. (We are almost done! :tada:)

[ewg]: https://github.com/rust-lang-nursery/embedded-wg
[stable]: https://github.com/rust-lang-nursery/embedded-wg