usm/slopdocs/structure.usm.manifest.md

MANIFEST.usm Reference

Overview

MANIFEST.usm is a JSON file that defines the structure, metadata, and behavior of a USM software package. This document provides a complete reference for all manifest fields.

Required Fields

name

Type: string The package identifier without spaces.

"name": "my-package"

version

Type: string Semantic version with optional package version suffix.

"version": "1.2.3+1"

summary

Type: string Short description of the package.

"summary": "A sample package for demonstration"

licences

Type: array of license objects List of licenses applicable to the package.

Each license object contains:

• name (string): License name
• category (string): License category ("libre", "open-source", "source-available", "proprietary")

• text (string): Path to license file relative to manifest

  "licences": [
  {
  "name": "GPLv3",
  "category": "libre",
  "text": "LICENSE"
  }
  ]
  

provides

Type: object Resources provided by the package. Keys are resource references, values are file specifications.

"provides": {
  "bin:myapp": "as-expected",
  "lib:libmyapp.so": "as-expected",
  "inc:myapp.h": {"pathBase": "source", "path": "include/myapp.h", "type": "reg"}
}

depends

Type: object Package dependencies organized by category.

• runtime (array): Runtime dependencies
• build (array): Build-time dependencies
  
• manage (array): Management dependencies

• acquire (array, optional): Source acquisition dependencies

  "depends": {
  "runtime": ["lib:libc.so.6", "lib:libglib-2.0.so"],
  "build": ["bin:gcc", "pc:glib-2.0.pc"],
  "manage": ["bin:bash"]
  }
  

execs

Type: object Executable scripts for different package lifecycle phases.

• build (string, required): Build script path
• install (string, optional): Install script path
• remove (string, optional): Removal script path
• postInstall (string, optional): Post-install script path
• acquire (string, optional): Source acquisition script path

• test (string, optional): Test script path

  "execs": {
  "build": "usm-scripts/build.sh",
  "install": "usm-scripts/install.sh",
  "acquire": "usm-scripts/acquire.sh",
  "test": "usm-scripts/test.sh"
  }
  

flags

Type: array of strings Package behavior flags.

• "buildInSourceTree": Build in source directory
• "setManifestPropertyEnvs": Set manifest properties as environment variables
• "ninjaStyleProgress": Parse Ninja-style progress output

• "simpleBuildEnvironment": Copy full source tree to build directory before building and execute all build-related scripts from build directory

  "flags": ["simpleBuildEnvironment"]
  

Optional Fields

md

Type: string Path to markdown description file relative to manifest root.

"md": "DESCRIPTION.md"

url

Type: string Project website or repository URL.

"url": "https://github.com/example/my-package"

screenshots

Type: array of strings Paths to screenshot files relative to manifest root.

"screenshots": ["screenshot1.png", "screenshot2.png"]

icon

Type: string Path to package icon file relative to manifest root.

"icon": "my-package.svg"

metainfo

Type: string Path to AppStream metainfo file relative to manifest root.

"metainfo": "my-package.appdata.xml"

git

Type: object Git repository information.

• origin (string): Repository URL

• commit (string): Commit hash, tag, or branch

  "git": {
  "origin": "https://github.com/example/my-package",
  "commit": "v1.2.3"
  }
  

extras

Type: object Additional custom properties.

"extras": {
  "customField": "customValue",
  "buildSystem": "cmake"
}

File Specification Objects

When using object notation in provides, files can be specified with:

pathBase

Base location for the file:

• "source": Extracted source directory
• "build": Build output directory
• "install": Install destination directory
• "as-expected": Standard system location

path

File path relative to pathBase. Empty string when pathBase is "as-expected".

type

File system entry type:

• "reg": Regular file
• "dir": Directory
• "lnk": Symbolic link

dest

Destination path for symbolic links (required when type is "lnk").

keepOn

Array of conditions when resource should not be deleted:

• "final": During final uninstallation
• "upgrade": During package upgrade
• "downgrade": During package downgrade

skipFor

Array of conditions when resource should not be installed:

• "fresh": During fresh installation
• "upgrade": During package upgrade
• "downgrade": During package downgrade

Shorthand Notation

Files can be specified using shorthand notation:

• "as-expected": Standard location
• "build:path/to/file": From build directory
• "source:path/to/file": From source directory
• "install:path/to/file": From install directory

Validation Rules

USM validates manifests for:

• All required fields present
• Valid JSON syntax
• Correct license categories
• Valid resource references
• Proper file specification objects
• Semantic version format compliance

---

This reference provides complete specification for MANIFEST.usm files used by USM packages.