# USM Resource Types Reference

## Overview
Resource references identify specific system resources using the format `[resource-type]:[resource-name]`. The resource type determines where the resource is located on the filesystem.

## Resource Types

### rootpath
Location: Filesystem root (`/[resource-name]`)
Used for: Root-level files and directories
Example: `rootpath:boot/config`

### path
Location: `/usr/[resource-name]`
Used for: General files in /usr hierarchy
Example: `path:local/bin/custom-tool`

### opt
Location: `/opt/[resource-name]`
Used for: Optional software packages
Example: `opt:myapp/bin/myapp`

### res
Location: `/usr/share/[resource-name]`
Used for: Shared data files
Example: `res:myapp/themes/default.theme`

### cfg
Location: `/etc/[resource-name]`
Used for: Configuration files
Example: `cfg:myapp/config.conf`

### bin
Location: System PATH directories
Used for: Executable binaries
Example: `bin:myapp`

### sbin
Location: `/usr/sbin` or `/sbin`
Used for: System administration binaries
Example: `sbin:myapp-daemon`

### lib
Location: System library paths
Used for: Shared libraries
Example: `lib:libmyapp.so.1`

### libexec
Location: `/usr/libexec`
Used for: Library executables
Example: `libexec:myapp-helper`

### libres
Location: `/usr/lib`, `/usr/lib64`, `/lib`, or `/lib64`
Used for: Library resource files
Example: `libres:myapp/plugins/extension.so`

### info
Location: `/usr/share/info`
Used for: GNU info documentation
Example: `info:myapp.info`

### man
Location: `/usr/share/man`
Used for: Manual pages
Example: `man:myapp.1`

### locale
Location: `/usr/share/locale`
Used for: Localization files
Example: `locale:fr/LC_MESSAGES/myapp.mo`

### app
Location: `/usr/share/applications`
Used for: Desktop application entries
Example: `app:myapp.desktop`

### inc
Location: `/usr/include`
Used for: C/C++ header files
Example: `inc:myapp.h`

### pc
Location: pkg-config paths
Used for: pkg-config files
Example: `pc:myapp.pc`

### vapi
Location: `/usr/share/vala/vapi` or `/usr/share/vala-0.56/vapi`
Used for: Vala API files
Example: `vapi:myapp.vapi`

### gir
Location: `/usr/share/gir`
Used for: GObject Introspection files
Example: `gir:MyApp-1.0.gir`

### typelib
Location: `/usr/lib64/girepository-1.0`, `/usr/lib/girepository-1.0`, `/lib64/girepository-1.0`, or `/lib/girepository-1.0`
Used for: GObject typelib files
Example: `typelib:MyApp-1.0.typelib`

### tag
Location: `/usr/share/usm-tags/[hierarchical-path].tag`
Used for: USM system tags
Example: `tag:category.subcategory.feature`

## Resource Reference Format

Resource references follow the pattern: `type:name`

Examples:
- `bin:ls` - The ls executable
- `lib:libc.so.6` - The libc shared library
- `man:ls.1` - Manual page for ls
- `cfg:myapp.conf` - Configuration file for myapp
- `app:myapp.desktop` - Desktop entry for myapp

## Path Resolution

USM resolves resource paths in this order:
1. Check standard system locations for the resource type
2. Use USM_* environment variables when set (USM_PREFIX, USM_LIBDIR, etc.)
3. Fall back to default paths

Note: The USM_* environment variables are for the USM process itself and are used to configure how USM resolves paths internally.

## Common Usage Patterns

### Development Libraries
```json
{
  "provides": {
    "lib:libmyapp.so": "as-expected",
    "inc:myapp.h": "as-expected",
    "pc:myapp.pc": "as-expected"
  }
}
```

### Applications
```json
{
  "provides": {
    "bin:myapp": "as-expected",
    "app:myapp.desktop": "as-expected",
    "res:myapp/icons/hicolor/256x256/apps/myapp.png": "as-expected"
  }
}
```

### Development Tools
```json
{
  "provides": {
    "bin:myapp-tool": "as-expected",
    "man:myapp-tool.1": "as-expected",
    "libexec:myapp-helper": "as-expected"
  }
}
```

## Dependency Specification

Resources are specified as dependencies using the same format:

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

## Resource Validation

USM validates resource references by:
- Checking existence in expected locations
- Verifying file permissions
- Validating resource type formats
- Ensuring path accessibility

## Environment Variables

USM respects these environment variables for path customization:
- `USM_DESTDIR`: Destination directory
- `USM_PREFIX`: Installation prefix
- `USM_LIBDIR`: Library directory
- `USM_BINDIR`: Binary directory
- `USM_INCLUDEDIR`: Include directory
- `USM_DATADIR`: Data directory
- `USM_MANDIR`: Manual page directory
- `USM_TAGSDIR`: Tags directory
- `USM_INFODIR`: Info directory
- `USM_LIBEXECDIR`: Libexec directory
- `USM_LOCALEDIR`: Locale directory
- `USM_LOCALSTATEDIR`: Local state directory
- `USM_SBINDIR`: System binary directory
- `USM_SHAREDSTATEDIR`: Shared state directory
- `USM_SYSCONFIGDIR`: Configuration directory
- `USM_CONFIGDIR`: USM configuration directory

Note: These USM_* variables are for the USM process itself. Executable scripts should use the non-prefixed versions (DESTDIR, PREFIX, LIBDIR, etc.) as documented in the executable scripts reference.

---

This reference provides complete specification for all USM resource types and their usage patterns.