[RFC] move to cargo-generate; start with QEMU #45
Conversation
|
Overall this LGTM, good update! But I have one small nitpick. |
|
@japaric Sounds good to me, I like it. |
|
@sekineh hey. I just want to inform you that I'll be adding a section about running bare metal programs with QEMU to the embedded book based on what I've written in this PR. I know you have been working with QEMU recently so I'm letting you know in case you want to, at any time, share with us any cool tricks you have learned or give feedback on the text. I'll be including the |
|
The latest commit upgrades all the examples to Rust 2018 and moves out the text to the book. See rust-embedded/book#20 |
| entry!(main); | ||
| use cortex_m_rt::entry; | ||
| use cortex_m_semihosting::hio::{self, HStdout}; | ||
| use stm32f30x::{interrupt, Interrupt}; |
There was a problem hiding this comment.
I would prefer if we could turn the device specific use lines into generic ones and define the crates to be used in the end in src/lib.rs, aliasing the device specific peripheral registers and HAL to device and hal respectively so (in Rust 2018) those would then read
use crate::device::<whatever>;
use crate::hal::<whatever>;
instead in the examples. This makes it a lot easier to try them on different devices.
There was a problem hiding this comment.
I don’t think example programs should depend on src/lib.rs of this crate.
Users typically use examples in their own crates. In that case, they can’t touch src/lib.rs of cortex-m-rt (Edited).
In other words, I expect I can do the following thing:
- copy one of the examples into their own main.rs.
- edit cargo.toml .
- build successfully
Adding one indirection of ‘use’ clauses will do harm in this use case.
There was a problem hiding this comment.
I don't quite see your point here I'm afraid. That's exactly what I would hope to enable by generally using universal names instead of calling device specific crates because those are the ones that one always has to change in each source file. If you want to use an example in your own crate you just have to alias the correct crates in your src/lib.rs and if the hardware is similar enough it will just run.
|
Question: Should we remove all the non-essential files from this repository? That is LICENSE-*, the ci directory, etc. Right now these would appear in projects made using Given that the bulk of the documentation will be in the book; this seems fine to me. Thoughts? |
book.rust-embedded.org is pointing to an old version
|
@japaric +1 |
|
I have minified the repo and bumped the dependencies. Since there's no clear ETA for the beta I would suggest landing this now. The text has been updated to note that the beta is not out yet. As there's no .travis.yml anymore I have modified the branch protection to not require bors. One of you will still have to approve this PR before it can be merged (just press the green merge button afterwards). |
I was going to propose moving to cargo-generate now by having the default
values work for the LM3S6965 microcontroller which QEMU supports and also to
update the documentation to start out with QEMU but while implementing this it
occurred to me that this documentation (see README.md) may be a better fit for
the embedded book and should be there instead of here. Which begs the question
what should the documentation of this template consist of?
thoughts? ^ @rust-embedded/resources @rust-embedded/cortex-m
Oh, and the rationale for starting with QEMU is that (a) way more people will be
able to try it out as it doesn't require hardware; (b) there's less chance of
things going wrong because there are no device specific steps, there are no
permissions to fiddle with (see OpenOCD on Linux), etc.; and (c) we don't expose
new users to so many new concepts at once (cross compiling and debugging vs that
plus "what is OpenOCD even doing?", "what is this interface/*.cfg file?", etc).
Basically, newcomers will have an easier time all around. The downside is that
there would be a new dependency to install: QEMU.