Skip to content

Latest commit

 

History

History
115 lines (94 loc) · 7 KB

V8.md

File metadata and controls

115 lines (94 loc) · 7 KB

v8

Breaking changes waiting for the next major release. Every published crate shares the 7.x line, and Cargo treats any 7.x as compatible with any other, so anything here would break an adopter's cargo update if it shipped sooner. mise run lint:semver catches the ones that reach a pull request.

When a change can't go out without breaking the public API, ship the part that doesn't break now and add the rest here: what changes, why, and what adopters should do.

Smaller flag and command tables

Binary size work on the oxc CLIs (oxlint and oxfmt) found that the derive-emitted tables are now the largest remaining usage cost: about 22 KB of data plus about 11 KB of relative relocations in oxlint, roughly 550 bytes per flag. They are large because every field is a fat reference or a u64, and each reference needs a relocation in a position-independent binary.

  • What changes: Flag and FlagMeta (and the matching command tables) store offsets into one shared string table, with narrower integers for key, counts and indices, instead of &'static str, &'static [..] and u64 fields.
  • Why it breaks: those fields are public, so changing their types breaks any code that builds or reads a table by hand. Derived code is unaffected.
  • Estimated saving: about 4 KB on oxlint from FlagMeta alone, more once Flag follows.
  • What adopters do: nothing if they use the derives. Hand-written tables regenerate or move to the constructor functions.

Per-flag binding type names

The derive emits a FLAG_<n>_BINDING_TYPE function returning a type name string for every flag, stored in the public Flag::binding_type: Option<BindingType> field. Only derive-generated code reads it: it compares two flags' binding types to decide whether a child command's redeclaration of a global flag is compatible. Parser never reads it.

  • What changes: Flag::binding_type and the BindingType type are removed, saving one function and one string per flag.
  • Open design question: the comparison cannot simply move into the derive's expansion. A parent derive does not see a subcommand's definition or a flattened struct's fields, so it has no types to compare while it expands. The check that replaces it has to run where both flags' types are visible, for example a generated const assertion over an associated item on the value type, and it has to keep today's diagnostic. Until that exists, this item is a candidate, not a plan.
  • Why it breaks: both items are public. Any code that names BindingType or sets or reads Flag::binding_type stops compiling, and a hand-built Flag literal that sets the field does too.
  • What adopters do: a hand-built Flag drops the binding_type field. Whether derive users see any difference depends on the replacement check: it must accept and reject the same redeclarations as today.

Compile-time parser specialization

Parser::with_action_errors carries the default_flag_route and sigil-argument logic that only some CLIs use, roughly 5 KB per binary. Dropping it where unused means making Parser generic over a const set of behaviours that derives choose.

  • What changes: Parser gains const generic parameters.
  • What the defaults keep working: with defaults on the new parameters, Parser<'t, 'a, 'v> written in a type position, a struct field or an impl Trait for Parser<'t, 'a, 'v> that only has to cover the default choices keeps compiling, and values built through Parser::new infer the parameters.
  • What needs new parameters: an impl or function that must accept every choice of the behaviours, rather than only the defaults, has to be generic over the new parameters.
  • Why it breaks anyway: a new generic parameter on a public type is a major change to cargo semver-checks, whatever the defaults preserve.
  • What adopters do: nothing for code that only constructs a Parser and calls next_event, or that names it with the default spelling. Code generic over every choice adds the parameters.

Smaller values moved through the parser and help renderer

Two more public types are larger than they need to be, found by the same size work:

  • Event::ClauseSeparator carries a Clause by value, which makes Event 80 bytes and Result<Option<Event>, Error> larger and costlier to copy on every next_event. Carrying a &Clause shrinks both. Breaking because the variant's payload type is public.
  • help::Style embeds a Palette (four &'static str) and is 72 bytes, copied by value through the help renderer. The palette field is private, so shrinking the embedded copy is not breaking by itself. The public API in the way is Style::palette(self, palette: Palette), which takes a Palette by value. Storing a &'static Palette means taking &'static Palette there, so a caller that builds a custom palette at runtime has to promote it to a static or const (a const works, since Palette's fields are &'static str), or leak it. Palette's own public fields do not change.

The flag table item above also has two specifics: FlagMeta holds 13 bool fields that a u16 bitset would pack (a single byte holds eight), and FlagMeta.accepted_choices and choices overlap. Flag.name is only sometimes redundant: it matches longs[0] for most flags, but the derive keeps explicit names, and for a short-only flag it holds the short letter, which help and the redeclaration check read. A saving here would drop name only where it equals longs[0] and keep a fallback for every other flag. ArgMeta (456 bytes) embeds its rarely used fields inline instead of behind a shared extra record, the way FlagMeta uses FlagExtra.

Go generation that can fail

usage::go::generate returns a String, so it has no way to refuse a spec it cannot generate correctly. A spec with both unknown_env and a mount is the first such case: the Go generator does not emit mounted commands, so it cannot know their variables, and the generated parser would refuse variables usage-lib accepts. generate_with_types, which the CLI calls, already returns an error for it.

  • What changes: generate returns Result<String, String> and refuses what generate_with_types refuses.
  • Why it breaks: the return type of a public function changes.
  • What adopters do: handle the error, or call generate_with_types with an empty map today.

One output for Completion::run

usage_rs::completion::Completion::run writes the script and the --install report to the same writer, so a tool that passes stdout prints installed /path there. usage generate completion --install keeps stdout empty and reports on stderr. Completion::run_split takes both writers and is the recommended call today.

  • What changes: run and run_in send the install report to stderr and only the script to out, or drop the single-writer form in favour of run_split.
  • Why it breaks: a caller that reads the report from out stops receiving it there.
  • What adopters do: call run_split now, with stdout and stderr.