Tern

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
    LICENSE

Name 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 here

Test 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

  1. Push the repository to a public git host over https. GitHub, GitLab, Codeberg, Bitbucket and sourcehut all work.
  2. Tag a release with a semantic version and push the tag:
git tag v0.1.0
git push origin v0.1.0

That'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 version

That 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.0

Then 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.

CapabilityWhen the package's code (tests excluded) has
netimport roost, http, net, tls, grpc, pg, redis, queue or sentry
fsimport fs
osimport os (processes, environment variables)
dbimport sqlite
can extern block (C code)
dep:NAMEan 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 .tn file 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.

Source: docs/guides/publishing-packages.md. Every example on this page is compiled and run by tern x test docs.