usm

Universal Source Manifest

Manifest format (MANIFEST.usm)

{
  "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",
    "app:hello-world.desktop": "hello-world.desktop",
    "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": {
    "install": "usp-exec/install",
    "remove": "usp-exec/remove",
    "build": "usp-exec/build",
    "rebuild": "usp-exec/rebuild"
  }
}

Optional extended properties

{
  "md": "src/DESCRIPTION.md",
  "url": "https://my.package.com",
  "screenshots": [ "hello-world-screenshot.png" ],
  "icon": "hello-world.svg",
  "git": { "origin": "https://git.my.package.com/hello-world", "commit": "8d9f3b198e3a767d41f3c33fac2fbd8496f23ed2" },
  "metainfo": "hello-world.appdata.xml",
  "extras": { "customData": "whatever" }
}

Resource types

• "rootpath": Generic resource: file on root filesystem without leading "/"
• "path": Generic resource: file name locatable /usr directory
• "opt": Optional software: file name locatable /opt directory
• "res": Generic resource: resource under /usr/share directory
• "cfg": Configuration file: file name locatable /etc directory
• "bin": Binary executable: file name locatable in $PATH
• "sbin": Binary executable: file name locatable in /usr/sbin or /sbin
• "lib": Shared library: file name locatable by LD
• "libexec": Binary executable: file name locatable in /usr/libexec
• "libres": Generic resource: file name locatable /usr/lib, /usr/lib64, /lib, or /lib64 directories
• "info": Information page: file name locatable /usr/share/info
• "man": Manual page: file name locatable /usr/share/man
• "locale": Locale: file name locatable /usr/share/locale
• "app": Desktop entry: file name locatable in /usr/share/applications
• "inc": Include: file name in /usr/include
• "pc": Package config: file name locatable in $PKG_CONFIG_PATH
• "vapi": Vala API: file name in /
• "gir": GObject introspection: file name locatable in /usr/share/gir
• "typelib": GObject typelib: file name locatable in /usr/lib64/girepository-1.0, /usr/lib/girepository-1.0, /lib64/girepository-1.0, or /lib/girepository-1.0
• "tag": A USM system tag, dot seperated with ".tag" appended, i.e. "hello.world" would be locatable in /usr/share/usm-tags/hello/world.tag

Source Repositories (Repo.usmr)

{
  "name": "my-repo",
  "summary": "My software repository",
  "uris": [
    "https://my.software/repository",
  ],
  "key": "EDXLsUvOZEne+xcv+huvSaqNBs8TTldCv6hd69GdmYw="
}

Source Repository listing (PACKAGES.usml)

Entries in JSON lines format:

{
  "type": "usmc",
  "manifest": {}, // Manifest object from MANIFEST.usm
  "path": "my-package.usmc", // Relative path to the package
  "sha512": "0+6QpQ5Wst2bPmAPYKO/RKrFYuq93rcaRs7tqt9lCo9zu8v6jpJsDqd7yPIqCWDt0KpOQ3uLK64Tmn9FYNw3eQ=="
}

Last line consists of the signatures for the repository

{
  "type": "signatures",
  "signatures": [
    {
      "key": "EDXLsUvOZEne+xcv+huvSaqNBs8TTldCv6hd69GdmYw=",
      "signature": "0rHQiDGKgumMK2S3B6D9jjU3NLnLLjijYJRvaB5vLbp4zxzjlixfyX8yfvvJUCCd34CC1STzyzawDtb9ZammCTE4zFHFdpnO8eseDS5OY+aKgAyL13oBGizvy/V0zGHVCdv83GQ7QUtgSWje0RKKk1zPGDAIF/prkurlFDgd3Vg="
    }
  ]
}

Complete package (package.usmc)

Complete package is simply a tar.xz file containing a MANIFEST.usm file and all the requisite files that would be acquired if the acquire script was run. That is to say, a USMC file could be created by simply running usm manifest acquire followed by tar -cJf ../package.usmc ..

USM Directory /var/usm

• /packages
  • /packagename-0.1.1
  • /origin-info
  • /package.usmc
  • /build-log (when built)
  • /build.tar.xz (when built)
  • /build (when building)
• /installed
  • /packagename-0.1.1 (symlink to /var/usm/packages/packagename-0.1.1)
• /lists
  • /repositoryname
  • /2020-03-20T14:28:23.382748.usml
  • /2020-03-20T14:34:42.382748.usml
• /transactions
  • 2020-03-21T14:28:23.382748
  • 2020-03-23T14:23:43.382748

Origin info format

{
    "repository": "repositoryname",
    "listfile": "2020-03-20T14:34:42.382748.usml",
    "original_path": "packagename-0.1.1.usmc",
    "signature_verified": true
}

Resource Ref Additions

• Add version expressions (can copy from MPK), i.e. == >= <= <>
• Add support for version expressions to some resource types, namely pkg and pc

Below here are draft ideas that may or may not get implemented

Transactions

• Create backup BTRFS snapshot
• Create transaction BTRFS snapshot from backup snapshot
• Apply difference between backup and transaction snapshots to live filesystem
• Delete transaction snapshot

JSONL transaction journal format

{
  "operation": "begin-transaction",
  "timestamp": "2020-03-20T14:34:42.382748",
  "snapshot": "path/to/backup/snapshot",
  "subvolume": "path/to/transaction/subvolume"
}

{
  "operation": "begin-transaction",
  "timestamp": "2020-03-20T14:34:42.382748",
}

Scriptable installation

• USM will not manage the installation if an install exec is present
• Compare backup and transaction snapshots for validation
• Scripts can optionally handle installation but it must be verified that the expected files (and only the expected files) are installed
• Add post-install and maybe post-transaction execs that are not subject to validations