Writing and publishing a package
A Tern package is a git repository. There's no registry to sign up for and nothing to upload: you push the code, tag a version, and anyone can use it with tern add NAME https://.... This page walks through writing one, testing it, publishing it, and what the people who depend on it will see.
What a package is
A package is a git repository whose top level holds .tn files. Together those files are one module, imported by the name the user gives the package (import geo). Files in it see each other's names without imports, the same as any directory of .tn files (see chapter 12 of the tour).
tern-geo/ the repository
geo.tn named after the package: the overview comment goes here
distance.tn more of the same module
distance_test.tn tests: never part of the package
tern.mod only if it uses other packages
README.md
LICENSEName the main file after the package (geo.tn for geo). Users and their tools open it first: tern add prints its API is in the comment at the top of deps/geo/geo.tn.
tern new geo --template lib starts one: a module file, a test file, a tern.mod, a README, and an AGENTS.md for coding agents.
Document it at the top
Begin geo.tn with a comment that says what the package is for and lists every public function with its signature, one per line. That comment is the package's documentation: people read it in deps/, and coding agents read it before calling anything.
# geo: distances and bearings on the Earth's surface.
#
# fn point(lat: float, lon: float) Point
# fn km(a: Point, b: Point) float great-circle distance
# fn bearing(a: Point, b: Point) float degrees clockwise from north
#
# Points are in degrees; distances use a spherical Earth (radius 6371 km).
struct Point:
lat: float
lon: float
fn point(lat: float, lon: float) Point:
return Point(lat, lon)Names starting with _ are private to the package. Everything else is its public API, so keep helpers underscored.
Test it from inside
A *_test.tn file in the package's directory is part of the package: it calls the package's functions and uses its types by their plain names, private ones included, with no import.
# distance_test.tn
import testing
fn test_same_point():
p = point(51.5, -0.1)
testing.near(km(p, p), 0.0, 0.000001)
fn test_london_paris():
testing.near(km(point(51.5074, -0.1278), point(48.8566, 2.3522)), 343.5, 1.0)tern test # every *_test.tn below hereTest files never ship: anyone who adds your package gets its code without them.
Other packages it needs
If your package imports another package, list it in your repository's tern.mod, exactly as a program would (tern add NAME URL writes the line). When someone adds your package, tern get reads your tern.mod too and fetches what it lists. All packages in a project share one deps/ directory, and the project's own tern.mod decides when two packages want different versions of a third.
Publish it
- Push the repository to a public git host over https. GitHub, GitLab, Codeberg, Bitbucket and sourcehut all work.
- Tag a release with a semantic version and push the tag:
git tag v0.1.0
git push origin v0.1.0That's it. A version is a vMAJOR.MINOR.PATCH tag (v1.2.0, or v1.3.0-beta.1 for a pre-release). Bump the patch for fixes, the minor version for additions, and the major version when existing code would stop compiling.
Never move or reuse a tag. Everyone who depends on v0.1.0 has the hash of its files in their tern.lock, so if the tag later points at different code, their next tern get fails. If a release is broken, tag a new one.
How people use it
tern add geo https://github.com/you/tern-geo # the newest vX.Y.Z tag
tern add geo@v0.1.0 https://github.com/you/tern-geo # a particular versionThat writes a line to their tern.mod, fetches the package into deps/geo/, and records it in tern.lock:
# tern.mod
geo = https://github.com/you/tern-geo@v0.1.0Then import geo works from any file in their project. They can call it anything they like: the name on the left of = is the import name.
What your users see
tern.lock records each package's exact commit, a hash of its files, and its capabilities: what its code can reach, worked out from its imports.
| Capability | When the package's code (tests excluded) has |
|---|---|
net | import roost, http, net, tls, grpc, pg, redis, queue or sentry |
fs | import fs |
os | import os (processes, environment variables) |
db | import sqlite |
c | an extern block (C code) |
dep:NAME | an import of another package, NAME |
An update that adds a capability is refused until the user accepts it with tern get --accept geo. A string library that suddenly gains net is how a hijacked package usually gives itself away, so users get to see it. Keep capabilities small: a parsing package that takes a string, rather than reading a file itself, needs no fs.
Neither fetching nor building runs any of your code. Tern has no install scripts, build scripts or macros, so there's nothing to hide code in, and nothing for you to maintain.
The rules a package must follow
tern get refuses a package that breaks any of these:
- at least one
.tnfile at the top level - regular files only: no symlinks, submodules or special files
- at most 5,000 files and 20 MB
- plain path names: no two that differ only in case, no
.., and no control characters or\ : * ? " < > |
A short name in the index
tern search WORD and tern add NAME (with no URL) look names up in the package index, a curated list that maps short names to repositories. The index is opening to submissions: until then, share the tern add NAME URL line in your README, which works for everyone today.
Private packages
A package can be private: give tern add an ssh URL (git@github.com:yourco/geo.git), and tern get uses your own git credentials. TERN_PRIVATE (comma-separated prefixes such as github.com/yourco/) marks https URLs that should always go straight to git, never through a public mirror.