GitHub Releases

Overview

IVPM can automatically download and install packages from GitHub Releases, including platform-specific binaries. This is ideal for:

Pre-built tools and utilities
Platform-specific executables
Large binary distributions
Versioned releases without full Git history

IVPM automatically selects the appropriate binary for your platform (Linux, macOS, Windows) or falls back to source archives.

Basic Usage

Simple Example

deps:
  - name: uv
    url: https://github.com/astral-sh/uv
    src: gh-rls

This downloads the latest release of uv for your platform.

With Version

deps:
  - name: ruff
    url: https://github.com/astral-sh/ruff
    src: gh-rls
    version: "0.1.0"

Cached

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    cache: true

Cached packages are stored by release tag and platform: <tag>_<platform>_<arch>.

Version Selection

IVPM supports multiple version selection strategies:

Latest Release

# Latest stable release (default)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest

Excludes pre-releases by default. To include pre-releases:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest
  prerelease: true

Exact Version

Match an exact release tag:

# Matches tag 'v1.2.3' or '1.2.3'
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.2.3"

# Also works with 'v' prefix
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "v1.2.3"

Version Range

Use comparison operators:

# Minimum version
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.0.0"

# Maximum version (exclusive)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "<2.0"

# Maximum version (inclusive)
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "<=1.5.0"

# Greater than
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">1.0"

Behavior:

>= and > select the earliest matching version
<= and < select the latest matching version

Examples:

Given releases: v1.0.0, v1.1.0, v1.2.0, v2.0.0

>=1.1.0 → selects v1.1.0
<2.0 → selects v1.2.0
>1.0.0 → selects v1.1.0
<=1.2.0 → selects v1.2.0

Version Parsing

IVPM parses version tags flexibly:

v1.2.3 → (1, 2, 3)
1.2.3 → (1, 2, 3)
v1.2 → (1, 2)
1.2.3.4 → (1, 2, 3, 4)

Comparison is done numerically on each component.

Pre-release Handling

By default, pre-releases are excluded:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest  # Excludes alpha, beta, rc

To include pre-releases:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: latest
  prerelease: true

This affects all version selectors:

# Include prereleases in version range
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.0.0"
  prerelease: true

Platform Selection

IVPM automatically detects your platform and selects the appropriate binary asset.

Supported Platforms

Linux:

Detects glibc version
Matches manylinux wheels (manylinux_2_17_x86_64, etc.)
Matches generic Linux binaries (linux-x86_64, linux-aarch64, etc.)
Supported architectures: x86_64, aarch64, armv7l

macOS:

Detects architecture (x86_64, arm64)
Matches assets with “macos”, “darwin”, or “osx”
Universal binaries supported

Windows:

Matches assets with “windows”, “win64”, “win32”
Supported architectures: x86_64, x86

Platform Detection Examples

Linux x86_64 with glibc 2.31:

IVPM looks for:

manylinux_2_31_x86_64 (exact match)
manylinux_2_28_x86_64 (older compatible)
manylinux_2_17_x86_64 (manylinux2014)
Generic linux-x86_64 or linux_x86_64 binaries
Falls back to source

macOS arm64 (M1/M2):

IVPM looks for:

Assets with “arm64” or “aarch64” and “macos”/”darwin”/”osx”
Falls back to any macOS asset
Falls back to source

Windows x86_64:

IVPM looks for:

Assets with “x86_64” or “amd64” and “windows”/”win64”/”win”
Falls back to any Windows asset
Falls back to source

Linux Binary Naming Schemes

IVPM supports three Linux binary naming schemes:

1. OS-Specific Naming (For distribution-specific builds):

IVPM recognizes distribution and version-specific binary naming patterns:

ubuntu-22.04-x86_64 or ubuntu-24.04-x86_64
debian-11-x86_64 or debian-12-aarch64
fedora-39-x86_64 or centos-8-x86_64
rhel-9-x86_64 or alpine-3.18-x86_64

Examples:

qemu-riscv-ubuntu-22.04-x86_64-master.20826406641.tar.gz
tool-ubuntu-24.04-aarch64.tar.gz
package-debian-11-x86_64.zip

Important: When OS-specific packages are detected in a release:

IVPM requires an exact match for your distribution and version
If no match is found, an error is raised with available options
Use source: true to bypass OS-specific requirements and download source

This ensures you don’t accidentally use incompatible binaries built for different distributions or versions.

2. manylinux Tags (For Python wheels and glibc-aware packages):

Tag	glibc Version	Compatible Systems
manylinux1	2.5	Very old systems
manylinux2010	2.12	CentOS 6+
manylinux2014	2.17	CentOS 7+
manylinux_2_28	2.28	Ubuntu 22.04+
manylinux_2_31	2.31	Recent systems

IVPM selects the newest compatible manylinux version for your system.

3. Generic Linux Naming (Common for C/C++ tools like protobuf):

IVPM also recognizes generic Linux binary naming patterns:

linux-x86_64 or linux_x86_64
linux-aarch64 or linux_aarch64 or linux-arm64
linux-aarch_64 (protobuf style)

Examples:

protoc-33.2-linux-x86_64.zip
tool-v1.0-linux-aarch64.tar.gz
binary-linux_x86_64.tar.xz

Selection Priority:

IVPM first checks for OS-specific assets (ubuntu, debian, etc.)
- If found, requires exact match or fails with helpful error
- Error message lists available OS-specific options
If no OS-specific assets, looks for manylinux-tagged assets (glibc-aware)
If none found, falls back to generic Linux naming patterns
If neither found, falls back to source archives

Source Fallback

If no platform-specific binary is found, IVPM falls back to source archives:

Try tarball_url (typically .tar.gz)
Try zipball_url (typically .zip)
Try any single generic asset
Fail with helpful error message

Example:

If a release has:

Source: source.tar.gz
Windows: tool-windows.zip
Linux: tool-linux.tar.gz
macOS: tool-macos.tar.gz

On FreeBSD (unsupported), IVPM will download source.tar.gz.

Forcing Source Download

You can force IVPM to download the source archive instead of platform-specific binaries using the source option:

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    version: latest
    source: true

This is useful when:

You want to build from source for optimization or customization
Binary releases don’t work on your platform
You need to audit or modify the source code
You’re distributing to users who will build themselves

When source: true is set:

IVPM skips all platform binary detection
Downloads tarball_url (GitHub’s source tarball, typically .tar.gz)
Falls back to zipball_url if tarball not available
Extracts to your packages directory

Complete Examples

Example 1: Installing uv

deps:
  - name: uv
    url: https://github.com/astral-sh/uv
    src: gh-rls
    version: latest

What happens:

Queries GitHub API for latest release
Detects your platform (e.g., Linux x86_64 glibc 2.31)
Selects uv-x86_64-unknown-linux-gnu.tar.gz
Downloads and extracts to packages/uv/

Usage:

$ ivpm update
$ packages/uv/uv --version

Example 2: Specific Version with Cache

deps:
  - name: ruff
    url: https://github.com/astral-sh/ruff
    src: gh-rls
    version: "0.1.6"
    cache: true

What happens:

Finds release with tag v0.1.6 or 0.1.6
Selects platform-specific binary
Caches with key 0.1.6_linux_x86_64 (example)
Symlinks from cache to packages/ruff/

Benefits:

Shared across projects
Instant for subsequent projects
Different platforms cache separately

Example 3: Version Range

deps:
  - name: tool
    url: https://github.com/org/tool
    src: gh-rls
    version: ">=1.2.0,<2.0"

Interpretation: Not directly supported as a single string.

Workaround: Use simple comparator:

# Get earliest >= 1.2.0
- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: ">=1.2.0"

Example 4: Including Prereleases

deps:
  - name: beta-tool
    url: https://github.com/org/tool
    src: gh-rls
    version: latest
    prerelease: true

What happens:

Queries all releases including pre-releases
Selects most recent (could be beta, rc, etc.)
Downloads platform-specific asset

Example 5: Protocol Buffers

deps:
  - name: protobuf
    url: https://github.com/protocolbuffers/protobuf
    src: gh-rls
    version: latest

What happens:

Queries GitHub API for latest release
Detects your platform (e.g., Linux x86_64)
Selects protoc-33.2-linux-x86_64.zip (generic Linux naming)
Downloads and extracts to packages/protobuf/

Usage:

$ ivpm update
$ packages/protobuf/bin/protoc --version
libprotoc 33.2

This demonstrates IVPM’s support for generic Linux binary naming (not manylinux).

Example 6: OS-Specific Binaries (QEMU)

deps:
  - name: qemu-riscv
    url: https://github.com/edapack/qemu-riscv
    src: gh-rls
    version: latest

What happens:

Queries GitHub API for latest release
Detects OS-specific packages (e.g., ubuntu-22.04, ubuntu-24.04)
Detects your Linux distribution and version (e.g., Ubuntu 24.04)
Selects exact match: qemu-riscv-ubuntu-24.04-x86_64-*.tar.gz
Downloads and extracts to packages/qemu-riscv/

If no exact match:

Error: No OS-specific package found for ubuntu-24.04-x86_64.
Available: ubuntu-22.04-x86_64, ubuntu-22.04-aarch64.
Consider setting source=true to download source instead.

Workaround when your OS isn’t supported:

deps:
  - name: qemu-riscv
    url: https://github.com/edapack/qemu-riscv
    src: gh-rls
    version: latest
    source: true  # Download source instead of OS-specific binary

Usage:

$ ivpm update
$ packages/qemu-riscv/bin/qemu-system-riscv64 --version

This demonstrates IVPM’s support for OS-specific binary packages that are built for particular Linux distributions and versions.

Example 7: Forcing Source Download

deps:
  - name: verilator
    url: https://github.com/verilator/verilator
    src: gh-rls
    version: latest
    source: true

What happens:

Queries GitHub API for latest release
Skips all binary detection (even if binaries are available)
Downloads source tarball (tarball_url)
Extracts to packages/verilator/

Use case:

Building Verilator from source for custom optimization flags or when pre-built binaries aren’t compatible with your system.

Example 8: Mixed Binaries and Source

package:
  name: verification-suite
  dep-sets:
    - name: default-dev
      deps:
        # Binary tool
        - name: verilator-bin
          url: https://github.com/verilator/verilator
          src: gh-rls
          version: latest
          cache: true

        # Source package
        - name: cocotb
          src: pypi

        # Git source
        - name: uvm-python
          url: https://github.com/pyuvm/pyuvm.git

Best Practices

Cache binary releases - They’re large and don’t change
Pin versions in production - Use exact versions for reproducibility
Use version ranges in development - Stay updated with >=1.0
Check release assets - Verify binaries exist for your platform before configuring
Set GITHUB_TOKEN - Avoid rate limiting in CI/CD
Test on all platforms - Ensure assets exist for Linux, macOS, Windows if deploying cross-platform
Document platform requirements - Let users know if only certain platforms are supported
Provide source fallback - Ensure releases include source archives

Advanced Configuration

Forcing Source Archives

Use source: true to skip platform binary selection and download source:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.0.0"
  source: true

This downloads the GitHub source tarball (.tar.gz) or zipball (.zip) instead of platform-specific binaries.

Benefits:

Full source code access for building with custom flags
Avoid binary compatibility issues
Works on any platform (not just those with prebuilt binaries)

Tradeoffs:

Requires build tools and dependencies to be installed
Slower initial setup compared to downloading prebuilt binaries
May need manual build steps after download

Specific Asset File (Not Yet Implemented)

Future support for selecting specific asset:

- name: tool
  url: https://github.com/org/tool
  src: gh-rls
  version: "1.0.0"
  file: "tool-custom-x86_64.tar.gz"

Currently, IVPM auto-selects based on platform.

Custom URL Patterns

For non-standard release URLs, use http source type:

- name: tool
  url: https://github.com/org/tool/releases/download/v1.0/tool.tar.gz
  src: http

GitHub Releases

Overview

Basic Usage

Simple Example

With Version

Cached

Version Selection

Latest Release

Exact Version

Version Range

Version Parsing

Pre-release Handling

Platform Selection

Supported Platforms

Platform Detection Examples

Linux Binary Naming Schemes

Source Fallback

Forcing Source Download

Complete Examples

Example 1: Installing uv

Example 2: Specific Version with Cache

Example 3: Version Range

Example 4: Including Prereleases

Example 5: Protocol Buffers

Example 6: OS-Specific Binaries (QEMU)

Example 7: Forcing Source Download

Example 8: Mixed Binaries and Source

Best Practices

Advanced Configuration

Forcing Source Archives

Specific Asset File (Not Yet Implemented)

Custom URL Patterns

See Also