usm/slopdocs/structure.usm.manifest.packaging.md

USM Package Maintainer Guide

Overview

USM (Universal Source Manifest) is a JSON-based package management system that defines software packages through manifest files. This guide provides package maintainers with comprehensive information for creating and managing MANIFEST.usm files.

Package Structure

A USM package consists of:

• MANIFEST.usm: JSON manifest file at the project root
• usm-scripts/: Directory containing executable scripts (optional, recommended)
• Source code and project files

Creating a New Package

Using Scaffold Templates

USM provides scaffold templates to quickly create new packages:

usm scaffold <package-name> <template> [attributes...]

Available templates:

• basic: Creates only MANIFEST.usm
• makefile: Adds make build system support
• meson: Adds Meson build system support

Attributes:

• vala: Add Vala language dependencies
• c: Add C language dependencies
• acquire: Add source acquisition support

Manual Manifest Creation

Create MANIFEST.usm at the project root with required fields:

• name: Package identifier (no spaces)
• version: Semantic version with optional package version
• summary: Short description
• licences: Array of license objects
• provides: Resources provided by the package
• depends: Package dependencies
• execs: Executable scripts
• flags: Package behavior flags

Package Management Workflow

Building Packages

usm manifest build <build-path>

Installing Packages

usm manifest install <build-path>

Creating Complete Packages

usm manifest package

This creates a .usmc (USM Complete) archive containing the manifest and all source files.

Auto-Generating Provides

usm manifest autoprovides [--replace] [build-path]

Scans build output to automatically generate the provides section.

Package Validation

USM validates manifests for:

• Required field presence
• Correct license categories
• Valid resource references
• Proper dependency satisfaction
• Executable script permissions

Best Practices

Version Management

Use semantic versioning: MAJOR.MINOR.PATCH+PACKAGE_VERSION

• Increment MAJOR for incompatible changes
• Increment MINOR for new features
• Increment PATCH for bug fixes
• Add +N for packaging revisions

Dependency Management

• Specify minimal required dependencies
• Use appropriate resource types
• Separate runtime, build, and management dependencies
• Verify dependency satisfaction before distribution

Resource Provision

• Use as-expected for standard file locations
• Specify exact paths for non-standard installations
• Include all necessary files in provides
• Use appropriate resource types

Script Management

• Make all scripts executable
• Use proper exit codes
• Handle script arguments correctly
• Test scripts in isolation

Repository Integration

Packages can be distributed through USM repositories using:

• PACKAGES.usml: Package listing files
• Repo.usmr: Repository metadata
• Cryptographic signatures for security

Troubleshooting

Common issues and solutions:

• Missing dependencies: Verify all resource references exist
• Build failures: Check executable script permissions and paths
• Installation errors: Ensure provides matches actual build output
• Validation failures: Review JSON syntax and required fields

---

This guide provides package maintainers with essential information for creating, managing, and distributing USM packages effectively.