Astrologue-Website/developer/usm/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>USM — Astrologue Developer</title>
  <meta name="description" content="USM — the Universal Source Manifest package manager: a project declares what it provides and needs in a MANIFEST.usm, and usm acquires, builds, tests, packages and deploys it. Free software, GPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="USM — Astrologue Developer">
  <meta property="og:description" content="The Universal Source Manifest: a project declares what it provides and needs in a MANIFEST.usm, and usm acquires, builds, tests, packages and deploys it.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">USM</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Packaging · How it all ships</span></p>
        <h1>USM</h1>
        <p class="lede">The Universal Source Manifest: a project declares what it provides and what it needs in one JSON file, and <code>usm</code> acquires, builds, tests, packages and deploys it. It is the package manager that ships the Astrologue stack — and any project you care to point it at.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>0.1</code></dd></div>
          <div><dt>Licence</dt> <dd>GPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;usm</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>Why it exists</h2>
          </header>
          <p>USM — the Universal Source Manifest — is a source-first package manager. A package is a directory with a <code>MANIFEST.usm</code> 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 <code>usm</code> command derives the whole lifecycle: acquire the sources, resolve the dependencies, build, test, install, package, publish, deploy.</p>
          <p>Every library on this site ships as a USM source package — the <code>usm install</code> line on each page is the whole ceremony. The stack bootstraps from its own foundations: USM is written in Vala against <a href="../invercargill/">Invercargill</a> and <a href="../invercargill-json/">Invercargill-Json</a>, validates its own manifest with its own validator, and — since the packaging work of this release — runs its own test suite through its own <code>test</code> exec. The package manager packages itself.</p>
          <p>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.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>What it hands you</h2>
          </header>
          <ul class="docs-features">
            <li><strong>One manifest, one truth.</strong> <code>MANIFEST.usm</code> declares provides and depends over a rich resource vocabulary — <code>lib:</code>, <code>inc:</code>, <code>vapi:</code>, <code>gir:</code>, <code>typelib:</code>, <code>pc:</code>, <code>bin:</code>, <code>res:</code>, <code>app:</code> and more — with version constraints where they matter.</li>
            <li><strong>Signed source repositories.</strong> A repository is a directory with a descriptor, ed25519 keys and a signed <code>PACKAGES.usml</code> listing; <code>usm repository init/add/publish/verify</code> tends it, and every package is checksummed.</li>
            <li><strong>DCBA artifact repositories.</strong> Distribute pre-built build artifacts as <code>.dcba</code> files alongside the sources — same layout, same signing, used automatically by <code>usm install</code> when a client's platform matches, with local builds always winning.</li>
            <li><strong>Validation that builds.</strong> <code>usm manifest validate</code> 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.</li>
            <li><strong>Tests in the lifecycle.</strong> A <code>test</code> exec in the manifest gives <code>usm manifest test</code> a suite to run against the built package — the whole stack's suites run this way.</li>
            <li><strong>System package manager bridges.</strong> Missing resources can delegate to the native manager before USM repositories are tried; five reference helpers ship (<code>usm-spm-dnf</code>, <code>-apt</code>, <code>-apk</code>, <code>-emerge</code>, <code>-pacman</code>) behind one stable JSON contract.</li>
            <li><strong>Container deployment.</strong> <code>usm manifest deploy</code> builds a container image that installs the package in-container, with the SPM bridge of your distro wired in.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the manager</h2>
          </header>
          <p>USM installs itself like anything else it manages:</p>
          <figure class="code-plate">
            <pre><code>usm install usm</code></pre>
            <figcaption>Acquires the sources, builds with meson/ninja, runs the test exec, installs.</figcaption>
          </figure>
          <p>From source it is the stack's one-build discipline — the manifest's build exec meson-sets-up <code>src/</code>:</p>
          <figure class="code-plate">
            <pre><code>git clone &lt;the usm repository&gt;
cd usm
meson setup src build
ninja -C build
ninja -C build install</code></pre>
            <figcaption>Needs valac, meson, ninja, GLib/GObject/GIO, <code>invercargill-1</code>, <code>invercargill-json</code>, json-glib and gobject-introspection.</figcaption>
          </figure>
          <p>Its own libraries are usable directly, not just through the command:</p>
          <figure class="code-plate">
            <pre><code>valac --pkg usm-0.1 my-tool.vala</code></pre>
            <figcaption>The manifest's <code>provides</code> lists <code>libusm-0.1.so</code>, <code>usm-0.1.h</code>, the vapi + <code>.deps</code>, GIR and typelib — USM ships as a library too.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>The manifest, the verbs, the bridges</h2>
          </header>
          <p>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:</p>
          <figure class="code-plate">
            <pre><code>{
  "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"
  }
}</code></pre>
            <figcaption>From the README. Every <code>provides</code> path is checked against what the build actually installed.</figcaption>
          </figure>
          <h3>The verbs</h3>
          <p>One command, grouped verbs — the descriptions below are lifted from <code>usm --help</code>:</p>
          <figure class="code-plate">
            <pre><code>usm install &lt;packages&gt;    Install packages (plan + confirm; -y to skip)
usm update [packages]     Update installed packages (or all if none named)
usm remove &lt;packages&gt;     Remove packages (cascades + sweeps orphaned deps)
usm search &lt;query&gt;        Search repositories and installed packages
usm provides &lt;resource&gt;   Find which package provides a resource
usm repository add &lt;pkg&gt;  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</code></pre>
            <figcaption>A selection — <code>usm --help</code> lists the full set, including <code>dcba</code>, <code>scaffold</code> and <code>manifest bump</code>.</figcaption>
          </figure>
          <h3>Repositories and signatures</h3>
          <p>A source repository is a directory with a <code>.usmr</code> descriptor, a <code>keys/</code> pair and a <code>public/</code> package directory; the listing is signed with the repository's ed25519 key and every package carries a SHA-512. Publishing is two commands:</p>
          <figure class="code-plate">
            <pre><code>usm repository init my-repo
usm repository add my-package-1.0.0.usmc
usm repository publish /srv/www/my-repo</code></pre>
            <figcaption>On a client: <code>usm add-repo &lt;url&gt;</code>, then <code>usm install my-package</code>.</figcaption>
          </figure>
          <h3>The self-referential bit</h3>
          <p>USM's own manifest declares the same execs every other package in the stack declares — <code>build</code>, <code>install</code>, <code>test</code> — so <code>usm manifest validate</code> on the usm repository builds USM with USM's build exec and <code>usm manifest test</code> runs USM's own suite (manifest parsing, <code>.usmignore</code> semantics, data-package validation, <code>usm.config</code> handling) through USM's test exec. The manager is managed.</p>
          <p>The repository carries the full references: <code>README.md</code> for commands and repository formats, <code>SPECIFICATION.md</code> for the manifest JSON schema, and <code>PACKAGING_GUIDE.md</code> for how to package a project well — including the classic pitfall of trusting <code>ldd</code> when declaring runtime dependencies.</p>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>0.1</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>GPL-3.0-or-later — free to run, study, share and improve. A package manager is infrastructure for everyone; this one stays strongly copyleft.</dd></div>
            <div><dt>Package</dt><dd><code>usm install usm</code></dd></div>
            <div><dt>Provides</dt><dd><code>usm</code> the binary, <code>libusm-0.1.so</code>, <code>usm-0.1.h</code>, <code>usm-0.1.vapi</code> + <code>.deps</code>, <code>usm-0.1.gir</code>, <code>usm-0.1.typelib</code>, <code>usm-0.1.pc</code>, the five SPM bridge binaries (<code>usm-spm-dnf</code>, <code>usm-spm-apt</code>, <code>usm-spm-apk</code>, <code>usm-spm-emerge</code>, <code>usm-spm-pacman</code>), and its manifest documentation under <code>slopdocs/</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib, GObject, GIO, <code>libinvercargill-1.so</code>, <code>libinvercargill-json.so</code>, json-glib, and the usual GObject platform libraries. Build time adds valac, meson, ninja and gobject-introspection.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>Tilo15/usm</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Related in the catalogue">
            <p>Its neighbours:</p>
            <ul>
              <li><a href="../invercargill/">Invercargill</a></li>
              <li><a href="../invercargill-json/">Invercargill-Json</a></li>
              <li><a href="../locksmith/">Locksmith</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <a class="docs-pager__link docs-pager__link--prev" href="../vallama/">
              <span>Previous</span>
              <strong>Vallama</strong>
            </a>
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../">
              <span>End of the catalogue</span>
              <strong>All projects</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>