Skip to content

Commit

Permalink
Update README, docs, and manifest
Browse files Browse the repository at this point in the history
  • Loading branch information
@djkoloski
djkoloski committed Aug 11, 2024
1 parent d37319e commit 4b78d87
Show file tree
Hide file tree
Showing 6 changed files with 135 additions and 126 deletions.
21 changes: 12 additions & 9 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,19 +11,22 @@ version = "0.8.0-alpha.9"
authors = ["David Koloski <djkoloski@gmail.com>"]
edition = "2021"
license = "MIT"
documentation = "https://docs.rs/bytecheck"
readme = "README.md"
repository = "https://github.com/rkyv/bytecheck"
keywords = ["no_std", "validation", "serialization"]
categories = ["encoding", "no-std", "no-std::no-alloc"]

[workspace.dependencies]
bytecheck = { version = "0.8.0-alpha.9", path = "bytecheck", default-features = false }
bytecheck_derive = { version = "0.8.0-alpha.9", path = "bytecheck_derive", default-features = false }
proc-macro2 = { version = "1.0", default-features = false }
ptr_meta = { version = "0.3.0-alpha.2", default-features = false }
rancor = { version = "0.1.0-alpha.9", default-features = false }
bytecheck = { version = "=0.8.0-alpha.9", path = "bytecheck", default-features = false }
bytecheck_derive = { version = "=0.8.0-alpha.9", path = "bytecheck_derive", default-features = false }
proc-macro2 = { version = "1", default-features = false }
ptr_meta = { version = "=0.3.0-alpha.3", default-features = false }
rancor = { version = "=0.1.0-alpha.9", default-features = false }
simdutf8 = { version = "0.1", default-features = false }
syn = { version = "2.0", features = ["full"] }
uuid = { version = "1.4", default-features = false }
quote = { version = "1.0", default-features = false }
syn = { version = "2", default-features = false }
uuid = { version = "1", default-features = false }
quote = { version = "1", default-features = false }

[patch.crates-io]
ptr_meta = { git = "https://github.com/rkyv/ptr_meta" }
rancor = { git = "https://github.com/rkyv/rancor" }
22 changes: 16 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,23 @@
# bytecheck &emsp; [![Latest Version]][crates.io] [![License]][license path]
# `bytecheck`

[Latest Version]: https://img.shields.io/crates/v/bytecheck.svg
[![crates.io badge]][crates.io] [![docs badge]][docs] [![license badge]][license]

[crates.io badge]: https://img.shields.io/crates/v/bytecheck.svg
[crates.io]: https://crates.io/crates/bytecheck
[License]: https://img.shields.io/badge/license-MIT-blue.svg
[license path]: https://github.com/djkoloski/bytecheck/blob/master/LICENSE
[docs badge]: https://img.shields.io/docsrs/bytecheck
[docs]: https://docs.rs/bytecheck
[license badge]: https://img.shields.io/badge/license-MIT-blue.svg
[license]: https://github.com/rkyv/bytecheck/blob/master/LICENSE

bytecheck is a memory validation framework for Rust.

## Documentation

bytecheck is a type validation framework for Rust.
- [bytecheck](https://docs.rs/bytecheck), a memory validation framework for Rust
- [bytecheck_derive](https://docs.rs/bytecheck_derive), the derive macro for
bytecheck

## bytecheck in action
## Example

```rust
use bytecheck::{CheckBytes, check_bytes, rancor::Failure};
Expand Down
14 changes: 8 additions & 6 deletions bytecheck/Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
[package]
name = "bytecheck"
description = "Derive macro for bytecheck"
documentation = "https://docs.rs/bytecheck"
keywords = ["bytecheck", "validation", "zero-copy", "rkyv"]
categories = ["encoding"]
description = "Memory validation framework for Rust"
version.workspace = true
edition.workspace = true
authors.workspace = true
edition.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
keywords.workspace = true
categories.workspace = true
documentation = "https://docs.rs/bytecheck"

[dependencies]
bytecheck_derive = { workspace = true, default-features = false }
Expand All @@ -27,5 +28,6 @@ simdutf8 = { workspace = true, optional = true }
uuid = { workspace = true, optional = true }

[features]
default = ["simdutf8", "std"]
default = ["derive", "simdutf8", "std"]
derive = []
std = ["ptr_meta/std", "rancor/std", "simdutf8?/std", "uuid?/std"]
77 changes: 77 additions & 0 deletions bytecheck/example.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
```rust
use bytecheck::{CheckBytes, check_bytes, rancor::Failure};

#[derive(CheckBytes, Debug)]
#[repr(C)]
struct Test {
a: u32,
b: char,
c: bool,
}

#[repr(C, align(4))]
struct Aligned<const N: usize>([u8; N]);

macro_rules! bytes {
($($byte:literal,)*) => {
(&Aligned([$($byte,)*]).0 as &[u8]).as_ptr()
};
($($byte:literal),*) => {
bytes!($($byte,)*)
};
}

// In this example, the architecture is assumed to be little-endian
#[cfg(target_endian = "little")]
unsafe {
// These are valid bytes for a `Test`
check_bytes::<Test, Failure>(
bytes![
0u8, 0u8, 0u8, 0u8,
0x78u8, 0u8, 0u8, 0u8,
1u8, 255u8, 255u8, 255u8,
].cast()
).unwrap();

// Changing the bytes for the u32 is OK, any bytes are a valid u32
check_bytes::<Test, Failure>(
bytes![
42u8, 16u8, 20u8, 3u8,
0x78u8, 0u8, 0u8, 0u8,
1u8, 255u8, 255u8, 255u8,
].cast()
).unwrap();

// Characters outside the valid ranges are invalid
check_bytes::<Test, Failure>(
bytes![
0u8, 0u8, 0u8, 0u8,
0x00u8, 0xd8u8, 0u8, 0u8,
1u8, 255u8, 255u8, 255u8,
].cast()
).unwrap_err();
check_bytes::<Test, Failure>(
bytes![
0u8, 0u8, 0u8, 0u8,
0x00u8, 0x00u8, 0x11u8, 0u8,
1u8, 255u8, 255u8, 255u8,
].cast()
).unwrap_err();

// 0 is a valid boolean value (false) but 2 is not
check_bytes::<Test, Failure>(
bytes![
0u8, 0u8, 0u8, 0u8,
0x78u8, 0u8, 0u8, 0u8,
0u8, 255u8, 255u8, 255u8,
].cast()
).unwrap();
check_bytes::<Test, Failure>(
bytes![
0u8, 0u8, 0u8, 0u8,
0x78u8, 0u8, 0u8, 0u8,
2u8, 255u8, 255u8, 255u8,
].cast()
).unwrap_err();
}
```
118 changes: 16 additions & 102 deletions bytecheck/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! # bytecheck
//!
//! bytecheck is a type validation framework for Rust.
//! bytecheck is a memory validation framework for Rust.
//!
//! For some types, creating an invalid value immediately results in undefined
//! behavior. This can cause some issues when trying to validate potentially
Expand All @@ -23,115 +23,28 @@
//! The layouts of types may change between compiler versions, or even different
//! compilations. To guarantee stable type layout between compilations, structs,
//! enums, and unions can be annotated with `#[repr(C)]`, and enums specifically
//! can be annotated with `#[repr(int)]` or `#[repr(C, int)]` as well.
//!
//! See [the reference's page on type layout][reference] for more details.
//! can be annotated with `#[repr(int)]` or `#[repr(C, int)]` as well. See
//! [the reference's page on type layout][reference] for more details.
//!
//! [reference]: https://doc.rust-lang.org/reference/type-layout.html
//!
//! ## Examples
//!
//! ```
//! use bytecheck::{check_bytes, rancor::Failure, CheckBytes};
//!
//! #[derive(CheckBytes, Debug)]
//! #[repr(C)]
//! struct Test {
//! a: u32,
//! b: char,
//! c: bool,
//! }
//!
//! #[repr(C, align(4))]
//! struct Aligned<const N: usize>([u8; N]);
//!
//! macro_rules! bytes {
//! ($($byte:literal,)*) => {
//! (&Aligned([$($byte,)*]).0 as &[u8]).as_ptr()
//! };
//! ($($byte:literal),*) => {
//! bytes!($($byte,)*)
//! };
//! }
//!
//! // In this example, the architecture is assumed to be little-endian
//! #[cfg(target_endian = "little")]
//! unsafe {
//! // These are valid bytes for a `Test`
//! check_bytes::<Test, Failure>(
//! bytes![
//! 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8, 255u8,
//! 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap();
//!
//! // Changing the bytes for the u32 is OK, any bytes are a valid u32
//! check_bytes::<Test, Failure>(
//! bytes![
//! 42u8, 16u8, 20u8, 3u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8,
//! 255u8, 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap();
//!
//! // Characters outside the valid ranges are invalid
//! check_bytes::<Test, Failure>(
//! bytes![
//! 0u8, 0u8, 0u8, 0u8, 0x00u8, 0xd8u8, 0u8, 0u8, 1u8, 255u8,
//! 255u8, 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap_err();
//! check_bytes::<Test, Failure>(
//! bytes![
//! 0u8, 0u8, 0u8, 0u8, 0x00u8, 0x00u8, 0x11u8, 0u8, 1u8, 255u8,
//! 255u8, 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap_err();
//!
//! // 0 is a valid boolean value (false) but 2 is not
//! check_bytes::<Test, Failure>(
//! bytes![
//! 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 0u8, 255u8, 255u8,
//! 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap();
//! check_bytes::<Test, Failure>(
//! bytes![
//! 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 2u8, 255u8, 255u8,
//! 255u8,
//! ]
//! .cast(),
//! )
//! .unwrap_err();
//! }
//! ```
//!
//! ## Features
//!
//! - `std`: (Enabled by default) Enables standard library support.
//! - `derive`: Re-exports the macros from `bytecheck_derive`. Enabled by
//! default.
//! - `std`: Enables standard library support. Enabled by default.
//! - `simdutf8`: Uses the `simdutf8` crate to validate UTF-8 strings. Enabled
//! by default.
//!
//! ## Crate support
//! ### Crates
//!
//! Some common crates need to be supported by bytecheck before an official
//! integration has been made. Support is provided by bytecheck for these
//! crates, but in the future crates should depend on bytecheck and provide
//! their own implementations. The crates that already have support provided by
//! bytecheck should work toward integrating the implementations into
//! themselves.
//!
//! Crates supported by bytecheck:
//! Bytecheck provides integrations for some common crates by default. In the
//! future, crates should depend on bytecheck and provide their own integration.
//!
//! - [`uuid`](https://docs.rs/uuid)

//!
//! ## Example
#![doc = include_str!("../example.md")]
#![deny(
future_incompatible,
missing_docs,
Expand All @@ -146,6 +59,7 @@
rustdoc::missing_crate_level_docs
)]
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(all(docsrs, not(doctest)), feature(doc_cfg, doc_auto_cfg))]

// Support for various common crates. These are primarily to get users off the
// ground and build some momentum.
Expand Down Expand Up @@ -618,7 +532,7 @@ where
value: *const Self,
context: &mut C,
) -> Result<(), C::Error> {
let (data_address, len) = ptr_meta::PtrExt::to_raw_parts(value);
let (data_address, len) = ptr_meta::to_raw_parts(value);
let base = data_address.cast::<T>();
for index in 0..len {
// SAFETY: The caller has guaranteed that `value` points to enough
Expand Down
9 changes: 6 additions & 3 deletions bytecheck_derive/Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
[package]
name = "bytecheck_derive"
description = "Derive macro for bytecheck"
documentation = "https://docs.rs/bytecheck_derive"
version.workspace = true
edition.workspace = true
authors.workspace = true
edition.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
keywords.workspace = true
categories.workspace = true
documentation = "https://docs.rs/bytecheck_derive"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

Expand All @@ -15,5 +18,5 @@ proc-macro = true

[dependencies]
proc-macro2.workspace = true
syn.workspace = true
syn = { workspace = true, features = ["clone-impls", "derive", "full", "parsing", "printing", "proc-macro"] }
quote.workspace = true

0 comments on commit 4b78d87

Please sign in to comment.