Build Guide

Build PiVirt components from source.

Overview

This guide covers building PiVirt components from source code.

Prerequisites

System Requirements

• Go 1.24 or later
• Git
• Make
• Protocol Buffers compiler (protoc)
• Node.js 20+ (for docs)

Install Dependencies

# Install Go
# https://go.dev/dl/

# Install protoc
# https://grpc.io/docs/protoc-installation/

# Install Node.js
# https://nodejs.org/

# Install additional tools
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest

Clone Repository

git clone https://github.com/pilab-dev/pivirt.git
cd pivirt

Build Components

Build All Components

# Build all binaries
make build

# Or build specific components
make build-agent
make build-pvcli
make build-iscsiman
make build-osinfodb
make build-cloudhypervisor

Build Individual Components

# Build agent
cd apps/agent
go build -o agent .

# Build pvcli
cd apps/pvcli
go build -o pvcli .

# Build iscsiman
cd apps/iscsiman
go build -o iscsiman .

# Build osinfodb
cd apps/osinfodb
go build -o osinfodb .

# Build cloudhypervisor
cd apps/cloudhypervisor
go build -o cloudhypervisor .

Build with Version Info

Version metadata is embedded via the docs package. Install the external gitinfo tool and run:

# Generate docs/doc.go with git info
gitinfo --output docs/doc.go

# Then build normally
make build

Generate Proto Files

# Proto files are defined in virtpb/proto/
# See the virtpb repository for proto generation instructions
cd ../virtpb
buf generate

Run Tests

# Run all tests
make test

# Run specific test
go test ./apps/agent/...

# Run with coverage
make test-coverage

Build Docker Images

# Build all images
make docker-build

# Build specific image
make docker-build-agent
make docker-build-pvcli

# Push images
make docker-push

Build Documentation

# Build docs
cd pibase-docs
pnpm install
pnpm build

# Serve docs locally
pnpm start

Cross-Compilation

# Build for Linux amd64
GOOS=linux GOARCH=amd64 go build -o agent-linux-amd64 ./apps/agent

# Build for Linux arm64
GOOS=linux GOARCH=arm64 go build -o agent-linux-arm64 ./apps/agent

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o agent-darwin-amd64 ./apps/agent

Troubleshooting

Build Errors

# Clean build cache
go clean -cache

# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

Proto Generation Errors

# Check protoc version
protoc --version

# Reinstall protoc plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest

Related

• Versioning Guide
• CI/CD Guide