rust VS snapbox

For what it's worth, this is the script I'm using to build for our platform: build.ps1 / build.sh

Note that before I got the target triple upstream, I had to provide my own target json file. That's here: https://github.com/betrusted-io/rust/blob/1.53.0-xous/riscv32imac-unknown-xous-elf.json and you can adapt it as necessary. Simply creating the file in the correct path is enough. This is the code that does that: https://github.com/betrusted-io/rust/blob/e39344c5473d49a0cb4d45de119ad23713a00ed4/rebuild.ps1#L65

Everything you need to know to build for our platform is at https://github.com/betrusted-io/rust/ and maybe the scripts or patches there will be interesting to you.

Rust does use a Rust port of dlmalloc on platforms that don't provide malloc() and free(). We did port this to Xous, but ran into a feature bug that caused locking to be disabled. That was the source of weird and subtle bugs, which is how he discovered that fact about allocators.

This is correct.

When you tell someone to install Rust, they go to rustup.rs and install the latest version. Therefore, we need to have a libstd port for the latest version. Which effectively means we need to release libstd as soon as possible after the compiler is released. Our `sys` directory is at https://github.com/betrusted-io/rust/tree/1.61.0-xous/librar... and isn't too complicated. It's about 50 patches that need to be carried forward every six weeks.

Fortunately libstd doesn't change too much, at leaset not the parts we need. And I can usually pre-port the patches by applying them to `beta`, which means the patches against the release version usually apply cleanly.

It's still better than requiring nightly, which has absolutely no stability guarantees. By targeting stable, we don't run into issues of bitrot where we accidentally rely on features that have been removed. Rather than adjusting every service in the operating system, we just need to port one library: libstd

I've considered trying to upstream these, but I'm not sure how the rust team would feel about it.

If needed, here is an example of per-word diffing and highlighting of trailing newline differences.

I see. I would try writing the same name as in your Cargo.toml. For example, if yours was toml [package] name = "caesor_cipher" I would try bin.name = "caesor_cipher" It seems that trycmd might ignore a test if the bin.name field is incorrect: https://github.com/assert-rs/trycmd/issues/105

I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and tutorial documentation are a weak point.

For examples, its improving with the example scraping work (e.g. https://docs.rs/clap/latest/clap/struct.ArgMatches.html#meth...) but testing of example is still lacking. I've written trycmd to help (https://github.com/assert-rs/trycmd).

For derive reference and tutorial documentation, your choices are

- A very long, hard to navigate top-level documentation, see https://docs.rs/structopt/latest/structopt/

- External documentation, see https://serde.rs/

- Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head)

For clap, my documentation examples are best served as programs and we've had a problem with these being broken. The Rust CLI book has a decent strategy for this by pulling in code from external files (https://rust-cli.github.io/book/index.html). I was tempted to do that for clap where example code and output (all verified via trycmd) are pulled into an mdbook site but I've stopped short and just have a README that links out to everything (https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.

Another problem we found in clap was it was easy for our examples to build but harder to make sure they worked. This is why I wrote trycmd (example "tests").

Would love feedback on on some of the known questions or whatever else is on your mind!

The design is inspired by trybuild with thought given to how mdBook books could pull in content so you can verify a code sample, the command for running it, and the output. In considering how to keep clap's website up-to-date, I had this idea and threw it together to see how well it works. Overall, seems good with room for improvement. I'll have to give this a try on a real world program soon.