Merge #394

394: Split nb and can traits to separate crates. r=eldruin a=Dirbaio

Following up from #177 (comment), this PR splits `nb` and `can` traits to separate crates.

I propose keeping these crates (and `embedded-hal-async`) separate forever. (instead of merging EHA into EH when stable as we originally planned when we created EHA).

Reasons for splitting `nb`:
- its future is unclear. Some people who would like to see `nb` deprecated. By splitting, if we do deprecate it, we won't get stuck with it in the main `embedded-hal` crate forever.
- It makes the module paths in the main crate cleaner.
- Traits tied to a particular "execution model" in their own crates, which make the overall structure easier to understand IMO.

Reasons for splitting `can`:
- It has some open concerns: #381 #387 
- Even if we do solve these, it's nice to have separate crates for the "more specialized" traits so that they can be major-bumped in the future if more concerns arise, without having to major-bump the main `embedded-hal` crate.

TODO:

- [x] Name it `embedded-can`, not `embedded-hal-can`.
- [x] Move/remove docs/examples from the main crate that mention `nb`.
- [x] Mention the subcrates from the main crate's docs.
- [x] Add CI
- [x] move `embedded-hal` to a subdir as well
- [x] What should the nb, can crate versions be? 1.0? (no opinion on this from me).
   - [x] can: 0.4
   - [x] nb: 1.0

Co-authored-by: Dario Nieuwenhuis <[email protected]>

Author: bors[bot]

.github/bors.toml

@@ -2,11 +2,15 @@ block_labels = ["needs-decision"]
 delete_merged_branches = true
 required_approvals = 1
 status = [
-  "ci-linux (stable, x86_64-unknown-linux-gnu)",
-  "ci-linux (stable, thumbv6m-none-eabi)",
-  "ci-linux (stable, thumbv7m-none-eabi)",
-  "ci-linux (1.54.0, x86_64-unknown-linux-gnu)",
-  "ci-linux-test (stable)",
-  "ci-linux-test (1.54.0, x86_64-unknown-linux-gnu)",
+  "test (stable, x86_64-unknown-linux-gnu)",
+  "test (stable, thumbv6m-none-eabi)",
+  "test (stable, thumbv7m-none-eabi)",
+  "test (1.54.0, x86_64-unknown-linux-gnu)",
+  "test (1.54.0, thumbv6m-none-eabi)",
+  "test (1.54.0, thumbv7m-none-eabi)",
+  "test (nightly, x86_64-unknown-linux-gnu)",
+  "test (nightly, thumbv6m-none-eabi)",
+  "test (nightly, thumbv7m-none-eabi)",
+  "clippy",
   "fmt",
 ]

.github/workflows/changelog.yml

@@ -5,14 +5,16 @@ on:
 
 name: Clippy check
 jobs:
-  clippy_check:
+  clippy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: stable
+          # embedded-hal-async needs nightly.
+          # Use a pinned version to avoid spontaneous breakages (new clippy lints are added often)
+          toolchain: nightly-2022-09-05  
           override: true
           components: clippy
       - uses: actions-rs/clippy-check@v1

.github/workflows/ci-async.yml

@@ -16,9 +16,4 @@ jobs:
           toolchain: nightly
           override: true
           components: rustfmt
-      - uses: actions-rs/cargo@v1
-        with:
-          command: fmt
-          args: --all -- --check
-      - run: cargo fmt --all -- --check
-        working-directory: embedded-hal-async
+      - run: cargo fmt --check

.github/workflows/ci-bus.yml

@@ -3,35 +3,41 @@ on:
     branches: [ staging, trying, master ]
   pull_request:
 
-name: Test Suite
+name: Continuous integration
 
 env:
   RUSTFLAGS: '--deny warnings'
 
 jobs:
-  ci-linux-test:
+  test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        rust: [stable]
+        # All generated code should be running on stable now
+        rust:
+          - stable
+          - 1.54.0  # MSRV
+          - nightly
 
-        include:
-          - rust: 1.54.0
-            TARGET: x86_64-unknown-linux-gnu
-
-          # Test nightly but don't fail
-          - rust: nightly
-            experimental: true
-            TARGET: x86_64-unknown-linux-gnu
+        # The default target we're compiling on and for
+        target:
+          - x86_64-unknown-linux-gnu
+          - thumbv6m-none-eabi
+          - thumbv7m-none-eabi
 
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
           toolchain: ${{ matrix.rust }}
-          target: ${{ matrix.TARGET }}
+          target: ${{ matrix.target }}
           override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: test
+
+      - run: sed -i '/nightly-only/d' Cargo.toml 
+        if: matrix.toolchain != 'nightly'
+
+      - run: cargo check --target=${{ matrix.target }}
+
+      - run: cargo test --target=${{ matrix.target }}
+        if: contains(matrix.target, 'linux')

.github/workflows/ci.yml

@@ -1,23 +1,10 @@
-[package]
-authors = [
-  "The Embedded HAL Team <[email protected]>",
-  "Jorge Aparicio <[email protected]>",
-  "Jonathan 'theJPster' Pallant <[email protected]>"
-]
-categories = ["asynchronous", "embedded", "hardware-support", "no-std"]
-description = " A Hardware Abstraction Layer (HAL) for embedded systems "
-documentation = "https://docs.rs/embedded-hal"
-edition = "2018"
-keywords = ["hal", "IO"]
-license = "MIT OR Apache-2.0"
-name = "embedded-hal"
-readme = "README.md"
-repository = "https://github.com/rust-embedded/embedded-hal"
-version = "1.0.0-alpha.8"
-
-[dependencies]
-nb = "1"
+[workspace]
 
-[dev-dependencies.stm32f1]
-version = "0.14"
-features = ["stm32f103", "rt"]
+# CI removes lines containing 'nightly-only' when not building with nightly.
+members = [
+    "embedded-hal",
+    "embedded-hal-async",  # nightly-only
+    "embedded-hal-nb",
+    "embedded-hal-bus",
+    "embedded-can",
+]

.github/workflows/clippy-async.yml

@@ -1,17 +1,8 @@
-[![crates.io](https://img.shields.io/crates/d/embedded-hal.svg)](https://crates.io/crates/embedded-hal)
-[![crates.io](https://img.shields.io/crates/v/embedded-hal.svg)](https://crates.io/crates/embedded-hal)
-[![Documentation](https://docs.rs/embedded-hal/badge.svg)](https://docs.rs/embedded-hal)
-![Minimum Supported Rust Version](https://img.shields.io/badge/rustc-1.54+-blue.svg)
-
 # `embedded-hal`
 
 >  A Hardware Abstraction Layer (HAL) for embedded systems
 
-This project is developed and maintained by the [HAL team][team].
-
-## [API reference]
-
-[API reference]: https://docs.rs/embedded-hal
+This project is developed and maintained by the [HAL team][https://github.com/rust-embedded/wg#the-hal-team].
 
 ## Scope
 
@@ -26,14 +17,24 @@ platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux,
 The advantage for application developers is that by adopting `embedded-hal` they can unlock all
 these drivers for their platform.
 
-`embedded-hal` is not tied to a specific execution model like blocking or non-blocking.
-
 For functionality that goes beyond what is provided by `embedded-hal`, users are encouraged
 to use the target platform directly. Abstractions of common functionality can be proposed to be
 included into `embedded-hal` as described [in this guide](docs/how-to-add-a-new-trait.md), though.
 
 See more about the design goals in [this documentation section](https://docs.rs/embedded-hal/latest/embedded_hal/#design-goals).
 
+## Crates
+
+The main  `embedded-hal` project is not tied to a specific execution model like blocking or non-blocking.
+
+| Crate | crates.io | Docs | |
+|-|-|-|-|
+| [embedded-hal](./embedded-hal)       | [![crates.io](https://img.shields.io/crates/v/embedded-hal.svg)](https://crates.io/crates/embedded-hal) | [![Documentation](https://docs.rs/embedded-hal/badge.svg)](https://docs.rs/embedded-hal) | Core traits, blocking version |
+| [embedded-hal-async](./embedded-hal-async) | [![crates.io](https://img.shields.io/crates/v/embedded-hal-async.svg)](https://crates.io/crates/embedded-hal-async) | [![Documentation](https://docs.rs/embedded-hal-async/badge.svg)](https://docs.rs/embedded-hal-async) | Core traits, async version |
+| [embedded-hal-nb](./embedded-hal-nb)    | [![crates.io](https://img.shields.io/crates/v/embedded-hal-nb.svg)](https://crates.io/crates/embedded-hal-nb) | [![Documentation](https://docs.rs/embedded-hal-nb/badge.svg)](https://docs.rs/embedded-hal-nb) | Core traits, polling version using the `nb` crate |
+| [embedded-hal-bus](./embedded-hal-bus)   | [![crates.io](https://img.shields.io/crates/v/embedded-hal-bus.svg)](https://crates.io/crates/embedded-hal-bus) | [![Documentation](https://docs.rs/embedded-hal-bus/badge.svg)](https://docs.rs/embedded-hal-bus) | Utilities for sharing SPI and I2C buses |
+| [embedded-can](./embedded-can)       | [![crates.io](https://img.shields.io/crates/v/embedded-can.svg)](https://crates.io/crates/embedded-can) | [![Documentation](https://docs.rs/embedded-can/badge.svg)](https://docs.rs/embedded-can) | Controller Area Network (CAN) traits |
+
 ## Releases
 
 At the moment we are working towards a `1.0.0` release (see [#177]). During this process we will
@@ -94,9 +95,6 @@ dual licensed as above, without any additional terms or conditions.
 
 ## Code of Conduct
 
-Contribution to this crate is organized under the terms of the [Rust Code of
-Conduct][CoC], the maintainer of this crate, the [HAL team][team], promises
+Contribution to this repository is organized under the terms of the [Rust Code of
+Conduct](CODE_OF_CONDUCT.md), the maintainers of this repository, the [HAL team](https://github.com/rust-embedded/wg#the-hal-team), promise
 to intervene to uphold that code of conduct.
-
-[CoC]: CODE_OF_CONDUCT.md
-[team]: https://github.com/rust-embedded/wg#the-hal-team

.github/workflows/clippy-bus.yml

@@ -0,0 +1,16 @@
+[package]
+name = "embedded-can"
+version = "0.4.0"
+edition = "2018"
+
+description = "HAL traits for Controller Area Network (CAN) devices."
+categories = ["embedded", "hardware-support", "no-std"]
+documentation = "https://docs.rs/embedded-can"
+keywords = ["hal", "IO"]
+license = "MIT OR Apache-2.0"
+readme = "README.md"
+repository = "https://github.com/rust-embedded/embedded-hal"
+
+[dependencies]
+embedded-hal = { version = "=1.0.0-alpha.8", path = "../embedded-hal" }
+nb = "1"