Write 0.8 upgrading guide (and maybe write a `cargo fix`-like tool)

[joshlf]

Progress

• Write upgrading guide
• (optional) Write upgrading tool
  • Commit example zerocopy project along with CI test that tests the upgrade tool (this will help us keep the tool up-to-date as we make further API tweaks)

Details

As described in #1288 (comment), and in my own personal experience upgrading the version of zerocopy vendored in Fuchsia, upgrading from 0.7 to 0.8 creates a large amount of churn. This falls into a few primary buckets:

• Many APIs now require Immutable and/or KnownLayout
• #[derive(FromZeroes, FromBytes)] now breaks, and needs to be replaced with just #[derive(FromBytes)]
• FromZeroes and AsBytes have been renamed to FromZeros and IntoBytes, respectively
• Many methods have been deprecated and need to be replaced by calls to different methods
• The return type of fallible methods has gone from Option to Result
• Some APIs that previously required B: ByteSlice now require B: SplitByteSlice

Upgrading guide

We should at a minimum write a detailed upgrading guide that explains what changes will need to be made, and what compiler errors to expect.

We may also want to include a note about the byteorder feature being removed.

Upgrade tool

We may also want to write a cargo fix-like tool that performs some of the upgrade automatically, as much of this can be done mechanically. In particular, the following set of transformations would result in code which is nearly semantically identical under 0.8:

• Rename FromZeroes and AsBytes to FromZeros and IntoBytes
• Everywhere FromZeros, FromBytes, or AsBytes is used (especially in derives and in trait bounds), add Immutable and KnownLayout as well
• Everywhere both FromZeros and FromBytes are derived, remove FromZeros
• Replace calls to deprecated methods with calls to their replacements
• Add .ok() to most FromBytes methods and Ref constructors
• Replace ByteSlice with SplitByteSlice in trait bounds

Some of these could be done with a relatively low false positive rate just using standard unix shell tools. Some of them would be better served by a more powerful tool that can parse Rust code and resolve item paths (e.g., detecting whether a use of Ref::new refers to zerocopy::Ref or some other Ref).

A few suggestions from this thread:

• ast-grep
  • Here's an example of rewriting a #[derive]
• "If you do not mind changing the formatting, you may use the syn crate with the visitor feature to browse and edit the code, then prettyplease to get a readable output."
• Write a rustc-driver plugin
• rust-analyzer search and replace
• gritql
• VSCode refactoring action

[joshlf]

I'm going to use this comment to draft the upgrading guide.

Zerocopy 0.7 -> 0.8 Upgrading Guide

Thank you for using zerocopy! Our new 0.8 release includes a number of changes which are backwards-incompatible with 0.7. This guide describes these changes and gives advice for how to make the upgrade process as painless as possible.

For large codebases, it may help to automate some of these upgrading steps using a tool such as ast-grep.

Implied derives

The FromBytes trait is a sub-trait of FromZeros. On 0.7, in order to derive FromBytes, you also had to derive FromZeros explicitly:

#[derive(FromZeros, FromBytes)]
struct Foo { ... }

On 0.8, deriving a trait automatically derives its super-traits. This code will now fail to compile since the FromBytes derive will emit an impl of FromZeros, which will conflict with the impl derived by the explicit FromZeros derive. Instead, simply write:

#[derive(FromBytes)]
struct Foo { ... }

New names

The AsBytes trait has been renamed to IntoBytes. The FromZeroes trait has been renamed to FromZeros.

A number of Ref, FromBytes, and IntoBytes methods have been renamed or deprecated in favor of a more general method. The old methods are preserved and marked as #[doc(hidden)] #[deprecated], including a deprecation message that indicates which API should be preferred in 0.8. We recommend using these compilation warnings as a guide for how to upgrade individual call sites. As they are #[doc(hidden)], we do not consider these methods subject to semver guarantees, and they may be removed or re-used in any future 0.8 version.

New traits

FromBytes and IntoBytes

Some properties that were previously required by FromBytes or IntoBytes (previously AsBytes) have now been split into separate traits. APIs that still require those properties now add bounds on these new traits.

The new traits in question are KnownLayout, which encodes certain layout information about a type, and Immutable, which indicates that a type does not contain any UnsafeCells.

We recommend that you simply derive KnownLayout and Immutable on any type with existing zerocopy trait derives. Alternatively, for a more fine-grained approach, use compilation errors as a guide to which types should derive these traits.

ByteSlice

The ByteSlice trait now supports byte slices which cannot be cheaply split in two. The new SplitByteSlice trait extends ByteSlice with this behavior. In 0.8, SplitByteSlice is analogous to what ByteSlice was in 0.7. The same holds for ByteSliceMut and SplitByteSliceMut.

If you don't care about maximum flexibility, we recommend simply replacing all instances of ByteSlice[Mut] with SplitByteSlice[Mut]. Alternatively, if you wish to support ByteSlice[Mut] types which cannot be split, use compilation errors as a guide to where you need to add SplitByteSlice[Mut] bounds.

New return values

Many methods that previously returned Option now return Result, and include a finer-grained error type. If you wish to preserve the 0.7 behavior and minimize the code change needed to upgrade, simply add .ok() to these call sites in order to convert Results back into Options. However, we recommend that most code should try to migrate to the new error types eventually, as they will help you ensure that you're only handling errors that you expect. For example, having to handle an AlignmentError where you don't expect it is an indication that you could use a different API that guarantees freedom from alignment errors (e.g. one of the Ref methods with unaligned in the method name).

Miscellaneous

The byteorder feature has been removed; in 0.8, the byteorder module is always present, and is not optional.

[joshlf]

Upgrading guide is published in our release announcement. We won't write an upgrading tool.