Getting Started with IVPM

Installing IVPM

IVPM must be installed before it can be used to work with a project. Typically, the easiest approach is to install IVPM as a user-installed package:

$ python3 -m pip install --user ivpm

Once this is done, you can invoke IVPM either via the entry-point script (ivpm) or as a Python module:

$ ivpm --help
$ python3 -m ivpm --help

Quick Start: Clone an Existing Project

The fastest way to start with IVPM is to clone an existing IVPM-enabled project:

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

This single command:

  1. Clones the Git repository

  2. Reads the project’s ivpm.yaml

  3. Fetches all dependencies

  4. Creates a Python virtual environment

  5. Installs Python packages

After cloning, you’re ready to work:

$ ivpm activate -c "python --version"
$ ivpm activate -c "pytest"

Clone Command Options

$ ivpm clone [options] <src-url-or-path> [workspace_dir]

Common options:

-a, --anonymous

Clone anonymously over HTTPS instead of using SSH. By default, HTTPS URLs are converted to SSH form (git@host:path).

-b, --branch <name>

Checkout the specified branch. If origin/<name> exists, it will be checked out tracking the remote; otherwise, a new local branch is created.

-d, --dep-set <name>

Specify the dependency set for ivpm update (e.g., default-dev).

--py-uv or --py-pip

Choose whether ivpm update should use “uv” or “pip” to manage the project-local Python virtual environment.

Examples:

# Clone with default workspace directory name
$ ivpm clone https://github.com/fvutils/ivpm

# Clone into specific directory with new branch
$ ivpm clone https://github.com/org/project my-workspace -b feature/new

# Clone anonymously and select dependency set
$ ivpm clone -a https://github.com/org/project -d default-dev

# Clone and use uv for Python package management
$ ivpm clone https://github.com/org/project --py-uv

Creating a New IVPM Project

To create a new IVPM-enabled project from scratch:

Step 1: Initialize the Project

$ mkdir my-project
$ cd my-project
$ ivpm init my-project -v 0.1.0

This creates a basic ivpm.yaml file:

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

Step 2: Add Dependency Sets

Edit ivpm.yaml to add your dependencies:

package:
  name: my-project
  version: "0.1.0"
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        # Runtime dependencies
        - name: requests
          src: pypi

    - name: default-dev
      deps:
        # Runtime dependencies
        - name: requests
          src: pypi
        # Development dependencies
        - name: pytest
          src: pypi

Step 3: Run Initial Update

Fetch dependencies and create the Python virtual environment:

$ ivpm update

This creates:

my-project/
├── ivpm.yaml
└── packages/
    └── python/           # Virtual environment
        ├── bin/
        ├── lib/
        └── ...

Step 4: Create Your Project Structure

$ mkdir -p src/my_project test
$ touch src/my_project/__init__.py
$ touch test/test_basic.py

Now you have a complete project structure:

my-project/
├── ivpm.yaml
├── packages/
│   └── python/
├── src/
│   └── my_project/
│       └── __init__.py
└── test/
    └── test_basic.py

Working with Dependencies

Adding Dependencies

To add a new dependency, edit ivpm.yaml:

Add a PyPI package:

deps:
  - name: numpy
    src: pypi
    version: ">=1.20"

Add a Git repository:

deps:
  - name: my-library
    url: https://github.com/org/my-library.git
    branch: main

Add a local development package:

deps:
  - name: co-developed
    url: file:///home/user/projects/library
    src: dir

After editing, run:

$ ivpm update

Updating Dependencies

To fetch the latest changes from Git repositories:

$ ivpm status    # Check status of all Git packages
$ ivpm sync      # Update Git packages from upstream

To update Python packages:

$ ivpm update --force-py-install

Using the Python Virtual Environment

IVPM creates a project-local Python virtual environment in packages/python/.

Activate for a Single Command

$ ivpm activate -c "python script.py"
$ ivpm activate -c "pytest"
$ ivpm activate -c "python -m my_module"

Start an Interactive Shell

$ ivpm activate
(venv) $ python
(venv) $ pytest
(venv) $ exit

The shell prompt shows (venv) when the environment is active.

Practical Examples

Example 1: Simple Python Project

ivpm.yaml:

package:
  name: data-processor
  version: "1.0.0"
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        - name: pandas
          src: pypi
        - name: numpy
          src: pypi

    - name: default-dev
      deps:
        - name: pandas
          src: pypi
        - name: numpy
          src: pypi
        - name: pytest
          src: pypi
        - name: black
          src: pypi

Usage:

$ ivpm update -d default-dev
$ ivpm activate -c "pytest"
$ ivpm activate -c "black src/"

Example 2: Mixed Dependencies

ivpm.yaml:

package:
  name: verification-env
  default-dep-set: default-dev

  dep-sets:
    - name: default-dev
      deps:
        # Python test framework
        - name: cocotb
          src: pypi

        # Co-developed Python library
        - name: bus-models
          url: https://github.com/org/bus-models.git

        # Verilog RTL (raw package)
        - name: uart-rtl
          url: https://github.com/org/uart.git
          type: raw

        # Test vectors
        - name: test-data
          url: https://cdn.example.com/vectors.tar.gz
          type: raw

Usage:

$ ivpm update
$ ivpm activate -c "make sim"

Example 3: Using Dependency Sets

ivpm.yaml:

package:
  name: soc-design
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        - name: cpu-core
          url: https://github.com/org/cpu.git
          tag: v1.0

    - name: default-dev
      deps:
        - name: cpu-core
          url: https://github.com/org/cpu.git  # Development branch
        - name: test-framework
          url: https://github.com/org/test.git

    - name: fpga
      deps:
        - name: cpu-core
          url: https://github.com/org/cpu.git
          tag: v1.0
        - name: xilinx-ips
          url: https://github.com/org/xilinx.git

Usage:

# Development work
$ ivpm update -d default-dev

# Release build
$ ivpm update -d default

# FPGA build
$ ivpm update -d fpga

Common Workflows

Daily Development

# 1. Start working
$ cd my-project
$ ivpm activate

# 2. Work on code
(venv) $ python src/my_script.py
(venv) $ pytest

# 3. Check dependency status
(venv) $ ivpm status

# 4. Done for the day
(venv) $ exit

Adding a New Dependency

# 1. Edit ivpm.yaml to add dependency
$ vim ivpm.yaml

# 2. Update to fetch new dependency
$ ivpm update

# 3. Verify it's available
$ ivpm activate -c "python -c 'import new_package'"

Syncing with Upstream

# 1. Check status of all Git dependencies
$ ivpm status

# 2. Update from upstream
$ ivpm sync

# 3. Re-install Python packages if needed
$ ivpm update --force-py-install

Troubleshooting

Update Fails with SSH Error

Problem: Cannot clone Git repositories with SSH

Solution: Use anonymous (HTTPS) cloning:

$ ivpm update -a

Or set anonymous: true in ivpm.yaml:

deps:
  - name: my-lib
    url: https://github.com/org/lib.git
    anonymous: true

Python Package Not Found

Problem: Cannot import a package that should be installed

Solution: Verify the package is in the active dependency set:

$ ivpm update -d default-dev  # Ensure correct dep-set
$ ivpm activate -c "pip list"  # Check installed packages

Dependencies Not Loading

Problem: Expected dependencies not appearing in packages/

Solution: Check your dependency set:

# See what's configured
$ cat ivpm.yaml

# Try explicit dependency set
$ ivpm update -d default-dev

Slow Updates

Problem: ivpm update is very slow

Solutions:

  1. Use caching for Git dependencies:

    deps:
  - name: large-repo
    url: https://github.com/org/large.git
    cache: true

  2. Use shallow clones:

    deps:
  - name: repo
    url: https://github.com/org/repo.git
    depth: 1

  3. Skip Python reinstall if already done:

    $ ivpm update --skip-py-install

Next Steps

Now that you have the basics: