# USM Dependency Management

## Overview
USM manages dependencies through resource references organized by lifecycle phase. Dependencies are specified in the `depends` section of MANIFEST.usm and validated before package operations.

## Dependency Categories

### runtime
Resources required for the package to function when installed.

**Used for**: Shared libraries, runtime binaries, data files
**Checked during**: Installation, dependency resolution
**Example**:
```json
"runtime": [
  "lib:libc.so.6",
  "lib:libglib-2.0.so",
  "lib:libgio-2.0.so",
  "res:common-themes"
]
```

### build
Resources required to compile the package from source.

**Used for**: Compilers, build tools, development libraries
**Checked during**: Build operations
**Example**:
```json
"build": [
  "bin:gcc",
  "bin:make",
  "pc:glib-2.0.pc",
  "inc:glib-2.0",
  "vapi:gio-2.0.vapi"
]
```

### manage
Resources required to run management scripts (build, install, remove).

**Used for**: Shell interpreters, system utilities
**Checked during**: All script executions
**Example**:
```json
"manage": [
  "bin:bash",
  "bin:ls",
  "bin:find"
]
```

### acquire
Resources required to download and extract source code.

**Used for**: Download tools, archive utilities
**Checked during**: Source acquisition
**Optional**: Only required when `execs.acquire` is specified
**Example**:
```json
"acquire": [
  "bin:bash",
  "bin:wget",
  "bin:tar",
  "bin:gzip"
]
```

## Resource Reference Format

All dependencies use the format `[resource-type]:[resource-name]` where the resource name refers to an actual installed file on the filesystem, NOT a package name.

**Important**: Dependencies must reference specific files, not package names. For example:
- Use `bin:find` to reference the find utility executable, NOT `bin:findutils`
- Use `bin:ls` to reference the ls executable, NOT `bin:coreutils`
- Use `lib:libssl.so` to reference the SSL library, NOT `bin:openssl`

Resource references are resolved by checking for the existence of the specified file in the appropriate system directories.

### Common Runtime Dependencies
```json
{
  "runtime": [
    "lib:libssl.so.1.1",
    "lib:libcrypto.so.1.1",
    "lib:libz.so.1",
    "cfg:ssl/certs/ca-certificates.crt"
  ]
}
```

### Common Build Dependencies
```json
{
  "build": [
    "bin:gcc",
    "bin:pkg-config",
    "pc:openssl.pc",
    "pc:zlib.pc",
    "inc:openssl.h",
    "inc:zlib.h"
  ]
}
```

### Development Libraries
```json
{
  "build": [
    "pc:glib-2.0.pc",
    "pc:gtk-4.pc",
    "inc:glib-2.0.h",
    "inc:gtk-4.h",
    "vapi:gtk-4.vapi"
  ],
  "runtime": [
    "lib:libglib-2.0.so",
    "lib:libgtk-4.so"
  ]
}
```

## Dependency Resolution

### Validation Process
USM validates dependencies by:
1. Parsing resource references
2. Checking system paths for resource existence
3. Verifying accessibility and permissions
4. Reporting missing dependencies

### Resolution Order
Dependencies are resolved in this priority:
1. System standard locations
2. Environment variable overrides
3. Package manager databases
4. User-specified paths

### Error Handling
When dependencies are missing:
- Build operations fail with detailed error messages
- Installation operations list all unsatisfied dependencies
- Script execution fails before starting

## Language-Specific Dependencies

### C Projects
```json
{
  "build": [
    "bin:gcc",
    "bin:make",
    "pc:libname.pc"
  ],
  "runtime": [
    "lib:libname.so"
  ]
}
```

### Vala Projects
```json
{
  "build": [
    "bin:valac",
    "pc:glib-2.0.pc",
    "pc:gobject-2.0.pc",
    "vapi:glib-2.0.vapi"
  ],
  "runtime": [
    "lib:libglib-2.0.so",
    "lib:libgobject-2.0.so"
  ]
}
```

### Meson Projects
```json
{
  "build": [
    "bin:meson",
    "bin:ninja",
    "bin:pkg-config"
  ],
  "manage": [
    "bin:bash"
  ]
}
```

### CMake Projects
```json
{
  "build": [
    "bin:cmake",
    "bin:make",
    "bin:pkg-config"
  ],
  "manage": [
    "bin:bash"
  ]
}
```

## System Integration

### Package Manager Integration
USM can integrate with system package managers for dependency resolution:
- Check system package databases
- Install missing dependencies when authorized
- Track package manager installations

### Cross-Platform Dependencies
USM handles different system layouts:
- Linux distributions with varying directory structures
- Different library naming conventions
- Architecture-specific dependencies

### Virtual Dependencies
Some resource types provide virtual dependencies:
- `bin:sh` - Any POSIX shell
- `bin:cc` - Any C compiler
- `lib:libc.so.6` - Standard C library

## Best Practices

### Minimal Dependencies
- Specify only required dependencies
- Avoid unnecessary build dependencies
- Separate runtime and build dependencies clearly
- Use specific version requirements when needed

### Dependency Accuracy
- Test dependency specifications
- Verify all required resources are listed
- Check for missing transitive dependencies
- Validate resource references

## Common Patterns

### GUI Applications
```json
{
  "runtime": [
    "lib:libgtk-4.so",
    "lib:libgdk_pixbuf-2.0.so",
    "lib:libpango-1.0.so",
    "res:shared-mime-info",
    "res:hicolor-icon-theme"
  ],
  "build": [
    "bin:gcc",
    "pc:gtk-4.pc",
    "bin:pkg-config"
  ]
}
```

### Command Line Tools
```json
{
  "runtime": [
    "lib:libreadline.so",
    "lib:libncurses.so"
  ],
  "build": [
    "bin:gcc",
    "inc:readline",
    "inc:ncurses"
  ],
  "manage": [
    "bin:bash"
  ]
}
```

### Libraries
```json
{
  "build": [
    "bin:gcc",
    "bin:pkg-config",
    "pc:glib-2.0.pc"
  ],
  "runtime": [
    "lib:libglib-2.0.so"
  ],
  "provides": [
    "lib:libmylib.so",
    "inc:mylib.h",
    "pc:mylib.pc"
  ]
}
```

## Troubleshooting

### Missing Dependencies
Common causes and solutions:
- Incorrect resource type: Verify type matches system location
- Wrong resource name: Check exact filename/version
- Path issues: Ensure standard directories are accessible
- Permission problems: Verify file access rights

### Dependency Conflicts
When multiple packages provide same resource:
- Use specific version requirements
- Specify alternative dependencies
- Check package manager conflicts
- Consider virtual dependencies

### Circular Dependencies
Avoid circular dependency chains:
- Review dependency graph
- Split packages if necessary
- Use optional dependencies
- Reorganize package structure

---

This guide provides comprehensive information for managing USM package dependencies effectively.