1<!-- Copyright 2022 The Fuchsia Authors
2
3Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
4<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
5license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6This file may not be copied, modified, or distributed except according to
7those terms. -->
8
9# Internal details
10
11This file documents various internal details of zerocopy and its infrastructure
12that consumers don't need to be concerned about. It focuses on details that
13affect multiple files, and allows each affected code location to reference this
14document rather than requiring us to repeat the same explanation in multiple
15locations.
16
17## CI and toolchain versions
18
19In CI (`.github/workflows/ci.yml`), we pin to specific versions or dates of the
20stable and nightly toolchains. The reason is twofold: First, our UI tests (see
21`tests/trybuild.rs` and `zerocopy-derive/tests/trybuild.rs`) depend on the
22format of rustc's error messages, and that format can change between toolchain
23versions (we also maintain multiple copies of our UI tests - one for each
24toolchain version pinned in CI - for this reason). Second, not all nightlies
25have a working Miri, so we need to pin to one that does (see
26https://rust-lang.github.io/rustup-components-history/).
27
28Updating the versions pinned in CI may cause the UI tests to break. In order to
29fix UI tests after a version update, run:
30
31```
32$ TRYBUILD=overwrite ./cargo.sh +all test
33```
34
35## Crate versions
36
37We ensure that the crate versions of zerocopy and zerocopy-derive are always the
38same in-tree, and that zerocopy depends upon zerocopy-derive using an exact
39version match to the current version in-tree. This has the result that, even
40when published on crates.io, both crates effectively constitute a single atomic
41version. So long as the code in zerocopy is compatible with the code in
42zerocopy-derive in the same Git commit, then publishing them both is fine. This
43frees us from the normal task of reasoning about compatibility with a range of
44semver-compatible versions of different crates.
45