From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 11 Nov 2025 21:05:43 GMT
Subject: Re: [PATCH v3 01/10] doc: define unambiguous type mappings across C and Rust
Message-ID: <xmqq1pm4wa8o.fsf@gitster.g>
In-Reply-To: <e5d084d340e874be52e7c3b056ada15ab5557877.1762890152.git.gitgitgadget@gmail.com>

"Ezekiel Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/technical/unambiguous-types.adoc b/Documentation/technical/unambiguous-types.adoc
> new file mode 100644
> index 0000000000..6bca39209b
> --- /dev/null
> +++ b/Documentation/technical/unambiguous-types.adoc
> @@ -0,0 +1,239 @@
> += Unambiguous types
> +
> +Most of these mappings are obvious, but there are some nuances and gotchas with
> +Rust FFI (Foreign Function Interface).
> +
> +This document defines clear, one-to-one mappings between primitive types in C,
> +Rust (and possible other languages in the future). Its purpose is to eliminate
> +ambiguity in type widths, signedness, and binary representation across
> +platforms and languages.

This is a laudable goal.  It does a lot more than "to eliminate
ambiguity" at least in some sections.  The section on character
types I already commented on, for example, is full of good points to
list the concerns that developers need to be aware of and careful
about.

> +== Enum types
> +Rust enum types should not be used as FFI types. Rust enum types are more like
> +C union types than C enum's. For something like:
> +
> +```
> +#[repr(C, u8)]
> +enum Fruit {
> +    Apple,
> +    Banana,
> +    Cherry,
> +}
> +```
> +
> +It's easy enough to make sure the Rust enum matches what C would expect, but a
> +more complex type like.
> +
> +```
> +enum HashResult {
> +    SHA1([u8; 20]),
> +    SHA256([u8; 32]),
> +}
> +```
> +
> +The Rust compiler has to add a discriminant to the enum to distinguish between
> +the variants. The width, location, and values for that discriminant is up to
> +the Rust compiler and is not ABI stable.

Good example, as we already do use this one, if I am not mistaken
;-)