[unsafe-fields] Initial commit

Makes progress on #1931

gherrit-pr-id: If0e198c377137dd941ebd5dc68787766a593e1eb

.github/workflows/ci.yml

@@ -507,6 +507,73 @@ jobs:
           # `roll-pinned-toolchain-versions.yml`.
           kani-version: 0.55.0
 
+  unsafe_fields:
+    runs-on: ubuntu-latest
+    needs: generate_cache
+    strategy:
+      # By default, this is set to `true`, which means that a single CI job
+      # failure will cause all outstanding jobs to be canceled. This slows down
+      # development because it means that errors need to be encountered and
+      # fixed one at a time.
+      fail-fast: false
+      matrix:
+        toolchain: [
+          "msrv",
+          "stable",
+          "nightly",
+        ]
+    steps:
+      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+      - name: Configure environment variables
+        run: |
+          set -eo pipefail
+          ZC_TOOLCHAIN="$(./cargo.sh --version ${{ matrix.toolchain }})"
+          RUSTFLAGS="$RUSTFLAGS $ZC_NIGHTLY_RUSTFLAGS"
+          echo "RUSTFLAGS=$RUSTFLAGS" >> $GITHUB_ENV
+          echo "ZC_TOOLCHAIN=$ZC_TOOLCHAIN" >> $GITHUB_ENV
+      - name: Install stable Rust for use in 'cargo.sh'
+        uses: dtolnay/rust-toolchain@00b49be78f40fba4e87296b2ead62868750bdd83 # stable
+        with:
+          toolchain: stable
+      - name: Install Rust with nightly toolchain (${{ env.ZC_TOOLCHAIN }}) and target aarch64_be-unknown-linux-gnu
+        uses: dtolnay/rust-toolchain@00b49be78f40fba4e87296b2ead62868750bdd83 # stable
+        with:
+          toolchain: ${{ env.ZC_TOOLCHAIN }}
+          components: clippy, rust-src
+      - name: Check
+        run: ./cargo.sh +${{ matrix.toolchain }} check --package unsafe-fields --verbose
+      - name: Check tests
+        run: ./cargo.sh +${{ matrix.toolchain }} check --tests --package unsafe-fields --verbose
+      - name: Build
+        run: ./cargo.sh +${{ matrix.toolchain }} build --package unsafe-fields --verbose
+      - name: Run tests
+        run: ./cargo.sh +${{ matrix.toolchain }} test --package unsafe-fields --verbose
+      - name: Clippy
+        run: ./cargo.sh +${{ matrix.toolchain }} clippy --package unsafe-fields --verbose
+      - name: Clippy tests
+        run: ./cargo.sh +${{ matrix.toolchain }} clippy --package unsafe-fields --tests --verbose
+        # Clippy improves the accuracy of lints over time, and fixes bugs. Only
+        # running Clippy on nightly allows us to avoid having to write code
+        # which is compatible with older versions of Clippy, which sometimes
+        # requires hacks to work around limitations that are fixed in more
+        # recent versions.
+        if: matrix.toolchain == 'nightly'
+      - name: Cargo doc
+        # We pass --document-private-items and --document-hidden items to ensure
+        # that documentation always builds even for these items. This makes
+        # future changes to make those items public/non-hidden more painless.
+        # Note that --document-hidden-items is unstable; if a future release
+        # breaks or removes it, we can just update CI to no longer pass that
+        # flag.
+        run: |
+          # Include arguments passed during docs.rs deployments to make sure those
+          # work properly.
+          set -eo pipefail
+          METADATA_DOCS_RS_RUSTDOC_ARGS="$(cargo metadata --format-version 1 | \
+            jq -r ".packages[] | select(.name == \"unsafe-fields\").metadata.docs.rs.\"rustdoc-args\"[]" | tr '\n' ' ')"
+          export RUSTDOCFLAGS="${{ matrix.toolchain == 'nightly' && '-Z unstable-options --document-hidden-items $METADATA_DOCS_RS_RUSTDOC_ARGS'|| '' }} $RUSTDOCFLAGS"
+          ./cargo.sh +${{ matrix.toolchain }} doc --document-private-items --package unsafe-fields
+
   # NEON intrinsics are currently broken on big-endian platforms. [1] This test ensures
   # that we don't accidentally attempt to compile these intrinsics on such platforms. We
   # can't use this as part of the build matrix because rustup doesn't support the
@@ -670,7 +737,7 @@ jobs:
       # https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks#handling-skipped-but-required-checks
       if: failure()
       runs-on: ubuntu-latest
-      needs: [build_test, kani,check_be_aarch64 , check_fmt, check_readme, check_versions, generate_cache, check-all-toolchains-tested, check-job-dependencies, run-git-hooks]
+      needs: [build_test, kani,check_be_aarch64, check_fmt, check_readme, check_versions, generate_cache, check-all-toolchains-tested, check-job-dependencies, run-git-hooks, unsafe_fields]
       steps:
         - name: Mark the job as failed
           run: exit 1

Cargo.toml

@@ -12,6 +12,10 @@
 # https://github.com/dtolnay/trybuild/issues/207#issuecomment-131227.594
 [workspace]
 
+[workspace.package]
+# Inherited by zerocopy and unsafe-fields.
+rust-version = "1.65.0"
+
 [package]
 edition = "2021"
 name = "zerocopy"
@@ -22,7 +26,7 @@ categories = ["embedded", "encoding", "no-std::no-alloc", "parsing", "rust-patte
 keywords = ["cast", "convert", "transmute", "transmutation", "type-punning"]
 license = "BSD-2-Clause OR Apache-2.0 OR MIT"
 repository = "https://github.com/google/zerocopy"
-rust-version = "1.65.0"
+rust-version = { workspace = true }
 
 exclude = [".*"]
 
@@ -81,6 +85,7 @@ testutil = { path = "testutil" }
 # sometimes change the output format slightly, so a version mismatch can cause
 # CI test failures.
 trybuild = { version = "=1.0.90", features = ["diff"] }
+unsafe-fields = { path = "./unsafe-fields" }
 # In tests, unlike in production, zerocopy-derive is not optional
 zerocopy-derive = { version = "=0.9.0-alpha.0", path = "zerocopy-derive" }
 # TODO(#381) Remove this dependency once we have our own layout gadgets.

unsafe-fields/Cargo.toml

@@ -0,0 +1,21 @@
+# Copyright 2024 The Fuchsia Authors
+#
+# Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
+# <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
+# license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
+# This file may not be copied, modified, or distributed except according to
+# those terms.
+
+[package]
+name = "unsafe-fields"
+version = "0.1.0"
+edition = "2021"
+license = "BSD-2-Clause OR Apache-2.0 OR MIT"
+repository = "https://github.com/google/zerocopy"
+rust-version = { workspace = true }
+
+exclude = [".*"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "doc_cfg", "--generate-link-to-definition"]

unsafe-fields/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-APACHE

unsafe-fields/LICENSE-BSD

@@ -0,0 +1 @@
+../LICENSE-BSD

unsafe-fields/LICENSE-MIT

@@ -0,0 +1 @@
+../LICENSE-MIT