# 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.
```json
"name": "my-package"
```

### version
Type: string
Semantic version with optional package version suffix.
```json
"version": "1.2.3+1"
```

### summary
Type: string
Short description of the package.
```json
"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

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

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

```json
"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

```json
"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

```json
"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

```json
"flags": ["simpleBuildEnvironment"]
```

## Optional Fields

### md
Type: string
Path to markdown description file relative to manifest root.
```json
"md": "DESCRIPTION.md"
```

### url
Type: string
Project website or repository URL.
```json
"url": "https://github.com/example/my-package"
```

### screenshots
Type: array of strings
Paths to screenshot files relative to manifest root.
```json
"screenshots": ["screenshot1.png", "screenshot2.png"]
```

### icon
Type: string
Path to package icon file relative to manifest root.
```json
"icon": "my-package.svg"
```

### metainfo
Type: string
Path to AppStream metainfo file relative to manifest root.
```json
"metainfo": "my-package.appdata.xml"
```

### git
Type: object
Git repository information.
- `origin` (string): Repository URL
- `commit` (string): Commit hash, tag, or branch

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

### extras
Type: object
Additional custom properties.
```json
"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.