From 1e648bbc1f796f2ef554255cf977d8d6870da7f9 Mon Sep 17 00:00:00 2001 From: Peter Kehl Date: Sun, 14 Aug 2022 08:00:22 -0700 Subject: [PATCH] Split pages --- README.md | 118 +++++++++++++++++++++++++---------- README_BUILDS_AND_TESTING.md | 8 +-- README_MORE_RESOURCES.md | 3 - 3 files changed, 88 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 733a9bb..4cec489 100644 --- a/README.md +++ b/README.md @@ -174,13 +174,13 @@ https://github.com/hakimel/reveal.js/issues/118. --> --- # Audience and purpose - * help general Rust developers move to low level - * help non-Rust low level developers move to Rust + * general Rust developers moving to low level + * non-Rust low level developers moving to Rust # In scope * Rust only; focusing on the language (less so on development tools) * [`no_std`](https://docs.rust-embedded.org/book/intro/no-std.html) library - `crates` (without `std` library), _with_ or _without heap_ + `crates` (without `std` library), _with_ or _without_ heap --- # Related, but mostly out of scope * hardware, deployment, embedded debugging @@ -204,6 +204,9 @@ https://github.com/hakimel/reveal.js/issues/118. Bounds](https://doc.rust-lang.org/nightly/nomicon/hrtb.html). * [`async/await` in no_std](https://ferrous-systems.com/blog/stable-async-on-embedded) + +--- + * [`unsafe` code](https://doc.rust-lang.org/nightly/book/ch19-01-unsafe-rust.html) * is... unsafe, indeed. Especially so in `std`, because some mistakes are @@ -239,16 +242,20 @@ https://github.com/hakimel/reveal.js/issues/118. * [Rust](https://doc.rust-lang.org) and [Cargo & dependencies](https://doc.rust-lang.org/nightly/cargo/reference/specifying-dependencies.html) in general - +--- # Limited scope * cross-platform * also for `std` (where `std` library exists) * Cargo documentation keeps this [quite hidden](https://doc.rust-lang.org/nightly/cargo/faq.html#does-cargo-handle-multi-platform-packages-or-cross-compilation) * [`.cargo/config.toml` --> - `build.target`](https://doc.rust-lang.org/nightly/cargo/reference/config.html#buildtarget) - (for an example, see TODO slicing-rs), or - * [`cargo build + `build.target`](https://doc.rust-lang.org/nightly/cargo/reference/config.html#buildtarget), + for example: + ``` + [build] + target = "aarch64-unknown-none-softfloat" + ``` + * or: [`cargo build --target`](https://doc.rust-lang.org/nightly/cargo/commands/cargo-build.html#compilation-options) * Architectures supported by Rust - in [three tiers](https://doc.rust-lang.org/nightly/rustc/target-tier-policy.html). @@ -279,8 +286,8 @@ https://github.com/hakimel/reveal.js/issues/118. --- # Prerequisites * no need for low level experience - * common (and a few uncommon) aspects of general (not necessarily low level) - Rust, especially + * common (and a few uncommon) aspects of general (but not necessarily low + level) Rust, especially * setting up a project and basics of [cargo](https://doc.rust-lang.org/nightly/book/ch01-03-hello-cargo.html) * [package @@ -297,10 +304,15 @@ https://github.com/hakimel/reveal.js/issues/118. - not as simple as Java/C++ enums, but potentially carrying variant-specific data field(s) (like Scala's and Haskell's algebraic types) * [iterators](https://doc.rust-lang.org/nightly/book/ch13-02-iterators.html) - (or [C# - iterators](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/iterators) + (like [C# + iterators](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/iterators), or - [java.util.stream.Stream](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/stream/Stream.html) + [java.util.stream.Stream](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/stream/Stream.html); + but not like + [java.util.Iterator](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Iterator.html)!) + +--- + * [generics](https://doc.rust-lang.org/nightly/book/ch10-00-generics.html) and especially [generic data types](https://doc.rust-lang.org/nightly/book/ch10-01-syntax.html). (Like @@ -317,6 +329,10 @@ https://github.com/hakimel/reveal.js/issues/118. (See also [Vancouver Rust's presentation](https://github.com/vancouver-rs/talks/tree/master/const-generics).) * anything in this document starting with "_New to Rust?_" + * optional (for deeper understanding of some code examples): + [core::option](https://doc.rust-lang.org/nightly/core/option/index.html) + and + [core::result](https://doc.rust-lang.org/nightly/core/result/index.html) * experience with a statically typed and compiled language * basics of linking, heap and stack * Rust @@ -424,6 +440,8 @@ https://github.com/hakimel/reveal.js/issues/118. See also the [Rust RFC book](https://rust-lang.github.io/rfcs). +--- + # no_std with heap * Import `core::` and `alloc::` (instead of `std::`) wherever you can - even in `std` development. That brings awareness about what parts of your library are @@ -467,28 +485,31 @@ https://github.com/hakimel/reveal.js/issues/118. * use slices (instead of arrays) as parameter types wherever possible * design function as accepting (shared or mutable) slices * functions may need to write to mutable slice parameters (instead of - returning). That may sound less "functional". _New to Rust?_ . But in - Rust any mutated parameters must be declared so. Any parameter that may - be modified must be either - * [`borrowed`](https://doc.rust-lang.org/nightly/book/ch04-02-references-and-borrowing.html) - (passed) as a mutable reference or slice (which has exclusive access), - or - * passing ownership of the object: - * [_"move"-d_](https://doc.rust-lang.org/nightly/book/ch04-01-what-is-ownership.html#ownership-and-functions) - (or - [`clone()`-d](https://doc.rust-lang.org/core/clone/trait.Clone.html) - first and then the clone is moved), or - * [_copied_: Ownership > Stack-Only Data: Copy] - ](https://doc.rust-lang.org/nightly/book/ch04-01-what-is-ownership.html#stack-only-data-copy) - if it implements [`Copy` - ](https://doc.rust-lang.org/core/marker/trait.Copy.html) trait. _New - to Rust?_ A `trait` is similar to an `interface` in Java, or a - virtual abstract field-less class with virtual methods in C++. - * See also - [ownership](https://doc.rust-lang.org/nightly/book/ch04-00-understanding-ownership.html), - [borrowing](https://doc.rust-lang.org/nightly/book/ch04-02-references-and-borrowing.html) - and - [lifetimes](https://doc.rust-lang.org/nightly/book/ch10-03-lifetime-syntax.html). + returning). + +--- + + * _New to Rust?_ Mutating slices or references/arrays may sound less + "functional". But, in Rust any mutated parameters must be declared so. Any + parameter that may be modified must be either + * [`borrowed`](https://doc.rust-lang.org/nightly/book/ch04-02-references-and-borrowing.html) + (passed) as a mutable reference or slice (which has exclusive access), or + * passing ownership of the object: + * [_"move"-d_](https://doc.rust-lang.org/nightly/book/ch04-01-what-is-ownership.html#ownership-and-functions) + (or + [`clone()`-d](https://doc.rust-lang.org/core/clone/trait.Clone.html) + first and then the clone is moved), or + * [_copied_: Ownership > Stack-Only Data: Copy] + ](https://doc.rust-lang.org/nightly/book/ch04-01-what-is-ownership.html#stack-only-data-copy) + if it implements [`Copy` + ](https://doc.rust-lang.org/core/marker/trait.Copy.html) trait. _New to + Rust?_ A `trait` is similar to an `interface` in Java, or a virtual + abstract field-less class with virtual methods in C++. + * See also + [ownership](https://doc.rust-lang.org/nightly/book/ch04-00-understanding-ownership.html), + [borrowing](https://doc.rust-lang.org/nightly/book/ch04-02-references-and-borrowing.html) + and + [lifetimes](https://doc.rust-lang.org/nightly/book/ch10-03-lifetime-syntax.html). * alternatively, use [`const` generics](https://rust-lang.github.io/rfcs/2000-const-generics.html), a subset of Rust @@ -503,6 +524,9 @@ https://github.com/hakimel/reveal.js/issues/118. array-containing structs/enums, on stack. Then they call the processing functions with slices, or with const generic-sized arrays (or their references) + +--- + * this way you can re-use the same processing functions * if you can process the incoming data last in, first out (in LIFO/stack order), you could recurse (possibly batching the data in an array at every @@ -519,4 +543,30 @@ https://github.com/hakimel/reveal.js/issues/118. [`impl`](https://doc.rust-lang.org/nightly/book/ch10-02-traits.html#returning-types-that-implement-traits) to define types like `impl Iterator`. --- +# no_std without heap > collect() alternatives +When developing for `no_heap`, we can't `collect()` from iterators. That makes +some tasks that need access to all items at the same time (like sorting) very +difficult. + +This would need limit on number of items to be known at build time. Then the +caller would pass a (mutable) reference to an array, or a slice, where we would +manually collect the items (in a `for` loop, or `.foreach()` closure). + +--- + # no_std without heap > Compound iterators +For some purposes we may not need access to all items if we +don't need to access the whole collection. Then all we do needs sequential access +only, for example a one-to-one transformation, and/or filtering. + +For that we may need to implement a compound iterator. It would contain an +underlying iterator (or several iterators) over the source data. It iterates and +transforms and/or filters the source data. + +[Exercism Rust track](https://exercism.org/tracks/rust/exercises) > +[RNA +Transcription](https://exercism.org/tracks/rust/exercises/rna-transcription) + +https://github.com/peter-kehl/x-rust/blob/main/rust/rna-transcription-std/src/lib.rs + +https://github.com/peter-kehl/x-rust/blob/main/rust/rna-transcription/src/lib.rs diff --git a/README_BUILDS_AND_TESTING.md b/README_BUILDS_AND_TESTING.md index db8b707..79f2e09 100644 --- a/README_BUILDS_AND_TESTING.md +++ b/README_BUILDS_AND_TESTING.md @@ -8,16 +8,16 @@ for the whole presentation. # no_std-friendly builds and testing (on desktop) * no simple way to run/debug `no_std` on desktop * workaround: separate build verification and testing - * build for a `no_std` target (but don't test) - * build `no_std` and `no_std` + `no_std_heap` features (on your desktop) and - run their tests + * build for a `no_std` target (but can't test, not even build the tests) + * build `no_std` and `no_std` (and optionally `no_std_heap`) features (for + your desktop's target), and run their tests * build `std` and run all tests * can't use a [workspace](https://doc.rust-lang.org/nightly/cargo/reference/workspaces.html) for these alternatives (because all crates in workspace share dependency resolution) * have the above builds in separate crates, under a directory like - `test_crates/` + [`test_crates/`](https://github.com/ranging-rs/slicing-rs/tree/main/test_crates) * test crates can re-use the tests * suggest their folder names to start with a prefix based on/equal to the main crate. That makes navigation easier (especially in VS Code) when you diff --git a/README_MORE_RESOURCES.md b/README_MORE_RESOURCES.md index 7271e8e..8015365 100644 --- a/README_MORE_RESOURCES.md +++ b/README_MORE_RESOURCES.md @@ -92,9 +92,6 @@ for the whole presentation. Linux-based", hence `std` * [rustc book](https://forge.rust-lang.org) > [Platform support (and tiers)](https://forge.rust-lang.org/release/platform-support.html) - -bufgo - ---