Just my $0.02; totally agree; a proper guide to linking (specifically the 'right' way to link when you have a crate with external C library dependencies), and interacting directly with ffi (str <--> char * for example) would be extremely useful.
I've been going through the process of doing that stuff the last week or two and there isn't really any good guidance on the topic other than 'don't look at the standard library as an example of how to do it'. ~ Doug. On Tue, Apr 22, 2014 at 7:11 AM, Brian Anderson <[email protected]>wrote: > Hi. > > I've been convinced recently that Rust is missing crucial documentation of > a particular nature: using Rust in practice. I would like to have such a > standalone guide, and these are some ideas about what should be in it. > > This is a guide that runs through creating an entire Rust project from > installation, using the tools, writing code, through deployment, touching > on the practical aspects of coding Rust, not glossing over whatever ugly > bits are necessary to do real work. > > Some of the topics I might expect include: > > * Installation > * Running rustc > * lib.rs/bin.rs/mod.rs conventions > * Evolving a project from a single file to multi-file/mod/directory > * Picking the correct types for various problems > * Obtaining and using other crates > * Setting up a build system (not cargo to start, cargo when it's ready) > * Working with the compiler to find the correct algorithms. Show typical > ways you might concieve the solution incorrectly and how the compiler helps > guide you to the correct one. Particularly re: borrowck. > * Common Rust patterns (like?) > * Rust CI, other community resources? > * Using rust-bindgen to create bindings that don't already exist > * Error handling > * Practical corner cases and workarounds of various types, e.g. > - #[path], #[link_args]? > > There's some overlap here with the current tutorial, which I think is > good, since I want to find new homes for most of the content there. > > I've filed this as issue #13669, but have no plans to work on it > personally at this time. If anybody has an interest in taking it on, please > coordinate there. > > Finally, I'd like to update folks with a few words on how I'm currently > envisioning the Rust documentation story. > > I've become convinced that relatively small and self-contained guides are > our best format for producing standalone documentation about Rust. By being > small, they require minimal investment by any single individual, so we can > experiment quite freely with what docs are provided, what order they are > presented, and the schedule on which they are created. > > Right now I am aiming for three introductory guides, serving distinct > purposes: > > * "A 30-minute intro to Rust" - Very high-level, purely to excited > prospective users, let them know whether Rust is for them > * "The Philosophy of Rust" - Covers about a dozen subjects that are > crucial to understanding why Rust is like it is. It would be impossible to > do anything useful in Rust without understanding this material: stack vs. > heap, ownership, copying, moving, borrowing, lifetimes. Experienced devs > will also pick up a lot of basic syntax in passing. > * "Practical Rust" - Using Rust to build real software. > > After these, a new user should be well on their way to writing Rust, > especially after reading the various other guides on more focused topics. > > "The Philosophy of Rust" is a document that Sam Wright, Niko and I are > working on. The title will almost certainly change. Sam will have a new > pull request up soon. > > As to the existing tutorial, after the new docs mature I expect to demote > it to "The (old) Rust tutorial", then start looking for new homes for the > material there. This won't happen for a while, until the new docs are a > good enough substitute. > > Regards, > Brian > _______________________________________________ > Rust-dev mailing list > [email protected] > https://mail.mozilla.org/listinfo/rust-dev >
_______________________________________________ Rust-dev mailing list [email protected] https://mail.mozilla.org/listinfo/rust-dev
