motiejus/zig
1
Fork 0
Code Releases Activity

switch from "id" to "nonce"

Browse Source 
mainly this addresses the following use case:

1. Someone creates a template with build.zig.zon, id field included
   (note that zig init does not create this problem since it generates
   fresh id every time it runs).
2. User A uses the template, changing package name to "example" but not
   id field.
3. User B uses the same template, changing package name also to
   "example", also not changing the id field.

Here, both packages have unintentional conflicting logical ids.

By making the field a combination of name checksum + random id, this
accident is avoided. "nonce" is an OK name for this.

Also relaxes errors on remote packages when using `zig fetch`.
This commit is contained in:
Andrew Kelley
2025-02-25 17:26:19 -08:00
parent a70307e7ff
commit 0fc7c9f57c
7 changed files with 100 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
doc/build.zig.zon.md
View File

@@ -22,21 +22,30 @@ Zig package namespace.
Must be a valid bare Zig identifier (don't `@` me), limited to 32 bytes.
### `id`
### `nonce`
Together with name, this represents a globally unique package identifier. This
field should be initialized with a 16-bit random number when the package is
first created, and then *never change*. This allows Zig to unambiguously detect
when one package is an updated version of another.
field is auto-initialized by the toolchain when the package is first created,
and then *never changes*. This allows Zig to unambiguously detect when one
package is an updated version of another.
When forking a Zig project, this id should be regenerated with a new random
number if the upstream project is still maintained. Otherwise, the fork is
*hostile*, attempting to take control over the original project's identity.
When forking a Zig project, this nonce should be regenerated if the upstream
project is still maintained. Otherwise, the fork is *hostile*, attempting to
take control over the original project's identity. The nonce can be regenerated
by deleting the field and running `zig build`.
`0x0000` is invalid because it obviously means a random number wasn't used.
This 64-bit integer is the combination of a 16-bit id component, a 32-bit
checksum, and 16 bits of reserved zeroes.
The id component within the nonce has these restrictions:
`0x0000` is reserved for legacy packages.
`0xffff` is reserved to represent "naked" packages.
The checksum is computed from `name` and serves to protect Zig users from
accidental id collisions.
### `version`
String. Required.