Book: Section 1: Introduction (draft)

[japaric]

From @jamesmunns on July 10, 2018 9:19

This issue tracks discussion around the Introduction Section of the book. This includes introducing concepts, obtaining and setting up hardware, and verifying a setup before starting the book.

Copied from original issue: rust-embedded/wg#116

[japaric]

Triage: The skeleton is in place but the following sections need to be completed or updated:

NOTE: follow the link to see what needs to be done

• The "Verify installation" section. This is empty. What parts of the Discovery counterpart need to copied over?

• The "tooling" section

• The "no_std" section

• The "Who Embedded Rust is for" section is empty. (But the answer is "everyone", right?)

• The "installation" section will need to be updated to not reference arm-none-eabi-gcc after [RFC] [breaking-change] change the default linker of the thumbv*m-none-eabi* targets wg#160 is implemented.

[Nicoretti]

Hi @japaric (just saw your tweet "Help Wanted") I would like to help on this issue, I'm not sure if i would be able to cover all of the open points but I am confident I'll be able to write something about:

• The "no_std"
• The "Who Embedded Rust is for" section
• parts of the "Tooling" section

Do you need some help on this, if so what's the process to contribute? (PR?)

[japaric]

@Nicoretti

Do you need some help on this, if so what's the process to contribute? (PR?)

Yes, definitively! The process is to send a PR updating the file then the resources team will review it.

[therealprof]

@Nicoretti Did you plan to write more about those topics? @jamesmunns and or me would be happy to review and mentor if needed.

[Nicoretti]

@therealprof yes I did plan to at least update/merge the things @japaric mentioned into the "no_std" section and I also planed to write something for the Tooling section. Just not sure if I can do any/too much writing before the 09.09. (writing turned out to be much harder for me than I thought)

About the The "Who Embedded Rust is for" section, it is a bit unclear to me what the (major) differences to Who This book is For should be -> They seem very similar to me.

[therealprof]

@Nicoretti That is fine, we're happy to take any work you can put into it.

About the The "Who Embedded Rust is for" section, it is a bit unclear to me what the (major) differences to Who This book is For should be -> They seem very similar to me.

My straw man answer would be: Embedded Rust is for everyone who wants to do efficient high level programming for embedded devices with the same promises as on regular systems. This book is meant to guide newcomers to develop with Rust for embedded devices, i.e. the target audience is people with embedded but no Rust experience as well as the other way around and of course also just the curious... It might also be good to look at the other available resources (e.g. the Embedonomicon (the tricky bits for the advanced folks) and discovery (a tutorial for a specific hardware) to determine who's not audience for this book.

[Nicoretti]

@therealprof thx for the input -> makes sense to me. I'll started to work on the update for the no_std part @japaric suggested, I'll plan to create a pull request for feedback tomorrow.

[jamesmunns]

Regarding "Who Embedded Rust is For", here's a comment I left on another PR:

As for context, I was borrowing from the Embedded Rust Book Introduction, and I am okay to just remove it.

That being said, I do like what @therealprof said above.

[Nicoretti]

@jamesmunns I see I'll try to put this (or something like this) into the section. By now I worked a bit writing something for the tooling section but, I just saw that you and @japaric already put something into place (so ill drop that). Still I pushed what I have drafted so far to my fork in case you wanna have a look.
If you think there are a few bits which still make sense to or work into the current master let me know.

[Nicoretti]

@jamesmunns and @therealprof I took some time thinking and drafting

For now I came to the conclusion that straw man of @therealprof splits up into two main messages/parts:

Embedded Rust is for everyone who wants to do efficient high level programming for embedded devices with the same promises as on regular systems.

This is more or less the Who Embedded Rust is for part, which might could be rewritten to something like:
Embedded rust is for everyone who wants to do embedded programming backed by the higher-level concepts and safety guarantees the rust language provides.
-> Also a reference to Who Rust Is For could be added here.

This book is meant to guide newcomers to develop with Rust for embedded devices, i.e. the target audience is people with embedded but no Rust experience as well as the other way around and of course also just the curious... It might also be good to look at the other available resources (e.g. the Embedonomicon (the tricky bits for the advanced folks) and discovery (a tutorial for a specific hardware) to determine who's not audience for this book.

I think this pieces belong mainly in the Who This Book Is For part. We could do a slight rewrite here though, so it will sound a bit more inclusive, but still states which people most likely will benefit the most by reading this book.

E.g. starting with something like this:

Who This Book is For

This book caters towards people with either a solid embedded background or a solid rust background These people most likely will get out the most out of this book, still we assume everybody courious about embedded rust programming will get something out of this book.

Depending on your background you might also wanna check out this resources:

• Embedonomicon
• Discovery
• Rust Book
  ...

@therealprof @jamesmunns what do you think?

[japaric]

Pending items:

• Update version information in the installation page to Rust 1.31.

[japaric]

Update version information in the installation page to Rust 1.31.

PR #74 covers this. Closing as done.