USM

USM — the Universal Source Manifest — is a source-first package manager. A package is a directory with a MANIFEST.usm at its root: one JSON document naming the package, its version, its licences, every resource it provides (libraries, headers, vapis, GIRs, typelibs, pkg-config files, binaries, data) and every resource it depends on at runtime, at build time, and to manage it. From that single declaration, the usm command derives the whole lifecycle: acquire the sources, resolve the dependencies, build, test, install, package, publish, deploy.

Every library on this site ships as a USM source package — the usm install line on each page is the whole ceremony. The stack bootstraps from its own foundations: USM is written in Vala against Invercargill and Invercargill-Json, validates its own manifest with its own validator, and — since the packaging work of this release — runs its own test suite through its own test exec. The package manager packages itself.

Source-first is the point: what you install is what was built from the sources you can read, with binary-artifact repositories (DCBA) available as a cache layer rather than a chain to hold you.

• One manifest, one truth. MANIFEST.usm declares provides and depends over a rich resource vocabulary — lib:, inc:, vapi:, gir:, typelib:, pc:, bin:, res:, app: and more — with version constraints where they matter.
• Signed source repositories. A repository is a directory with a descriptor, ed25519 keys and a signed PACKAGES.usml listing; usm repository init/add/publish/verify tends it, and every package is checksummed.
• DCBA artifact repositories. Distribute pre-built build artifacts as .dcba files alongside the sources — same layout, same signing, used automatically by usm install when a client's platform matches, with local builds always winning.
• Validation that builds. usm manifest validate builds the package, installs to a temporary directory and checks that every declared resource actually appeared — a manifest cannot claim what the build never produced.
• Tests in the lifecycle. A test exec in the manifest gives usm manifest test a suite to run against the built package — the whole stack's suites run this way.
• System package manager bridges. Missing resources can delegate to the native manager before USM repositories are tried; five reference helpers ship (usm-spm-dnf, -apt, -apk, -emerge, -pacman) behind one stable JSON contract.
• Container deployment. usm manifest deploy builds a container image that installs the package in-container, with the SPM bridge of your distro wired in.

USM installs itself like anything else it manages:

usm install usm

From source it is the stack's one-build discipline — the manifest's build exec meson-sets-up src/:

git clone <the usm repository>
cd usm
meson setup src build
ninja -C build
ninja -C build install

Its own libraries are usable directly, not just through the command:

valac --pkg usm-0.1 my-tool.vala

A manifest names the package, its version, its licences, what it provides and what it depends on — this is the README's own example, trimmed to the shape:

{
  "name": "my-package",
  "version": "1.0.5+2",
  "summary": "A sample package",
  "licences": [ {"name": "GPLv3", "category": "libre", "text": "src/LICENSE"} ],
  "provides": {
    "bin:hello-world": "hello-world",
    "res:usr/share/icons/hicolor/scalable/hello-world.svg": "icons/hello-world.svg"
  },
  "depends": {
    "runtime": [ "lib:libgtk-4.so.1" ],
    "build":     [ "bin:valac", "bin:meson", "inc:gtk-4.0" ],
    "manage":    [ "bin:bash" ]
  },
  "execs": {
    "build":   "usm-scripts/build",
    "install": "usm-scripts/install",
    "test":    "usm-scripts/test"
  }
}

The verbs

One command, grouped verbs — the descriptions below are lifted from usm --help:

usm install <packages>    Install packages (plan + confirm; -y to skip)
usm update [packages]     Update installed packages (or all if none named)
usm remove <packages>     Remove packages (cascades + sweeps orphaned deps)
usm search <query>        Search repositories and installed packages
usm provides <resource>   Find which package provides a resource
usm repository add <pkg>  Add a package (.usmc) to this repository
usm manifest validate     Validate a manifest
usm manifest test         Run package tests
usm manifest package      Create a .usmc archive
usm manifest deploy       Deploy a package as a container image

Repositories and signatures

A source repository is a directory with a .usmr descriptor, a keys/ pair and a public/ package directory; the listing is signed with the repository's ed25519 key and every package carries a SHA-512. Publishing is two commands:

usm repository init my-repo
usm repository add my-package-1.0.0.usmc
usm repository publish /srv/www/my-repo

The self-referential bit

USM's own manifest declares the same execs every other package in the stack declares — build, install, test — so usm manifest validate on the usm repository builds USM with USM's build exec and usm manifest test runs USM's own suite (manifest parsing, .usmignore semantics, data-package validation, usm.config handling) through USM's test exec. The manager is managed.

The repository carries the full references: README.md for commands and repository formats, SPECIFICATION.md for the manifest JSON schema, and PACKAGING_GUIDE.md for how to package a project well — including the classic pitfall of trusting ldd when declaring runtime dependencies.

Version

0.1 (from MANIFEST.usm)

Licence

GPL-3.0-or-later — free to run, study, share and improve. A package manager is infrastructure for everyone; this one stays strongly copyleft.

Package

usm install usm

Provides

usm the binary, libusm-0.1.so, usm-0.1.h, usm-0.1.vapi + .deps, usm-0.1.gir, usm-0.1.typelib, usm-0.1.pc, the five SPM bridge binaries (usm-spm-dnf, usm-spm-apt, usm-spm-apk, usm-spm-emerge, usm-spm-pacman), and its manifest documentation under slopdocs/

Needs at runtime

GLib, GObject, GIO, libinvercargill-1.so, libinvercargill-json.so, json-glib, and the usual GObject platform libraries. Build time adds valac, meson, ninja and gobject-introspection.

Source

The repository Tilo15/usm on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.