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:

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

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

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

"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

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

Common Build Dependencies

{
  "build": [
    "bin:gcc",
    "bin:pkg-config",
    "pc:openssl.pc",
    "pc:zlib.pc",
    "inc:openssl.h",
    "inc:zlib.h"
  ]
}

Development Libraries

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

Parsing resource references
Checking system paths for resource existence
Verifying accessibility and permissions
Reporting missing dependencies

Resolution Order

Dependencies are resolved in this priority:

System standard locations
Environment variable overrides
Package manager databases
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

{
  "build": [
    "bin:gcc",
    "bin:make",
    "pc:libname.pc"
  ],
  "runtime": [
    "lib:libname.so"
  ]
}

Vala Projects

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

{
  "build": [
    "bin:meson",
    "bin:ninja",
    "bin:pkg-config"
  ],
  "manage": [
    "bin:bash"
  ]
}

CMake Projects

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

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

{
  "runtime": [
    "lib:libreadline.so",
    "lib:libncurses.so"
  ],
  "build": [
    "bin:gcc",
    "inc:readline",
    "inc:ncurses"
  ],
  "manage": [
    "bin:bash"
  ]
}

Libraries

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

structure.usm.manifest.dependency-management.md 6.3 KB Histórico Em bruto