# USM Manifest Autoprovides Command

## Overview
The `usm manifest autoprovides` command automatically generates the `provides` section of MANIFEST.usm by scanning build output. This tool helps package maintainers ensure all installed files are properly declared.

## Usage

```bash
usm manifest autoprovides [--replace] [--debug] [build-path]
```

### Arguments
- `build-path`: Directory containing build output (optional, auto-generated if not provided)

### Options
- `--replace`: Update MANIFEST.usm file with generated provides section
- `--debug`: Disable build progress reporting and inherit file descriptors for subprocesses

## Process

### 1. Build Execution
The command first builds the package using the specified build script:
- Runs `usm manifest build` with silent output (unless --debug is used)
- Captures build progress for display (disabled with --debug)
- Uses temporary build directory if not specified
- With --debug: inherits file descriptors and disables progress callbacks

### 2. Installation Simulation
Build output is installed to temporary directory:
- Creates temporary install directory
- Runs package's install script if present
- Uses standard USM installation process
- With --debug: inherits file descriptors for install subprocess

### 3. Filesystem Scanning
The temporary install directory is scanned recursively:
- Traverses all files and directories
- Identifies resource types based on file locations
- Maps file paths to appropriate resource references

### 4. Resource Type Detection
Files are classified using these rules:
- `/usr/bin/*` → `bin:filename`
- `/usr/sbin/*` → `sbin:filename`
- `/usr/lib*/*` → `lib:filename` or `libres:filename`
- `/usr/include/*` → `inc:filename`
- `/usr/share/applications/*` → `app:filename`
- `/usr/share/man/*` → `man:filename`
- `/usr/share/info/*` → `info:filename`
- `/usr/share/locale/*` → `locale:filename`
- `/usr/share/vala*/vapi/*` → `vapi:filename`
- `/usr/share/gir*/*` → `gir:filename`
- `/usr/lib*/girepository-1.0/*` → `typelib:filename`
- `/usr/lib*/pkgconfig/*` → `pc:filename`
- `/etc/*` → `cfg:filename`
- `/opt/*` → `opt:filename`
- `/usr/share/usm-tags/*` → `tag:filename`
- Other `/usr/share/*` → `res:filename`
- All other paths → `rootpath:filename` (fallback when no specific type matches)

### 5. Output Generation
Results are formatted as JSON provides section:

```json
"provides": {
  "bin:myapp": "as-expected",
  "lib:libmyapp.so": "as-expected",
  "inc:myapp.h": "as-expected",
  "app:myapp.desktop": "as-expected",
  "res:myapp/icons/hicolor/256x256/apps/myapp.png": "as-expected",
  "rootpath:boot/config": "as-expected"
}
```

## Examples

### Basic Usage
Generate provides section and display to stdout:
```bash
usm manifest autoprovides
```

### With Custom Build Directory
Use specific build directory:
```bash
usm manifest autoprovides /tmp/myapp-build
```

### Replace in Manifest
Update MANIFEST.usm file directly:
```bash
usm manifest autoprovides --replace
```

### With Custom Build Directory and Replace
Combine options:
```bash
usm manifest autoprovides --replace /tmp/myapp-build
```

### Debug Mode
Enable debug mode for troubleshooting:
```bash
usm manifest autoprovides --debug
```

### Debug Mode with Replace
Combine debug and replace options:
```bash
usm manifest autoprovides --debug --replace
```

### All Options Combined
Use all available options:
```bash
usm manifest autoprovides --debug --replace /tmp/myapp-build
```

## Output Format

### Console Output
Without `--replace`, command outputs JSON provides section:
```json
"provides": {
  "bin:myapp": "as-expected",
  "lib:libmyapp.so": "as-expected",
  "rootpath:custom-file": "as-expected"
}
```

### File Update
With `--replace`, command:
- Updates existing MANIFEST.usm file
- Preserves all other manifest fields
- Replaces only the provides section
- Creates backup of original file

## Integration Workflow

### 1. Initial Package Creation
```bash
usm scaffold myapp meson vala
```

### 2. Build and Test
```bash
usm manifest build /tmp/build
```

### 3. Generate Provides
```bash
usm manifest autoprovides --replace /tmp/build
```

### 4. Review and Customize
Edit MANIFEST.usm to:
- Add custom file locations
- Remove unwanted resources
- Specify non-standard installations

### 5. Final Testing
```bash
usm manifest install /tmp/build
```

## Best Practices

### When to Use
- After implementing build system
- When adding new files to package
- After changing installation paths
- Before package release

### Review Required
Always review generated provides for:
- Missing important files
- Incorrect resource types
- Unwanted temporary files
- Non-standard file locations

### Manual Overrides
Some files require manual specification:
- Configuration files in custom locations
- Data files outside standard paths
- Generated files created during runtime
- Optional components

### Common Adjustments
```json
{
  "provides": {
    "bin:myapp": "as-expected",
    "lib:libmyapp.so": "as-expected",
    "cfg:myapp.conf": {"pathBase": "install", "path": "etc/myapp.conf", "type": "reg"},
    "res:myapp/default-config": {"pathBase": "source", "path": "config/default.json", "type": "reg"},
    "rootpath:boot/loader.conf": {"pathBase": "install", "path": "boot/loader.conf", "type": "reg"}
  }
}
```

## Troubleshooting

### Empty Provides
If no resources are detected:
- Check build completed successfully
- Verify install script exists and works
- Ensure files are installed to correct locations
- Check file permissions

### Incorrect Resource Types
If files are misclassified:
- Verify build follows FHS standards
- Check for custom installation paths
- Review build system configuration
- Consider manual overrides

### Build Failures
When autoprovides fails during build:
- Check build dependencies are satisfied
- Verify build script is executable
- Review build script syntax
- Test build manually first

### Permission Issues
If file update fails:
- Check MANIFEST.usm file permissions
- Verify directory write access
- Ensure file is not locked by other processes
- Run with appropriate user permissions

## Advanced Usage

### Debug Mode Benefits
The `--debug` flag provides enhanced debugging capabilities:
- **Full subprocess output**: Inherit file descriptors to see all build/install output
- **No progress interference**: Disables progress reporting that can obscure error messages
- **Direct error visibility**: Build and install errors appear immediately without progress overlay
- **Process monitoring**: Enables direct observation of subprocess behavior

### When to Use Debug Mode
- Troubleshooting build failures
- Investigating install script issues
- Analyzing subprocess output for debugging
- When progress reporting interferes with error visibility
- For detailed build/install process examination

### Custom Resource Mapping
For non-standard layouts, manually edit generated provides:
```json
{
  "provides": {
    "bin:myapp": "as-expected",
    "lib:libmyapp.so": {"pathBase": "build", "path": "custom/lib/libmyapp.so", "type": "reg"},
    "res:myapp/data": {"pathBase": "source", "path": "data/*", "type": "reg"},
    "rootpath:etc/custom-config": {"pathBase": "source", "path": "config/custom.conf", "type": "reg"}
  }
}
```

### Selective Resource Inclusion
Remove unwanted resources from generated output:
- Delete lines for temporary files
- Remove development-only resources
- Exclude documentation if not needed
- Filter out test files

---

This command provides package maintainers with automated tools for generating accurate manifest provides sections.