Skip to content

Commit

Permalink
[doc] Render toolchain version detection in rustdoc
Browse files Browse the repository at this point in the history 
Previously, we had avoided doing this because there wasn't any way to
guarantee that we didn't make mistakes and render the wrong version for
a particular named toolchain version.

In this commit, we take the pragmatic approach of renaming the named
toolchain versions - in particular, we add a suffix which includes the
toolchain version. This is fairly error-resistant for two reasons:
- At the definition site (in `Cargo.toml`), the name appears on the same
  line as the version, so mistakes should be obvious
- At the use site (in various `.rs` files), the name appears within a
  few lines of any `#[cfg_attr(doc_cfg, doc(cfg(...)))]` attribute, so
  mistakes should similarly be obvious

Release 0.8.7.

Closes #894

gherrit-pr-id: I74b8e9be0e6cb6e02552d2e1f985b490a7d37afe
  • Loading branch information
@joshlf
joshlf committed Oct 18, 2024
1 parent 40947c6 commit e435ee7
Show file tree
Hide file tree
Showing 10 changed files with 130 additions and 120 deletions.
124 changes: 62 additions & 62 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,12 @@ jobs:
# These are the names of specific Rust versions detected in
# `build.rs`. Each of these represents the minimum Rust version for
# which a particular feature is supported.
"zerocopy-core-error",
"zerocopy-diagnostic-on-unimplemented",
"zerocopy-generic-bounds-in-const-fn",
"zerocopy-target-has-atomics",
"zerocopy-aarch64-simd",
"zerocopy-panic-in-const-and-vec-try-reserve"
"zerocopy-core-error-1-81-0",
"zerocopy-diagnostic-on-unimplemented-1-78-0",
"zerocopy-generic-bounds-in-const-fn-1-61-0",
"zerocopy-target-has-atomics-1-60-0",
"zerocopy-aarch64-simd-1-59-0",
"zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
]
target: [
"i686-unknown-linux-gnu",
Expand Down Expand Up @@ -89,17 +89,17 @@ jobs:
features: "--all-features"
- toolchain: "stable"
features: "--all-features"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
features: "--all-features"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
features: "--all-features"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
features: "--all-features"
- toolchain: "zerocopy-target-has-atomics"
- toolchain: "zerocopy-target-has-atomics-1-60-0"
features: "--all-features"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
features: "--all-features"
- toolchain: "zerocopy-panic-in-const-and-vec-try-reserve"
- toolchain: "zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
features: "--all-features"
# Exclude any combination for the zerocopy-derive crate which
# uses zerocopy features.
Expand All @@ -114,103 +114,103 @@ jobs:
# exist to exercise zerocopy behavior which differs by toolchain;
# zerocopy-derive doesn't behave different on these toolchains.
- crate: "zerocopy-derive"
toolchain: "zerocopy-core-error"
toolchain: "zerocopy-core-error-1-81-0"
- crate: "zerocopy-derive"
toolchain: "zerocopy-diagnostic-on-unimplemented"
toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
- crate: "zerocopy-derive"
toolchain: "zerocopy-generic-bounds-in-const-fn"
toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
- crate: "zerocopy-derive"
toolchain: "zerocopy-target-has-atomics"
toolchain: "zerocopy-target-has-atomics-1-60-0"
- crate: "zerocopy-derive"
toolchain: "zerocopy-aarch64-simd"
toolchain: "zerocopy-aarch64-simd-1-59-0"
- crate: "zerocopy-derive"
toolchain: "zerocopy-panic-in-const-and-vec-try-reserve"
# Exclude non-aarch64 targets from the `zerocopy-aarch64-simd`
toolchain: "zerocopy-panic-in-const-and-vec-try-reserve-1-57-0"
# Exclude non-aarch64 targets from the `zerocopy-aarch64-simd-1-59-0`
# toolchain.
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "i686-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "x86_64-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "arm-unknown-linux-gnueabi"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "powerpc-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "powerpc64-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "riscv64gc-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "s390x-unknown-linux-gnu"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "x86_64-pc-windows-msvc"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "thumbv6m-none-eabi"
- toolchain: "zerocopy-aarch64-simd"
- toolchain: "zerocopy-aarch64-simd-1-59-0"
target: "wasm32-wasi"
# Exclude most targets targets from the `zerocopy-core-error`
# toolchain since the `zerocopy-core-error` feature is unrelated to
# Exclude most targets targets from the `zerocopy-core-error-1-81-0`
# toolchain since the `zerocopy-core-error-1-81-0` feature is unrelated to
# compilation target. This only leaves i686 and x86_64 targets.
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "arm-unknown-linux-gnueabi"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "aarch64-unknown-linux-gnu"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "powerpc-unknown-linux-gnu"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "powerpc64-unknown-linux-gnu"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "riscv64gc-unknown-linux-gnu"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "s390x-unknown-linux-gnu"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "x86_64-pc-windows-msvc"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "thumbv6m-none-eabi"
- toolchain: "zerocopy-core-error"
- toolchain: "zerocopy-core-error-1-81-0"
target: "wasm32-wasi"
# Exclude most targets targets from the
# `zerocopy-diagnostic-on-unimplemented` toolchain since the
# `zerocopy-diagnostic-on-unimplemented` feature is unrelated to
# `zerocopy-diagnostic-on-unimplemented-1-78-0` toolchain since the
# `zerocopy-diagnostic-on-unimplemented-1-78-0` feature is unrelated to
# compilation target. This only leaves i686 and x86_64 targets.
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "arm-unknown-linux-gnueabi"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "aarch64-unknown-linux-gnu"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "powerpc-unknown-linux-gnu"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "powerpc64-unknown-linux-gnu"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "riscv64gc-unknown-linux-gnu"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "s390x-unknown-linux-gnu"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "x86_64-pc-windows-msvc"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "thumbv6m-none-eabi"
- toolchain: "zerocopy-diagnostic-on-unimplemented"
- toolchain: "zerocopy-diagnostic-on-unimplemented-1-78-0"
target: "wasm32-wasi"
# Exclude most targets targets from the
# `zerocopy-generic-bounds-in-const-fn` toolchain since the
# `zerocopy-generic-bounds-in-const-fn` feature is unrelated to
# `zerocopy-generic-bounds-in-const-fn-1-61-0` toolchain since the
# `zerocopy-generic-bounds-in-const-fn-1-61-0` feature is unrelated to
# compilation target. This only leaves i686 and x86_64 targets.
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "arm-unknown-linux-gnueabi"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "aarch64-unknown-linux-gnu"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "powerpc-unknown-linux-gnu"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "powerpc64-unknown-linux-gnu"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "riscv64gc-unknown-linux-gnu"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "s390x-unknown-linux-gnu"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "x86_64-pc-windows-msvc"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "thumbv6m-none-eabi"
- toolchain: "zerocopy-generic-bounds-in-const-fn"
- toolchain: "zerocopy-generic-bounds-in-const-fn-1-61-0"
target: "wasm32-wasi"
# Exclude `thumbv6m-none-eabi` combined with any feature that implies
# the `std` feature since `thumbv6m-none-eabi` does not include a
Expand Down
24 changes: 14 additions & 10 deletions Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
[package]
edition = "2021"
name = "zerocopy"
version = "0.8.6"
version = "0.8.7"
authors = ["Joshua Liebow-Feeser <joshlf@google.com>"]
description = "Zerocopy makes zero-cost memory manipulation effortless. We write \"unsafe\" so you don't have to."
categories = ["embedded", "encoding", "no-std::no-alloc", "parsing", "rust-patterns"]
Expand All @@ -31,27 +31,31 @@ exclude = [".*"]
# which will be emitted if zerocopy is built with a toolchain version at least
# as high as the specified version. In the emitted `--cfg`, dashes are replaced
# by underscores.
#
# Each name is suffixed with the version it corresponds to. This is a convention
# used in the codebase to make it less likely for us to make mistakes when
# writing `doc_cfg` attributes.

# From 1.81.0, Rust supports the `core::error::Error` trait.
zerocopy-core-error = "1.81.0"
zerocopy-core-error-1-81-0 = "1.81.0"

# From 1.78.0, Rust supports the `#[diagnostic::on_unimplemented]` attribute.
zerocopy-diagnostic-on-unimplemented = "1.78.0"
zerocopy-diagnostic-on-unimplemented-1-78-0 = "1.78.0"

# From 1.61.0, Rust supports generic types with trait bounds in `const fn`.
zerocopy-generic-bounds-in-const-fn = "1.61.0"
zerocopy-generic-bounds-in-const-fn-1-61-0 = "1.61.0"

# From 1.60.0, Rust supports `cfg(target_has_atomics)`, which allows us to
# detect whether a target supports particular sets of atomics.
zerocopy-target-has-atomics = "1.60.0"
zerocopy-target-has-atomics-1-60-0 = "1.60.0"

# When the "simd" feature is enabled, include SIMD types from the
# `core::arch::aarch64` module, which was stabilized in 1.59.0. On earlier Rust
# versions, these types require the "simd-nightly" feature.
zerocopy-aarch64-simd = "1.59.0"
zerocopy-aarch64-simd-1-59-0 = "1.59.0"

# Permit panicking in `const fn`s and calling `Vec::try_reserve`.
zerocopy-panic-in-const-and-vec-try-reserve = "1.57.0"
zerocopy-panic-in-const-and-vec-try-reserve-1-57-0 = "1.57.0"

[package.metadata.ci]
# The versions of the stable and nightly compiler toolchains to use in CI.
Expand All @@ -77,13 +81,13 @@ std = ["alloc"]
__internal_use_only_features_that_work_on_stable = ["alloc", "derive", "simd", "std"]

[dependencies]
zerocopy-derive = { version = "=0.8.6", path = "zerocopy-derive", optional = true }
zerocopy-derive = { version = "=0.8.7", path = "zerocopy-derive", optional = true }

# The "associated proc macro pattern" ensures that the versions of zerocopy and
# zerocopy-derive remain equal, even if the 'derive' feature isn't used.
# See: https://github.com/matklad/macro-dep-test
[target.'cfg(any())'.dependencies]
zerocopy-derive = { version = "=0.8.6", path = "zerocopy-derive" }
zerocopy-derive = { version = "=0.8.7", path = "zerocopy-derive" }

[dev-dependencies]
itertools = "0.11"
Expand All @@ -97,6 +101,6 @@ testutil = { path = "testutil" }
# CI test failures.
trybuild = { version = "=1.0.89", features = ["diff"] }
# In tests, unlike in production, zerocopy-derive is not optional
zerocopy-derive = { version = "=0.8.6", path = "zerocopy-derive" }
zerocopy-derive = { version = "=0.8.7", path = "zerocopy-derive" }
# TODO(#381) Remove this dependency once we have our own layout gadgets.
elain = "0.3.0"
16 changes: 10 additions & 6 deletions src/error.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,9 @@ use core::{
ops::Deref,
};

#[cfg(zerocopy_core_error)]
#[cfg(zerocopy_core_error_1_81_0)]
use core::error::Error;
#[cfg(all(not(zerocopy_core_error), any(feature = "std", test)))]
#[cfg(all(not(zerocopy_core_error_1_81_0), any(feature = "std", test)))]
use std::error::Error;

use crate::{util::SendSyncPhantomData, KnownLayout, TryFromBytes, Unaligned};
Expand Down Expand Up @@ -232,7 +232,8 @@ impl<A: fmt::Display, S: fmt::Display, V: fmt::Display> fmt::Display for Convert
}
}

#[cfg(any(zerocopy_core_error, feature = "std", test))]
#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
impl<A, S, V> Error for ConvertError<A, S, V>
where
A: fmt::Display + fmt::Debug,
Expand Down Expand Up @@ -389,7 +390,8 @@ where
}
}

#[cfg(any(zerocopy_core_error, feature = "std", test))]
#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
impl<Src, Dst: ?Sized> Error for AlignmentError<Src, Dst>
where
Src: Deref,
Expand Down Expand Up @@ -534,7 +536,8 @@ where
}
}

#[cfg(any(zerocopy_core_error, feature = "std", test))]
#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
impl<Src, Dst: ?Sized> Error for SizeError<Src, Dst>
where
Src: Deref,
Expand Down Expand Up @@ -641,7 +644,8 @@ where
}
}

#[cfg(any(zerocopy_core_error, feature = "std", test))]
#[cfg(any(zerocopy_core_error_1_81_0, feature = "std", test))]
#[cfg_attr(doc_cfg, doc(cfg(all(rust = "1.81.0", feature = "std"))))]
impl<Src, Dst: ?Sized> Error for ValidityError<Src, Dst>
where
Src: Deref,
Expand Down
8 changes: 5 additions & 3 deletions src/impls.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,7 @@ safety_comment! {
}

#[cfg(all(
zerocopy_target_has_atomics,
zerocopy_target_has_atomics_1_60_0,
any(
target_has_atomic = "8",
target_has_atomic = "16",
Expand All @@ -451,6 +451,7 @@ safety_comment! {
target_has_atomic = "ptr"
)
))]
#[cfg_attr(doc_cfg, doc(cfg(rust = "1.60.0")))]
mod atomics {
use super::*;

Expand Down Expand Up @@ -933,7 +934,8 @@ mod simd {
#[cfg(all(feature = "simd-nightly", target_arch = "powerpc64"))]
powerpc64, powerpc64, vector_bool_long, vector_double, vector_signed_long, vector_unsigned_long
);
#[cfg(zerocopy_aarch64_simd)]
#[cfg(zerocopy_aarch64_simd_1_59_0)]
#[cfg_attr(doc_cfg, doc(cfg(rust = "1.59.0")))]
simd_arch_mod!(
// NOTE(https://github.com/rust-lang/stdarch/issues/1484): NEON intrinsics are currently
// broken on big-endian platforms.
Expand Down Expand Up @@ -1882,7 +1884,7 @@ mod tests {
vector_signed_long,
vector_unsigned_long
);
#[cfg(all(target_arch = "aarch64", zerocopy_aarch64_simd))]
#[cfg(all(target_arch = "aarch64", zerocopy_aarch64_simd_1_59_0))]
#[rustfmt::skip]
test_simd_arch_mod!(
aarch64, float32x2_t, float32x4_t, float64x1_t, float64x2_t, int8x8_t, int8x8x2_t,
Expand Down
2 changes: 1 addition & 1 deletion src/layout.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -880,7 +880,7 @@ mod tests {
layout(size_info, align).validate_cast_and_convert_metadata(addr, bytes_len, cast_type)
}).map_err(|d| {
let msg = d.downcast::<&'static str>().ok().map(|s| *s.as_ref());
assert!(msg.is_some() || cfg!(not(zerocopy_panic_in_const_and_vec_try_reserve)), "non-string panic messages are not permitted when `--cfg zerocopy_panic_in_const_and_vec_try_reserve` is set");
assert!(msg.is_some() || cfg!(not(zerocopy_panic_in_const_and_vec_try_reserve_1_57_0)), "non-string panic messages are not permitted when `--cfg zerocopy_panic_in_const_and_vec_try_reserve` is set");
msg
});
std::panic::set_hook(previous_hook);
Expand Down
Loading

0 comments on commit e435ee7

Please sign in to comment.