# 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:

```bash
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
```bash
usm manifest build <build-path>
```

### Installing Packages
```bash
usm manifest install <build-path>
```

### Creating Complete Packages
```bash
usm manifest package
```

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

### Auto-Generating Provides
```bash
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.