Publishing a library

1. Create the library

   Start from the library template, or add a [package] table to an existing project’s apsi.toml.

   apsi new my-physics --template lib
   cd my-physics

   [project]
   name = "my-physics"              # lowercase letters, digits, "-" or "_"; 2–64 characters
   version = "1.0.0"                # semantic versioning: MAJOR.MINOR.PATCH
   description = "Orbital mechanics helpers"
   
   [package]
   entry = "src/main.apsi"          # what `use my_physics` loads
   license = "MIT"
   authors = ["Your Name"]
   keywords = ["physics", "orbits"]
   include = ["src/**", "README*", "LICENSE*", "examples/**"]
   
   [dependencies]
   linalg-extra = "^1.2"            # other libraries this one needs

2. Build it into dist/

   apsi pack checks every source file (types and units), then writes dist/NAME-VERSION.apsil: a reproducible archive with a manifest that lists the SHA-256 of every file. The same sources always produce the same bytes.

   apsi pack
   # built dist/my-physics-1.0.0.apsil  (12.4 KB, 4 files, sha256 3f9a…)

3. Create an API token

   Open Settings → Developer, give the token a name, choose its permissions — publish:new to create new libraries and publish:update to add versions — optionally limit it to one library, and copy it. It is shown only once.

4. Upload

   Store the token once and publish. The Apsi command line uses this registry by default.

   apsi lib login --token apsi_xxxxxxxxxxxxxxxxxxxx
   apsi publish                     # uploads the newest file in dist/

   Files larger than 64 MB are sent automatically in resumable 32 MB pieces; an interrupted upload continues where it stopped. In CI, pass the token through the APSI_TOKEN environment variable instead of storing it.

5. Install it anywhere

   apsi install my-physics          # newest version
   apsi install my-physics@^1.0     # newest 1.x
   apsi install "my-physics>=1.2,<2"
   apsi install                     # everything in [dependencies], then writes apsi-packages.lock

   Then use it like a standard module: use my_physics (dashes become underscores).

Rules

• A version can be uploaded only once. To fix a mistake, publish a new version; you can yank a broken one so that new installs skip it while existing lock files keep working.
• Pre-release versions such as 2.0.0-rc.1 are installed only when asked for explicitly.
• Names that differ only in “-” and “_” are the same name; the first owner keeps it.
• Every download is verified against the registry’s SHA-256 and every file against the manifest, and Apsi Guard scans the code before it can be used.
• Malware, credential stealing, hidden network access and name squatting are removed and the account is suspended. Report a library from its page.

The .apsil format

A ZIP archive (format version 1) containing apsil.json — name, version, summary, authors, license, entry file, dependencies, required Apsi version, and the SHA-256 and size of every other file — followed by the library’s files under their relative paths. Archives with files that are not listed, paths that leave the package, encrypted entries or mismatching sizes are rejected.

Registry API