The registry: a package by its name
A program can use a package that somebody else keeps. Until now it had to say where the package is:
needs units from "https://github.com/someone/zeno-units" at "v1.2.0"
With the registry it can say only what the package is called:
needs units at "v1.2.0"
The registry is a list that says, for each name, which git
repository the package is, and which commit of it each version is.
zeno fetch asks it, zeno search reads it, and zeno publish is
how a package gets into it. Zeno's own registry is at
github.com/zeno-src/packages,
and a page that shows it is at
zeno-lang.org/packages.
The two lines that were there before work as they did, and
using-packages.md is the page about them and
about how an import finds a package's files. The decisions for this
page are chapter 27 of decisions.md. The code is
src/registry.rs, and fetch in
src/package.rs.
Three ways to need a package
| Line | The package is | Who knows which commit |
|---|---|---|
needs filters in "../filters" |
in that folder, and is used where it is | nobody has to: it is the files that are there |
needs units from "address" at "v1.2.0" |
a git repository, at a tag, a branch or a commit | the repository, when zeno fetch asks it |
needs units at "v1.2.0" |
whatever the registry says units is |
the registry, which wrote the commit down when the version was published |
A version in the registry is written v1.2.0: the letter v and three
numbers. That is a tag of the package's repository, so the third line
is the second with the address left out, and somebody who moves a
package into the registry deletes one word and one address from the
lines that need it.
A version is one exact thing here too. There are no ranges such as
^1.2, and zeno fetch never picks a version for you (decision 8.4).
What a registry is
A git repository. There is no server, no database and no account to
make. It holds one small file for each package, in a folder called
index. This is index/units:
package units
about "Lengths, masses and times that the checker keeps apart"
from "https://github.com/someone/zeno-units"
owner "someone"
version "v1.0.0" commit "0123abc..." dated "2026-11-02"
version "v1.2.0" commit "9f8e7d6..." dated "2026-11-18"
It is written in the same plain words as zeno.package and
zeno.lock, and read by Zeno's own lexer. The four lines at the top
say what the package is called, what it is for, where it is, and who
published it. Then there is one line for each version.
The packages are not in the registry. units stays in its author's
repository, and the registry only says where that is. So the registry
stays small: a few hundred bytes for each package, however big the
package is.
The commit is what is fetched, not the tag. A tag can be moved. If
v1.2.0 is moved to another commit after it was published, everybody
still gets 9f8e7d6, because that is what the registry wrote down.
A published version stays what it was.
index.json, at the top of the registry, is the same list as one
file of JSON. zeno does not read it. It is there for the page on
zeno-lang.org, which a browser can only give JSON to.
zeno fetch, with a name
$ zeno fetch
Asked the registry https://github.com/zeno-src/packages
Fetched units v1.2.0 (9f8e7d6) into packages/units
Fetched prefix v1.0.0 (d4461d9) into packages/prefix
Wrote zeno.lock
For a line that names no address, fetch does this:
- It gets the registry, with git, into a folder of this machine
where things are kept that can be fetched again (
Index::open). Only the newest state is fetched, not the registry's history. It is asked once in a run, however many names there are. - It reads
index/unitsand finds the line forv1.2.0(Index::version). Now it has an address and a commit. - It goes on as for a line with an address: it clones the
repository into
packages/units, and checks out that commit (get). - It reads the
zeno.packageof what it got, and does the same for whatever that needs.unitsneedsprefix, so that came too. - It writes
zeno.lock.
The line in the lock begins as the needs line does, and then says
what was found:
prefix at "v1.0.0" from "https://github.com/someone/zeno-prefix" commit "d4461d9..."
units at "v1.2.0" from "https://github.com/someone/zeno-units" commit "9f8e7d6..."
With the lock, nobody is asked. The next zeno fetch, here or on
another machine, finds the address and the commit in zeno.lock. It
does not get the registry at all. If the packages are in packages/
at those commits, it does not use the network. A program with its
lock builds the same next year, whatever has happened to the registry
since.
zeno fetch --update looks every version up again, as before.
What can go wrong says what there is:
zeno: the registry has no version `v9.0.0` of `units`. It has v1.2.0 and v1.0.0
zeno: the registry https://github.com/zeno-src/packages has no package called
`unit`. `zeno search` and a word shows the packages it has
Where the copy of the registry is
| On | In |
|---|---|
| Linux | ~/.cache/zeno/registry (or under $XDG_CACHE_HOME) |
| macOS | ~/Library/Caches/zeno/registry |
| Windows | %LOCALAPPDATA%\zeno\registry |
ZENO_CACHE names another folder. The copy can be deleted at any
time: it is made again when it is next needed.
zeno search
$ zeno search noisy
1 package in the registry https://github.com/zeno-src/packages:
filters v1.1.0 Filters for noisy readings
needs filters at "v1.1.0"
https://github.com/someone/zeno-filters
older: v1.0.0
It gets the registry, and lists the packages that have every word
you gave in their name or in their about line. With no word it
lists them all. The second line of each package is the line to put
in a zeno.package.
With no network it shows the copy from last time, and says that this is what it is doing.
Publishing a package
A package that can be published is a git repository with a
zeno.package at its top, which says what the package is for:
package filters
about "Filters for noisy readings"
about is one line of at most 120 characters. It is what zeno
search and the page show.
Then a commit is given a version, which is a tag, and both are pushed:
git tag v1.0.0
git push origin main v1.0.0
and, in the package's folder:
$ zeno publish
`filters` v1.0.0 (32a7444) is ready to be published, from https://github.com/someone/zeno-filters
Open this address, signed in to GitHub, and press the button under the form:
https://github.com/zeno-src/packages/issues/new?template=publish.yml&title=...
The registry checks the package and answers on that page, most often within a few minutes.
What zeno publish checks
It changes nothing, on this machine or any other. It checks, and each thing it finds wrong comes with what to do about it:
| It checks that | Because |
|---|---|
the name is 2 to 40 small letters, digits and _ |
a registry is a folder of files named after packages, and Windows and macOS take Units and units for one file |
there is an about line |
a list of names alone tells a searcher nothing |
| the folder is the top of a git repository | the registry reads zeno.package at the top of what it fetches |
| nothing is changed and not committed | a version is a commit, and what was checked must be what is published |
the commit has a version tag (zeno publish v1.2.0 says which, if it has two) |
|
the tag is at origin, on the same commit |
the registry fetches it from there |
no needs ... in line points outside the package |
nobody who fetches the package would have that folder |
every needs ... at line names a version the registry has |
a package in the registry can be fetched whole from it |
| the name is free, or is this repository's already | a name has one owner |
| the version is not in the registry already | a published version stays what it was |
What the registry does
Zeno's own registry is on GitHub, and asking it is a form there: an
issue with two answers, the repository and the version. zeno
publish gives the address of the form with both filled in.
When the form is sent, a workflow in the registry's repository starts
tools/publish.py,
which
- reads the two answers, and takes them only if they are exactly an address of a repository on GitHub and a version;
- checks who sent the form. GitHub says which account that was. The repository must belong to that account, or to an organization that shows the account as a member;
- runs
zeno registry accept, below, which checks the package again from the repository, since whatzeno publishsaw was a folder on somebody's machine; - commits and pushes the two files that wrote, answers on the issue, and closes it.
So the accounts are GitHub's, and the registry needs none of its own.
The first to publish a name owns it. The file says owner
"someone", and a later version of units is taken only from the
same repository, asked for by the same account.
The registry's side: zeno registry accept
zeno registry accept <folder> <address> <version> --owner <who>
takes one version of the package at address into the clone of a
registry in folder. This is the whole of what a registry does to
take a package (accept in registry.rs):
- It clones the repository at that tag into a folder that it takes away again, and refuses a branch of that name: a branch moves.
- It notes the commit, and the day of the commit.
- It reads the
zeno.packagethere and checks the package aszeno publishdoes (fits). - If the name is in the registry already, the address must be the same, the owner must be the same, and the version must be new.
- It writes
index/<name>andindex.json.
It commits nothing. Whoever ran it looks at what was written, and commits and pushes.
$ zeno registry accept . https://github.com/someone/zeno-filters v1.0.0 --owner someone
Accepted filters v1.0.0 (32a7444) from https://github.com/someone/zeno-filters
Wrote index/filters and index.json
zeno registry index <folder> writes index.json again from the
files in index. It is for after a change by hand, such as taking a
package out, and it reads every file on the way, so it is also how a
registry is checked.
A registry of your own
Because a registry is any git repository, a company can keep one inside. An empty repository is a registry with no packages. A program names it:
package logger
registry "https://git.example.com/zeno-packages"
needs units at "v1.2.0"
and every name in that program is looked up there, in place of
Zeno's own. Like memory, it is the line in the program's own
zeno.package that counts: a registry line in a needed package
says nothing about the program that needs it.
For a registry that is not on GitHub there is no form, so zeno
publish ends with the line for whoever keeps it:
The registry https://git.example.com/zeno-packages is added to by whoever keeps it. In a clone of it, they run:
zeno registry accept . https://git.example.com/units v1.2.0 --owner NAME
Who may publish is then who may push to that repository.
Where each part is
| In | Is |
|---|---|
package.rs, parse |
the lines needs name at "v1.2.0", about "..." and registry "..." |
package.rs, fetch_with |
zeno fetch: the lock first, then the registry, then get |
package.rs, parse_lock, write_lock |
the two kinds of line in zeno.lock |
registry.rs, Index |
this machine's copy of a registry, and looking a name up |
registry.rs, parse_entry, write_entry, write_list |
a file of the index, and index.json |
registry.rs, search, publish, accept, relist |
the four commands |
registry.rs, fits |
what a package must be to be published, asked by both publish and accept |
modules.rs, need |
where an import finds a fetched package: packages/<name>, whichever line needed it |
What it does not do yet
- Nothing takes a version out. A version that should not be used
is taken out by a keeper of the registry, by hand. There is no
zeno unpublish, and no way to mark a version as one to avoid. - The form takes packages on GitHub only. One that lives
elsewhere is added by a keeper, with
zeno registry accept. - An owner is one account. A package cannot yet be handed to somebody else, or have two owners, except by a keeper's hand.
- No count of downloads, no page for each package. The registry never sees a fetch: git goes straight to the package's repository.
zeno publishdoes not run the package's tests. It checks that the package can be fetched, not that it is good.- A package is a whole repository. Two packages cannot share one.
- A program that changes its
registryline should runzeno fetch --update: the lock does not say which registry a line came from.
Things to try
- Make a registry in a folder:
git init --bare reg.git, andgit clone reg.git keeper. Make a package in another folder with anaboutline, commit it, tag itv0.1.0, and take it in withzeno registry accept keeper file:///full/path/to/package v0.1.0 --owner me. Readkeeper/index/<name>andkeeper/index.json. - Commit and push in
keeper. Write a program whosezeno.packagehasregistry "file:///full/path/to/reg.git"and needs your package by name. Runzeno fetch, and readzeno.lock. - Delete
packages/and the copy of the registry (the table above says where it is). Runzeno fetchagain. Which lines does it print, and what did it not have to ask? - Move the tag: change the package, commit,
git tag --force v0.1.0. Runzeno fetch --updatein the program. Which commit do you get, and why? Now try to takev0.1.0in again withaccept. - Run
zeno registry acceptfor the same package with--owner someone_elseand a new tag. What does it say? - Give the package a
needs helper in "../helper"line and runzeno publish. Read the message, and find the function inregistry.rsthat it comes from. Why isneeds helper in "helper"allowed? - In
registry.rs,numbersputs versions in order. What would go wrong inzeno searchif versions were sorted as text? Write down two versions that show it. - A big one: add
zeno registry remove <folder> <name> <version>. What should happen to a program whose lock names that version? What shouldzeno fetch --updatesay?
This page is docs/registry.md in the language repository.