Reference

Commands

usage: ivpm [-h] [--log-level {INFO,DEBUG,WARN,NONE}]
            {activate,build,cache,pkg-info,share,clone,update,init,git-status,git-update,snapshot,sync,status}
            ...

Positional Arguments

command: Possible choices: activate, build, cache, pkg-info, share, clone, update, init, git-status, git-update, snapshot, sync, status

Named Arguments

--log-level

Possible choices: INFO, DEBUG, WARN, NONE

Set the logging level (default: NONE)

Default: 'NONE'

Sub-commands

activate

Starts a new shell that contains the activated python virtual environment

ivpm activate [-h] [-c C] [-p PROJECT_DIR] [args ...]

Positional Arguments

args

Named Arguments

-c: When specified, executes the specified string
-p, --project-dir: Specifies the project directory to use (default: cwd)

build

Build all sub-projects with an IVPM-supported build infrastructure (Python)

ivpm build [-h] [-d DEP_SET] [-g]

Named Arguments

-d, --dep-set

Uses dependencies from specified dep-set instead of ‘default-dev’

-g, --debug

Enables debug for native extensions

Default: False

cache

Manage the IVPM package cache

ivpm cache [-h] {init,info,clean} ...

Positional Arguments

cache_cmd: Possible choices: init, info, clean

Sub-commands

init

Initialize a new cache directory

ivpm cache init [-h] [-s] [-f] cache_dir

Positional Arguments

cache_dir: Path to the cache directory to initialize

Named Arguments

-s, --shared

Set group inheritance (chmod g+s) for shared cache usage

Default: False

-f, --force

Force reinitialization of existing directory

Default: False

info

Show cache information (packages, versions, sizes)

ivpm cache info [-h] [-c CACHE_DIR] [-v]

Named Arguments

-c, --cache-dir

Cache directory (default: $IVPM_CACHE)

-v, --verbose

Show detailed version information

Default: False

clean

Remove old cache entries

ivpm cache clean [-h] [-c CACHE_DIR] [-d DAYS]

Named Arguments

-c, --cache-dir

Cache directory (default: $IVPM_CACHE)

-d, --days

Remove entries older than this many days (default: 7)

Default: 7

pkg-info

Collect paths/files for a listed set of packages

ivpm pkg-info [-h] [-k KIND]
              {incdirs,paths,libdirs,libs,flags} pkgs [pkgs ...]

Positional Arguments

type

Possible choices: incdirs, paths, libdirs, libs, flags

Specifies what info to query

pkgs

Named Arguments

-k, --kind: Specifies qualifiers on the type of info to query

clone

Create a new workspace from a Git URL or path

ivpm clone [-h] [-a] [-b BRANCH] [-d DEP_SET] [--py-uv] [--py-pip]
           src [workspace_dir]

Positional Arguments

src: Source URL or path to clone
workspace_dir: Target workspace directory; defaults to basename of src

Named Arguments

-a, --anonymous

Clone anonymously (HTTPS); default converts to SSH when applicable

Default: False

-b, --branch

Target branch; checks out existing or creates new

-d, --dep-set

Dependency set to use for ivpm update

--py-uv

Use ‘uv’ to manage virtual environment

Default: False

--py-pip

Use ‘pip’ to manage virtual environment

Default: False

update

Fetches packages specified in ivpm.yaml that have not already been loaded

ivpm update [-h] [-p PROJECT_DIR] [-d DEP_SET] [-j JOBS] [-a]
            [--skip-py-install] [--force-py-install] [--py-prerls-packages]
            [--py-uv] [--py-pip]

Named Arguments

-p, --project-dir

Specifies the project directory to use (default: cwd)

-d, --dep-set

Uses dependencies from specified dep-set instead of ‘default-dev’

-j, --jobs

Maximum number of parallel package fetches (default: number of CPU cores)

-a, --anonymous-git

Clones git repositories in ‘anonymous’ mode

Default: False

--skip-py-install, --py-skip-install

Skip installation of Python packages

Default: False

--force-py-install, --py-force-install

Forces a re-install of Python packages

Default: False

--py-prerls-packages

Enable installation of pre-release packages

Default: False

--py-uv

Use ‘uv’ to manage virtual environment

Default: False

--py-pip

Use ‘uv’ to manage virtual environment

Default: False

init

Creates an initial ivpm.yaml file

ivpm init [-h] [-v VERSION] [-f] name

Positional Arguments

name

Named Arguments

-v, --version: Default: '0.0.1'
-f, --force: Default: False

git-status

Runs git status on any git packages (Note: deprecated. use ‘status’ instead)

ivpm git-status [-h] [-p PROJECT_DIR]

Named Arguments

-p, -project-dir

git-update

Updates any git packages (Note: deprecated. use ‘sync’ instead)

ivpm git-update [-h] [-p PROJECT_DIR]

Named Arguments

-p, -project-dir

snapshot

Creates a snapshot of required packages

ivpm snapshot [-h] [-p PROJECT_DIR] [-r] snapshot_dir

Positional Arguments

snapshot_dir: Specifies the directory where the snapshot will be created

Named Arguments

-p, -project-dir

-r, --rls-deps

Uses release deps from project root instead of dev deps

Default: False

sync

Synchronizes dependent packages with an upstream source (if available)

ivpm sync [-h]

status

Checks the status of sub-dependencies such as git repositories

ivpm status [-h]

Command Details

activate

Activate the project-local Python virtual environment.

Synopsis:

ivpm activate [-c <command>] [-p <project-dir>] [args ...]

Options:

-c <command>: Execute a command in the activated environment and exit
-p, --project-dir <dir>: Specify project directory (default: current directory)
args: Arguments passed to shell or command

Examples:

# Start interactive shell
$ ivpm activate

# Run single command
$ ivpm activate -c "python script.py"
$ ivpm activate -c "pytest"

# Different project directory
$ ivpm activate -p /path/to/project -c "pytest"

Behavior:

Sources packages/python/bin/activate
Sets VIRTUAL_ENV and modifies PATH
Applies environment variables from env-sets
Without -c, starts an interactive shell
With -c, runs command and exits

build

Build Python packages with native extensions.

Synopsis:

ivpm build [-d <dep-set>] [-g|--debug]

Options:

-d, --dep-set <name>: Use dependencies from specified dep-set (default: project’s default)
-g, --debug: Enable debug symbols in native extensions

Examples:

# Build all packages
$ ivpm build

# Debug build
$ ivpm build --debug

# Specific dependency set
$ ivpm build -d default-dev

Behavior:

Finds all Python packages with native extensions
Runs python setup.py build_ext
Installs built extensions
Debug mode: sets DEBUG=1, adds -g flag

cache

Manage the IVPM package cache.

Synopsis:

ivpm cache <subcommand> [options]

Subcommands:

init: Initialize a new cache directory
info: Show cache statistics and contents
clean: Remove old cache entries

cache init

Initialize a cache directory.

Synopsis:

ivpm cache init [-s|--shared] [-f|--force] <cache_dir>

Options:

-s, --shared: Set group inheritance (chmod g+s) for shared access
-f, --force: Reinitialize existing directory

Examples:

# Personal cache
$ ivpm cache init ~/.cache/ivpm

# Shared team cache
$ sudo ivpm cache init --shared /shared/ivpm-cache
$ sudo chown :devteam /shared/ivpm-cache

cache info

Display cache information.

Synopsis:

ivpm cache info [-c|--cache-dir <dir>] [-v|--verbose]

Options:

-c, --cache-dir <dir>: Cache directory (default: $IVPM_CACHE)
-v, --verbose: Show detailed version information

Examples:

$ ivpm cache info
$ ivpm cache info --verbose
$ ivpm cache info --cache-dir /path/to/cache

cache clean

Remove old cache entries.

Synopsis:

ivpm cache clean [-c|--cache-dir <dir>] [-d|--days <n>]

Options:

-c, --cache-dir <dir>: Cache directory (default: $IVPM_CACHE)
-d, --days <n>: Remove entries older than N days (default: 7)

Examples:

$ ivpm cache clean
$ ivpm cache clean --days 30
$ ivpm cache clean --cache-dir /shared/cache --days 14

clone

Create a new workspace from a Git repository.

Synopsis:

ivpm clone [options] <src> [workspace_dir]

Arguments:

src: Git URL or local path to clone
workspace_dir: Target directory (default: basename of src)

Options:

-a, --anonymous: Clone anonymously over HTTPS (no SSH)
-b, --branch <name>: Checkout branch; create if doesn’t exist
-d, --dep-set <name>: Dependency set for ivpm update
--py-uv: Use ‘uv’ for Python package management
--py-pip: Use ‘pip’ for Python package management

Examples:

# Basic clone
$ ivpm clone https://github.com/org/project.git

# Custom directory
$ ivpm clone https://github.com/org/project.git my-workspace

# Specific branch
$ ivpm clone -b develop https://github.com/org/project.git

# Anonymous clone with dep-set
$ ivpm clone -a -d default https://github.com/org/project.git

# Use uv for package management
$ ivpm clone --py-uv https://github.com/org/project.git

Behavior:

Clones Git repository
Enters directory
Runs ivpm update with specified options

init

Create a new ivpm.yaml file.

Synopsis:

ivpm init [-v|--version <ver>] [-f|--force] <name>

Arguments:

name: Package name

Options:

-v, --version <ver>: Initial version (default: 0.0.1)
-f, --force: Overwrite existing ivpm.yaml

Examples:

$ ivpm init my-project
$ ivpm init my-project -v 1.0.0
$ ivpm init my-project -f  # Overwrite existing

Output:

Creates ivpm.yaml with:

package:
  name: my-project
  version: "0.0.1"

pkg-info

Query package information (paths, libraries, flags).

Synopsis:

ivpm pkg-info <type> [-k <kind>] <packages...>

Arguments:

type: Information type: incdirs, paths, libdirs, libs, flags
packages: Package names to query

Options:

-k, --kind <kind>: Qualifier for query type

Examples:

# Get include directories
$ ivpm pkg-info incdirs my-package

# Get paths by kind
$ ivpm pkg-info paths -k rtl my-package

# Get library directories
$ ivpm pkg-info libdirs package1 package2

Use case: Integration with build systems (CMake, Make, etc.)

snapshot

Create a self-contained snapshot of the project.

Synopsis:

ivpm snapshot [-p <project-dir>] [-r|--rls-deps] <snapshot_dir>

Arguments:

snapshot_dir: Output directory for snapshot

Options:

-p, -project-dir <dir>: Project directory (default: current)
-r, --rls-deps: Use release deps (default) instead of dev deps

Examples:

$ ivpm snapshot /tmp/my-snapshot
$ ivpm snapshot --rls-deps /tmp/release-snapshot
$ ivpm snapshot -p /path/to/project /tmp/snapshot

Output:

Creates directory with:

Project source
All dependency sources
python_pkgs.txt (list of Python packages)
Updated ivpm.yaml with exact versions

Use case: Archival, reproducible builds, offline distribution

status

Check status of Git dependencies.

Synopsis:

ivpm status

Examples:

$ ivpm status

Output:

For each Git package:

Package name
Current branch
Modified files
Untracked files
Commits ahead/behind remote

Use case: See which dependencies have uncommitted changes.

sync

Synchronize Git dependencies with upstream.

Synopsis:

ivpm sync

Examples:

$ ivpm sync

Behavior:

For each Git package on a branch:

git fetch origin
git merge origin/<branch>

Skips:

Packages on tags (immutable)
Packages on specific commits (immutable)
Packages with uncommitted changes (safety)

update

Fetch dependencies and initialize environment.

Synopsis:

ivpm update [options]

Options:

-p, --project-dir <dir>: Project directory (default: current)
-d, --dep-set <name>: Use specified dependency set
-j, --jobs <n>: Parallel package fetches (default: CPU count)
-a, --anonymous-git: Clone Git repos anonymously (HTTPS)
--skip-py-install: Skip Python package installation
--force-py-install: Force Python package reinstallation
--py-prerls-packages: Allow pre-release Python packages
--py-uv: Use ‘uv’ for package management
--py-pip: Use ‘pip’ for package management

Examples:

# Basic update
$ ivpm update

# Specific dependency set
$ ivpm update -d default

# Anonymous Git clones
$ ivpm update -a

# Parallel downloads
$ ivpm update -j 8

# Skip Python install
$ ivpm update --skip-py-install

# Force Python reinstall
$ ivpm update --force-py-install

# Use uv
$ ivpm update --py-uv

Behavior:

Read ivpm.yaml
Select dependency set
Fetch missing dependencies
Resolve sub-dependencies recursively
Create Python virtual environment (if needed)
Install Python packages

Global Options

These options apply to all commands:

--log-level <level>: Set logging level: INFO, DEBUG, WARN, NONE (default)

Examples:

$ ivpm --log-level DEBUG update
$ ivpm --log-level INFO status

Environment Variables

IVPM_CACHE

Path to the package cache directory.

export IVPM_CACHE=~/.cache/ivpm

Used by caching system. See Caching.

IVPM_PROJECT

Set automatically by IVPM to project root directory.

Available in env-sets as ${IVPM_PROJECT}.

IVPM_PACKAGES

Set automatically by IVPM to packages directory.

Available in env-sets as ${IVPM_PACKAGES}.

GITHUB_TOKEN

GitHub API token for higher rate limits.

export GITHUB_TOKEN=ghp_your_token_here

Useful for GitHub Releases and API queries.

YAML File Format

JSON Schema

IVPM provides a JSON Schema for ivpm.yaml files that enables IDE autocompletion and validation. To use it, add a $schema reference at the top of your file:

$schema: https://fvutils.github.io/ivpm/ivpm.schema.json

package:
  name: my-project
  version: "0.1.0"

The schema is available at:

Primary: https://fvutils.github.io/ivpm/ivpm.schema.json
Legacy (backwards compatibility): https://fvutils.github.io/ivpm/ivpm.json

Most modern editors (VS Code, IntelliJ, Vim with LSP) will automatically provide validation and autocompletion when the $schema field is present.

Package Definition

type	object
properties
name	Name of the package
	type	string
version	Version of the package
	type	string
deps-dir	Directory where dependencies are stored (default: ‘packages’)
	type	string
default-dep-set	Default dependency set to use if not specified on command line
	type	string
dep-sets	List of named dependency sets
	type	array
	items	Named package-dependency set
setup-deps	Setup-time dependencies that must be installed before other packages
	type	array
	items	type	string
paths	Path specifications organized by kind and type
	Organize project paths for tools to discover (e.g., rtl/vlog, dv/sv)
	type	object
	additionalProperties	type	object
		additionalProperties	type	array
			items	type	string
env-sets	Environment variable sets
	type	array
	items	Environment variable set

Dependency Set

Named package-dependency set

type	object
properties
name	Dependency-set identifier. ‘default’ and ‘default-dev’ are builtin names
	type	string
default-dep-set	Default dep-set name for sub-packages to inherit if not explicitly specified
	type	string
deps	Package dependencies
	type	array
	items	Package Dependency specification

Package Dependency

Package Dependency specification

type	object
properties
required	[‘name’]
name	Package identifier
	type	string
url	URL from which to obtain the dependency. Used for all execpt ‘pypi’
	type	string
src	Specifies the source type. Most of the time auto-detect works
	type	string
	oneOf	URL points to a Git repository
		const	git
		URL points to an HTTP/HTTPS resource
		const	http
		URL points to a local file (file://path)
		const	file
		URL points to a local directory (file://path)
		const	dir
		URL points to a .jar file. IVPM will not expand
		const	jar
		URL points to a gzip-compressed TAR file. IVPM will expand
		const	tgz
		URL points to a xz-compressed TAR File. IVPM will expand
		const	txz
		URL points to a zip file. IVPM will expand
		const	zip
		Dependency name is a PyPi package to be installed with pip
		const	pypi
		GitHub Release - downloads platform-specific binaries or source from releases
		const	gh-rls
type	Specifies package type. Most of the time auto-detect works
	type	string
	oneOf	Data package. IVPM will not attempt to interpret
		const	raw
		Python package that IVPM will install into the venv
		const	python
version	Version-specification string for Python packages from PyPi or GitHub Releases
	type	string
anonymous	Clone using anonymous (HTTPS) Git instead of SSH
	type	boolean
branch	Git branch to checkout
	type	string
tag	Git tag to checkout
	type	string
commit	Git commit to checkout
	type	string
deps	When set to ‘skip’, sub-dependencies will not be loaded
	type	string
	enum	skip
depth	Git clone depth (number of commits to fetch)
	type	integer
dep-set	Assuming the target is an IVPM package, specifies the named dep-set to use
	type	string
cache	Enable caching for this package. true=cached+readonly, false=readonly no cache, unspecified=full history+editable
	type	boolean
link	For ‘dir’ source type: use symlink (true) or copy (false). Default: true
	type	boolean
unpack	For archive files: whether to unpack the archive. Default: true (false for .jar)
	type	boolean
file	For GitHub Releases: specific asset filename to download
	type	string
prerelease	For GitHub Releases: include pre-release versions when selecting. Default: false
	type	boolean

Environment Set

Environment variable set

type	object
properties
name	Environment set identifier
	type	string
env	List of environment variable specifications
	type	array
	items	Environment variable specification

Environment Specification

Environment variable specification

type	object
properties
name	Environment variable name
	type	string
value	Set the variable to this value (space-separated if array)
	oneOf	type	string
		type	array
		items	type	string
path	Set the variable as a path (colon-separated if array)
	oneOf	type	string
		type	array
		items	type	string
path-append	Append to the variable as a path
	oneOf	type	string
		type	array
		items	type	string
path-prepend	Prepend to the variable as a path
	oneOf	type	string
		type	array
		items	type	string

Common Patterns

Pattern 1: Multi-Environment Project

package:
  name: versatile-project
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
          tag: v1.0
          cache: true

    - name: default-dev
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
        - name: pytest
          src: pypi
        - name: coverage
          src: pypi

    - name: ci
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
          tag: v1.0
          cache: true
          anonymous: true
        - name: pytest
          src: pypi

Pattern 2: Monorepo Structure

package:
  name: monorepo

  dep-sets:
    - name: default-dev
      deps:
        # Shared libraries
        - name: common-lib
          url: file://${IVPM_PROJECT}/../common-lib
          src: dir

        # External deps
        - name: requests
          src: pypi

Pattern 3: Platform-Specific Dependencies

package:
  name: cross-platform

  dep-sets:
    - name: default-dev
      deps:
        - name: common-tool
          url: https://github.com/org/tool
          src: gh-rls
          cache: true

        - name: pytest
          src: pypi

The gh-rls automatically selects platform-specific binaries.

Reference

Commands

Positional Arguments

Named Arguments

Sub-commands

activate

Positional Arguments

Named Arguments

build

Named Arguments

cache

Positional Arguments

Sub-commands

init

Positional Arguments

Named Arguments

info

Named Arguments

clean

Named Arguments

pkg-info

Positional Arguments

Named Arguments

share

Positional Arguments

clone

Positional Arguments

Named Arguments

update

Named Arguments

init

Positional Arguments

Named Arguments

git-status

Named Arguments

git-update

Named Arguments

snapshot

Positional Arguments

Named Arguments

sync

status

Command Details

activate

build

cache

cache init

cache info

cache clean

clone

init

pkg-info

share

snapshot

status

sync

update

Global Options

Environment Variables

IVPM_CACHE

IVPM_PROJECT

IVPM_PACKAGES

GITHUB_TOKEN

YAML File Format

JSON Schema

Package Definition

Package Definition

Dependency Set

Named package-dependency set

Package Dependency

Package Dependency specification

Environment Set

Environment variable set

Environment Specification

Environment variable specification

Common Patterns

Pattern 1: Multi-Environment Project

Pattern 2: Monorepo Structure

Pattern 3: Platform-Specific Dependencies

See Also