usm/slopdocs/utility.usm.manifest.autoprovides.md

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

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:

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

usm manifest autoprovides

With Custom Build Directory

Use specific build directory:

usm manifest autoprovides /tmp/myapp-build

Replace in Manifest

Update MANIFEST.usm file directly:

usm manifest autoprovides --replace

With Custom Build Directory and Replace

Combine options:

usm manifest autoprovides --replace /tmp/myapp-build

Debug Mode

Enable debug mode for troubleshooting:

usm manifest autoprovides --debug

Debug Mode with Replace

Combine debug and replace options:

usm manifest autoprovides --debug --replace

All Options Combined

Use all available options:

usm manifest autoprovides --debug --replace /tmp/myapp-build

Output Format

Console Output

Without --replace, command outputs JSON provides section:

"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

usm scaffold myapp meson vala

2. Build and Test

usm manifest build /tmp/build

3. Generate Provides

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

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

{
  "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:

{
  "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.