Merge #71: Add "alloc" feature

85caa28 Add CI test.sh script (Tobin C. Harding)
1ceb828 Add no-allocator crate (Tobin C. Harding)
8f27962 Add "alloc" feature (Tobin C. Harding)
33bad4c Move embedded to sub-dir with-allocator (Tobin C. Harding)

Pull request description:

  We would like users to be able to use parts of this library in a `no_std` environment without an allocator. To achieve this add an "alloc" feature and feature gate any code that requires allocation behind.

  To test the new feature gating works, and catch regressions, add a crate that uses `bech32` as a dependency with no default features and forces a `no_std` build. (Does not test any code just imports the lib to verify it builds.)

  Patch 3 can be moved before patch 2 to verify that the crate does not currently build without an allocator.

  Patch 4 adds a minimal `contrib/test.sh` script.

ACKs for top commit:
  apoelstra:
    ACK 85caa28

Tree-SHA512: ee1507d08dca79ddee07e6b7188c8f707d0c0dd1aaf778f3d5b376fa5ba99358260ed034efce852366e794843737757589564cbf65fa3e2560ff73559baa06d2

Author: apoelstra

.github/workflows/rust.yml

@@ -3,7 +3,7 @@ on: [pull_request]
 name: Continuous Integration
 
 jobs:
-  test:
+  Test:
     name: Test Suite
     runs-on: ubuntu-latest
     strategy:
@@ -13,16 +13,17 @@ jobs:
           - stable
           - nightly
     steps:
+      - name: Checkout Crate
       - uses: actions/checkout@v2
+      - name: Checkout Toolchain
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
           toolchain: ${{ matrix.rust }}
           override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: test
-          args: --verbose --features strict
+      - name: Run Test Script
+        env: ${{ matrix.rust }}
+        run: ./contrib/test.sh
 
   fmt:
     name: Rustfmt
@@ -60,7 +61,8 @@ jobs:
           command: clippy
           args: -- -D warnings
 
-  Embedded:
+  EmbeddedWithAlloc:
+    name: no_std with alloc
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -79,4 +81,20 @@ jobs:
         env:
           RUSTFLAGS: "-C link-arg=-Tlink.x"
           CARGO_TARGET_THUMBV7M_NONE_EABI_RUNNER: "qemu-system-arm -cpu cortex-m3 -machine mps2-an385 -nographic -semihosting-config enable=on,target=native -kernel"
-        run: cd embedded && cargo run --target thumbv7m-none-eabi
+        run: cd embedded/with-allocator && cargo run --target thumbv7m-none-eabi
+
+  EmbeddedNoAlloc:
+    name: no_std no alloc
+    runs-on: ubuntu-latest
+    strategy:
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: rustc
+          args: -- -C link-arg=-nostartfiles

.gitignore

@@ -2,5 +2,7 @@
 *.o
 /Cargo.lock
 
-/embedded/Cargo.lock
-/embedded/.cargo
+/embedded/no-allocator/Cargo.lock
+/embedded/no-allocator/.cargo
+/embedded/with-allocator/Cargo.lock
+/embedded/with-allocator/.cargo

Cargo.toml

@@ -13,7 +13,9 @@ edition = "2018"
 
 [features]
 default = ["std"]
-std = []
+std = ["alloc"]
+alloc = []
+
 # Only for CI to make all warnings errors, do not activate otherwise (may break forward compatibility)
 strict = []
 

contrib/test.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+#
+# CI test script for rust-bech32.
+#
+# The "strict" feature is used to configure cargo to deny all warnings, always use it in test runs.
+
+set -ex
+
+# Sanity, check tools exist.
+cargo --version
+rustc --version
+
+# Check without features ("strict" is a CI feature only, see above).
+cargo build --no-default-features --features="strict"
+cargo test --no-default-features --features="strict"
+
+# Check "std" feature (implies "alloc").
+cargo build --no-default-features --features="strict std"
+cargo test --no-default-features --features="strict std"
+
+# Check "alloc" feature alone.
+cargo build --no-default-features --features="strict alloc"
+cargo test --no-default-features --features="strict alloc"
+
+exit 0

embedded/no-allocator/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+authors = ["Tobin C. Harding <[email protected]>"]
+edition = "2018"
+readme = "README.md"
+name = "no-allocator"
+version = "0.1.0"
+
+[profile.dev]
+panic = "abort"
+
+[profile.release]
+panic = "abort"
+
+[dependencies]
+bech32 = { path = "../../", default_features = false }

embedded/no-allocator/README.md

@@ -0,0 +1,10 @@
+# no_std test crate without an allocator
+
+This crate is based on the blog post found at:
+
+ https://blog.dbrgn.ch/2019/12/24/testing-for-no-std-compatibility/
+
+Its purpose is to test that the `rust-bech32` library can be built in a `no_std` environment without
+a global allocator.
+
+Build with: `cargo rustc -- -C link-arg=-nostartfiles`.

embedded/no-allocator/src/main.rs

@@ -0,0 +1,26 @@
+//! Test `no_std` build of `bech32`.
+//!
+//! Build with: `cargo rustc -- -C link-arg=-nostartfiles`.
+//!
+
+#![no_std]
+#![no_main]
+
+use core::panic::PanicInfo;
+
+// Note: `#[global_allocator]` is NOT set.
+
+#[allow(unused_imports)]
+use bech32;
+
+/// This function is called on panic, defining this ensures build will fail if `std` is enabled
+/// because `panic` will be defined twice.
+#[panic_handler]
+fn panic(_info: &PanicInfo) -> ! {
+    loop {}
+}
+
+#[no_mangle]
+pub extern "C" fn _start() -> ! {
+    loop {}
+}

embedded/Cargo.toml embedded/with-allocator/Cargo.toml

@@ -2,7 +2,7 @@
 authors = ["Riccardo Casatta <[email protected]>"]
 edition = "2018"
 readme = "README.md"
-name = "embedded"
+name = "with-allocator"
 version = "0.1.0"
 
 [dependencies]
@@ -11,10 +11,10 @@ cortex-m-rt = "0.6.10"
 cortex-m-semihosting = "0.3.3"
 panic-halt = "0.2.0"
 alloc-cortex-m = "0.4.1"
-bech32 = { path="../", default-features = false }
+bech32 = { path="../../", default-features = false }
 
 [[bin]]
-name = "embedded"
+name = "with-allocator"
 test = false
 bench = false
 

embedded/memory.x embedded/with-allocator/memory.x

@@ -57,19 +57,21 @@ assert_eq!(variant, Variant::Bech32);
 #![cfg_attr(feature = "strict", deny(warnings))]
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
 
-#[cfg(all(not(feature = "std"), not(test)))]
+#[cfg(feature = "alloc")]
 extern crate alloc;
 
 #[cfg(any(test, feature = "std"))]
 extern crate core;
 
-#[cfg(all(not(feature = "std"), not(test)))]
+#[cfg(all(feature = "alloc", not(feature = "std")))]
 use alloc::borrow::Cow;
-#[cfg(all(not(feature = "std"), not(test)))]
+#[cfg(all(feature = "alloc", not(feature = "std")))]
 use alloc::{string::String, vec::Vec};
-use core::convert::{Infallible, TryFrom};
+#[cfg(feature = "alloc")]
+use core::convert::Infallible;
+use core::convert::TryFrom;
 use core::{fmt, mem};
-#[cfg(any(feature = "std", test))]
+#[cfg(feature = "std")]
 use std::borrow::Cow;
 
 /// Integer in the range `0..32`
@@ -220,6 +222,7 @@ pub trait FromBase32: Sized {
     fn from_base32(b32: &[u5]) -> Result<Self, Self::Err>;
 }
 
+#[cfg(feature = "alloc")]
 impl WriteBase32 for Vec<u5> {
     type Err = Infallible;
 
@@ -234,6 +237,7 @@ impl WriteBase32 for Vec<u5> {
     }
 }
 
+#[cfg(feature = "alloc")]
 impl FromBase32 for Vec<u8> {
     type Err = Error;
 
@@ -243,6 +247,7 @@ impl FromBase32 for Vec<u8> {
 }
 
 /// A trait for converting a value to a type `T` that represents a `u5` slice.
+#[cfg(feature = "alloc")]
 pub trait ToBase32 {
     /// Convert `Self` to base32 vector
     fn to_base32(&self) -> Vec<u5> {
@@ -257,11 +262,13 @@ pub trait ToBase32 {
 }
 
 /// Interface to calculate the length of the base32 representation before actually serializing
+#[cfg(feature = "alloc")]
 pub trait Base32Len: ToBase32 {
     /// Calculate the base32 serialized length
     fn base32_len(&self) -> usize;
 }
 
+#[cfg(feature = "alloc")]
 impl<T: AsRef<[u8]>> ToBase32 for T {
     fn write_base32<W: WriteBase32>(&self, writer: &mut W) -> Result<(), <W as WriteBase32>::Err> {
         // Amount of bits left over from last round, stored in buffer.
@@ -306,6 +313,7 @@ impl<T: AsRef<[u8]>> ToBase32 for T {
     }
 }
 
+#[cfg(feature = "alloc")]
 impl<T: AsRef<[u8]>> Base32Len for T {
     fn base32_len(&self) -> usize {
         let bits = self.as_ref().len() * 8;
@@ -327,6 +335,7 @@ pub trait CheckBase32<T: AsRef<[u5]>> {
     fn check_base32(self) -> Result<T, Self::Err>;
 }
 
+#[cfg(feature = "alloc")]
 impl<T: AsRef<[u8]>> CheckBase32<Vec<u5>> for T {
     type Err = Error;
 
@@ -336,6 +345,7 @@ impl<T: AsRef<[u8]>> CheckBase32<Vec<u5>> for T {
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
+#[cfg(feature = "alloc")]
 enum Case {
     Upper,
     Lower,
@@ -348,6 +358,7 @@ enum Case {
 /// * **MixedCase**: If the HRP contains both uppercase and lowercase characters.
 /// * **InvalidChar**: If the HRP contains any non-ASCII characters (outside 33..=126).
 /// * **InvalidLength**: If the HRP is outside 1..83 characters long.
+#[cfg(feature = "alloc")]
 fn check_hrp(hrp: &str) -> Result<Case, Error> {
     if hrp.is_empty() || hrp.len() > 83 {
         return Err(Error::InvalidLength);
@@ -387,6 +398,7 @@ fn check_hrp(hrp: &str) -> Result<Case, Error> {
 /// * If [check_hrp] returns an error for the given HRP.
 /// # Deviations from standard
 /// * No length limits are enforced for the data part
+#[cfg(feature = "alloc")]
 pub fn encode_to_fmt<T: AsRef<[u5]>>(
     fmt: &mut fmt::Write,
     hrp: &str,
@@ -416,6 +428,7 @@ pub fn encode_to_fmt<T: AsRef<[u5]>>(
 /// * If [check_hrp] returns an error for the given HRP.
 /// # Deviations from standard
 /// * No length limits are enforced for the data part
+#[cfg(feature = "alloc")]
 pub fn encode_without_checksum_to_fmt<T: AsRef<[u5]>>(
     fmt: &mut fmt::Write,
     hrp: &str,
@@ -454,6 +467,7 @@ const BECH32M_CONST: u32 = 0x2bc8_30a3;
 
 impl Variant {
     // Produce the variant based on the remainder of the polymod operation
+    #[cfg(feature = "alloc")]
     fn from_remainder(c: u32) -> Option<Self> {
         match c {
             BECH32_CONST => Some(Variant::Bech32),
@@ -476,6 +490,7 @@ impl Variant {
 /// * If [check_hrp] returns an error for the given HRP.
 /// # Deviations from standard
 /// * No length limits are enforced for the data part
+#[cfg(feature = "alloc")]
 pub fn encode<T: AsRef<[u5]>>(hrp: &str, data: T, variant: Variant) -> Result<String, Error> {
     let mut buf = String::new();
     encode_to_fmt(&mut buf, hrp, data, variant)?.unwrap();
@@ -488,6 +503,7 @@ pub fn encode<T: AsRef<[u5]>>(hrp: &str, data: T, variant: Variant) -> Result<St
 /// * If [check_hrp] returns an error for the given HRP.
 /// # Deviations from standard
 /// * No length limits are enforced for the data part
+#[cfg(feature = "alloc")]
 pub fn encode_without_checksum<T: AsRef<[u5]>>(hrp: &str, data: T) -> Result<String, Error> {
     let mut buf = String::new();
     encode_without_checksum_to_fmt(&mut buf, hrp, data)?.unwrap();
@@ -497,6 +513,7 @@ pub fn encode_without_checksum<T: AsRef<[u5]>>(hrp: &str, data: T) -> Result<Str
 /// Decode a bech32 string into the raw HRP and the data bytes.
 ///
 /// Returns the HRP in lowercase, the data with the checksum removed, and the encoding.
+#[cfg(feature = "alloc")]
 pub fn decode(s: &str) -> Result<(String, Vec<u5>, Variant), Error> {
     let (hrp_lower, mut data) = split_and_decode(s)?;
     if data.len() < CHECKSUM_LENGTH {
@@ -518,9 +535,11 @@ pub fn decode(s: &str) -> Result<(String, Vec<u5>, Variant), Error> {
 /// Decode a bech32 string into the raw HRP and the data bytes, assuming no checksum.
 ///
 /// Returns the HRP in lowercase and the data.
+#[cfg(feature = "alloc")]
 pub fn decode_without_checksum(s: &str) -> Result<(String, Vec<u5>), Error> { split_and_decode(s) }
 
 /// Decode a bech32 string into the raw HRP and the `u5` data.
+#[cfg(feature = "alloc")]
 fn split_and_decode(s: &str) -> Result<(String, Vec<u5>), Error> {
     // Split at separator and check for two pieces
     let (raw_hrp, raw_data) = match s.rfind(SEP) {
@@ -577,12 +596,14 @@ fn split_and_decode(s: &str) -> Result<(String, Vec<u5>), Error> {
     Ok((hrp_lower, data))
 }
 
+#[cfg(feature = "alloc")]
 fn verify_checksum(hrp: &[u8], data: &[u5]) -> Option<Variant> {
     let mut exp = hrp_expand(hrp);
     exp.extend_from_slice(data);
     Variant::from_remainder(polymod(&exp))
 }
 
+#[cfg(feature = "alloc")]
 fn hrp_expand(hrp: &[u8]) -> Vec<u5> {
     let mut v: Vec<u5> = Vec::new();
     for b in hrp {
@@ -595,6 +616,7 @@ fn hrp_expand(hrp: &[u8]) -> Vec<u5> {
     v
 }
 
+#[cfg(feature = "alloc")]
 fn polymod(values: &[u5]) -> u32 {
     let mut chk: u32 = 1;
     let mut b: u8;
@@ -623,6 +645,7 @@ const CHARSET: [char; 32] = [
 ];
 
 /// Reverse character set. Maps ASCII byte -> CHARSET index on [0,31]
+#[cfg(feature = "alloc")]
 const CHARSET_REV: [i8; 128] = [
     -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
     -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
@@ -697,6 +720,7 @@ impl std::error::Error for Error {
 /// let base5 = convert_bits(&[0xff], 8, 5, true);
 /// assert_eq!(base5.unwrap(), vec![0x1f, 0x1c]);
 /// ```
+#[cfg(feature = "alloc")]
 pub fn convert_bits<T>(data: &[T], from: u32, to: u32, pad: bool) -> Result<Vec<u8>, Error>
 where
     T: Into<u8> + Copy,
@@ -732,6 +756,7 @@ where
 }
 
 #[cfg(test)]
+#[cfg(feature = "alloc")] // Note, all the unit tests currently require an allocator.
 mod tests {
     use super::*;