Publish your first package
pack, publish --dry-run, publish, and what the hub keeps
Reading packages is harmless and can always be undone. Publishing is the one
place where Gritpack asks you to slow down, because a published version is
permanent: once @ada/greet 0.1.0 exists on a hub, those bytes are what every
project that asks for it will get, forever. This chapter walks through the
whole flow with a small C library: describe the package, build it, check
everything with a dry run, publish, and keep the record of what landed.
What you will be able to do
- turn a directory into a package with a
gritpack.toml; - build the package file locally with
gritpack pack; - run every check, locally and with the hub, without publishing anything;
- publish, and read the receipt Gritpack prints;
- understand why a version can never be changed, and what to do instead.
Before you start
You need two things:
-
A login to a hub you may publish to. Reading needs no account, but every change does.
gritpack auth statusshould show your account. If it does not, see Logging in. The public hub,get.gritpack.org, does not take publications from the public; this chapter uses a private hub you were invited to. -
The right to the name. A scoped name such as
@ada/greetneeds your account to own the scope@ada.gritpack auth statuslists the scopes you can write:$ gritpack auth status
account=01a1e866-0f88-7a53-b8fe-d10b69bab7ef email=ada@example.com status=Active credential=01a1e866-2356-7c22-86a8-313961ffe866 status=Active expires_at=1797492370 writable_scope=@ada
If it says writable_scopes=none, claim one with gritpack scope claim ada
or ask your hub's administrator. Names, scopes and owners
explains the rules.
A package directory
Start with an ordinary directory of files:
greet/
include/greet.h
src/greet.c
README.md
LICENSE
gritpack init writes the smallest manifest that names the package:
$ gritpack init @ada/greet --dialect c/c23
initialized @ada/greet 0.1.0 dialect=c/c23 at ./gritpack.toml status=changed
[dependencies]
[package]
dialect = "c/c23"
name = "@ada/greet"
version = "0.1.0"
Those three fields are the package's identity: its name, its version, and its dialect, the language and version it is written in. (A small mental model covers dialects, encodings and targets.)
The first dry run, and the first refusal
Before writing anything more, ask Gritpack what would happen:
$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:2826840f... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
...
publication verification plan=sha256:2826840f... repository=550e8400-e29b-41d4-a716-446655440000 result=Blocked generation=sha256:811272b7... attestation_threshold=0
native:@ada/greet@0.1.0:c/c23:-:-: Blocked
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
PUBLICATION_DOCUMENTATION_REQUIRED: Failed: @ada/greet has no README; every publication needs one with at least 100 words of prose. To publish without one anyway, give your reason: `gritpack publish --without-readme "<reason>"`, ...
publication verification blocked
The command exits with code 6, a conflict, and nothing reached the hub. Two things in it are worth noticing.
First, the authority check passed: the hub agrees that this account may publish
@ada/greet. Second, the hub refused because the package has no README. There
is a README.md in the directory, but the manifest does not say so, and
Gritpack never guesses which files mean what. Every hub requires every new
version to carry a README of at least 100 words and a licence declaration.
README and licence explains the rule and the rare
cases where you may go without.
Describe the package properly
Fill in the rest of the manifest:
[package]
name = "@ada/greet"
version = "0.1.0"
dialect = "c/c23"
description = "A tiny C library that says hello"
keywords = ["example", "greeting"]
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
files = ["include/**", "src/**", "README.md", "LICENSE"]
[dependencies]
descriptionis the one line people see in search results, at most 512 bytes.keywordshelp search; at most 32, each at most 64 bytes, stored in lowercase.readmenames the README file inside the package.licenseis an SPDX licence expression, such asMITorApache-2.0 OR MIT.license-fileslists the licence texts you ship.fileschooses what goes into the package, with**matching any depth. Without it, every regular file under the directory is included, except the top-level.git,.gritpackandtargetdirectories.gritpack.tomlis always included.
None of these change the package's identity, but none of them can be changed after publication either, so it pays to get them right now.
Build the package file
You do not have to build the package yourself; publish does it for you. But
gritpack pack shows exactly what will be published, and is useful when you
want to look before you leap:
$ gritpack pack --output ../greet-0.1.0.gpk
packed @ada/greet 0.1.0 dialect=c/c23 files=5 payload_sha256=2d2f390ac4efb42894609b4d58c9651cf436c59ae07122863ffa3a7b542ee5f4 -> ../greet-0.1.0.gpk
A package file is one file holding the manifest, the chosen files and their digests. The name and extension are yours to choose. Packing is deterministic: the same directory always produces the same bytes, so you can build it twice, on two machines, and compare digests.
From C/C++. Nothing is compiled. A package carries the files you list, byte for byte: headers, sources, prebuilt libraries, whatever your build needs. Your build system stays yours. C and C++ shows how a consumer uses them.
The dry run again
$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:73c67995... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
native:@ada/greet@0.1.0:c/c23:-:- adapter=Native status=Indeterminate artifact=.gritpack/publication/artifacts/...
check=PUBLICATION_METADATA_COMPLETE status=Passed — gritpack.toml declares description, README, licence
check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
publication verification plan=sha256:73c67995... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable generation=sha256:b6dc691f... attestation_threshold=0
native:@ada/greet@0.1.0:c/c23:-:-: New
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
dry run complete; registry was not mutated
A dry run has two halves.
- The plan, worked out on your machine. Gritpack built the package file
into
.gritpack/publication/artifacts/, ran its local checks, and wrote the whole plan to.gritpack/publication-plan.json. You, or a reviewer, can read that file. - Verification, done by the hub. It checked that you own the name, that the
version is new (
New), and that the package meets the hub's rules.result=Publishablemeans the real publish would go through.
The last line is the promise: nothing on the hub changed. The built file is
byte for byte the one gritpack pack wrote a moment ago; their SHA-256 digests
match.
Publish
gritpack publish
On a terminal, Gritpack shows the same plan and asks once:
Publish this immutable plan? [y/N]
Type y. When there is no terminal to ask in, for example in a script or CI,
it refuses instead of guessing:
$ gritpack publish < /dev/null
...
publication requires --yes when input is non-interactive or structured output is selected
That run exits with code 2. Pass --yes once you have read the dry run:
$ gritpack publish --yes
...
committed publication transaction=01a1e870-5edc-7853-ba87-c383c8471c70 plan=sha256:73c67995... generation=sha256:59116ff0... nodes=1
native:@ada/greet@0.1.0:c/c23:-:-: New storage_id=01M7M70QPWF19VN1Y3J95JHWBM digest=sha256:1504292e5770846383bfd0296fcc7f78af02e2283fede1d4f03f7144d9b5d379
The receipt
Those two lines are your receipt:
transactionidentifies this publication on the hub. It is also the ID of the hub's signed receipt, which you can download and check later (Evidence and receipts).planis the digest of the plan that was published, the one in.gritpack/publication-plan.json.generationidentifies the state of the hub's catalogue that now includes your package.storage_idis the hub's name for this exact published file. Most commands acceptname@versioninstead (@ada/greet@0.1.0), but the storage ID is always exact.digestis the SHA-256 of the published package file. Everyone who installs@ada/greet 0.1.0from this hub gets a file with this digest, and Gritpack checks it every time.
You can ask the hub about the publication again at any time:
$ gritpack publication status 01a1e870-5edc-7853-ba87-c383c8471c70
publication transaction=01a1e870-5edc-7853-ba87-c383c8471c70 state=Committed plan=sha256:73c67995... nodes=1 expires_at=1794904640
For automation.
gritpack publish --yes --jsonprints the receipt as one JSON document, and--format ndjsonprints one record per line as the work happens. Keep it with your build's other records.
Look at what you published
Your package is visible to everyone who can read the hub:
$ gritpack search greet
@ada/greet 0.1.0 ecosystem=native score=900 dialect=c/c23 variants=1 — A tiny C library that says hello
$ gritpack info @ada/greet
@ada/greet 0.1.0 (native)
A tiny C library that says hello
dialect: c/c23
versions: 0.1.0
variants: 1
license: MIT
owner: 01a1e866-0f88-7a53-b8fe-d10b69bab7ef
...
sha256: 1504292e5770846383bfd0296fcc7f78af02e2283fede1d4f03f7144d9b5d379
A scope decides who may publish a name, not who may see it. Everyone with
access to the hub can find and use @ada/greet. Privacy comes from the hub:
packages on a private hub are seen only by that hub's users.
Why a version never changes
Every lock file that records @ada/greet 0.1.0 records its digest too. If the
bytes behind that version could change, every one of those projects would
silently build something else tomorrow. So the hub keeps the version exactly
as published.
Publishing the same thing again is harmless. Gritpack recognises the plan and gives you the same receipt:
$ gritpack publish --yes
...
PUBLICATION_IDENTITY_SATISFIED: Passed: the immutable identity already contains this artifact
publication transaction 01a1e866-b38a-7bf2-ac3e-325932fcf48a is already Committed; finishing its commit
committed publication transaction=01a1e866-b38a-7bf2-ac3e-325932fcf48a ...
Publishing something different under the same version is refused:
$ gritpack publish --dry-run
...
native:@ada/hello-tool@1.1.0:application/cli:executable/native:x86_64-unknown-linux-gnu: Conflict
PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
PUBLICATION_IDENTITY_CONFLICT: Failed: the immutable identity is occupied by different content
publication verification blocked
There is no overwrite flag. A mistake is fixed forward: raise the version in
gritpack.toml and publish 0.1.1. You can steer people away from the old
version with a deprecation or a yank, covered in After publishing.
Publishing a package file you already built
gritpack publish also accepts a package file instead of a directory:
gritpack publish ../greet-0.1.0.gpk --yes
This sends the file as it is, without a plan. Hubs that keep signed records of every publication accept new versions only through a plan, and refuse a bare file:
$ gritpack publish textkit-0.1.2.gpk --yes
the hub answered HTTP 409: repository evidence policy requires the publication transaction API
If you meet this, publish the directory instead. The directory route is also the only one where you can give the reasons described in README and licence.
What just happened
gritpack initnamed the package; you described it ingritpack.toml.gritpack packbuilt a deterministic package file you could inspect.gritpack publish --dry-runbuilt the same file, wrote a plan, and had the hub verify it, without changing anything.gritpack publishasked once (or took--yes), then committed the version and printed a receipt with its storage ID and digest.- The version is now permanent. Every fix is a new version.
You can stop here
If you publish an occasional package, this is the whole everyday flow.
Next
- README and licence explains the documentation every version needs, and what to do when the hub refuses a licence.
- Optional: Publishing step by step for several packages at once, and for publishing in separate plan, verify and publish steps.