pcbjam/docker

Docker Build Environment for KiCad WASM

This directory contains Docker configuration for building KiCad for WebAssembly in a reproducible, isolated environment.

Prerequisites

• Docker Desktop (with Docker Compose v2)
• Git submodules initialized: git submodule update --init --recursive

Quick Start

# Build KiCad WASM (full build)
./docker/build.sh

# Build with options
./docker/build.sh --no-clean    # Skip cleaning build directory
./docker/build.sh --debug       # Build with debug symbols

# Interactive shell for debugging
./docker/shell.sh

Branch-Specific Builds

Each git branch gets isolated Docker containers and volumes, enabling parallel development:

# On branch 'main' → containers/volumes prefixed with 'kicad-wasm-main'
# On branch 'feature-x' → containers/volumes prefixed with 'kicad-wasm-feature-x'

This allows you to:

• Work on multiple branches simultaneously using git worktrees
• Each worktree has its own build cache (no conflicts)
• Switch branches without rebuilding from scratch

Using git worktrees for parallel development:

# Create a worktree for a new branch
git worktree add ../kicad-wasm-feature path/to/branch

# Build in the worktree (uses isolated Docker volumes)
cd ../kicad-wasm-feature
./docker/build.sh

# List all worktrees
git worktree list

What Gets Built

The build process includes:

1. Dependencies (cached in Docker volume):

   • GLM (header-only)
   • Zstd, Protobuf
   • FreeType, HarfBuzz
   • Pixman, Cairo
   • Boost (Locale)
   • OpenCASCADE (optional, for 3D/STEP)
   • CURL headers, libgit2 headers (stubs)

2. wxWidgets (built from submodule)

3. KiCad PCBnew (main application)

Container Resources

Configured for M4 Max (adjust in docker-compose.yml):

• CPUs: 10 cores
• Memory: 16GB

Volume Strategy

Path	Type	Purpose
/workspace	Bind mount	Source code
/workspace/build-wasm	Named volume	Build cache (deps, sysroot)
/workspace/output	Bind mount	Final WASM output

Common Commands

# Start container
docker compose -f docker/docker-compose.yml up -d

# Run a command inside
docker compose -f docker/docker-compose.yml exec kicad-wasm-builder <command>

# View logs
docker compose -f docker/docker-compose.yml logs -f

# Stop container
docker compose -f docker/docker-compose.yml down

# Clear build cache (full rebuild)
docker volume rm docker_kicad-build-cache

Troubleshooting

Build freezes

The OpenCASCADE build is very resource-intensive. If it freezes:

1. Reduce parallel jobs: Edit script to use -j4 instead of -j$(nproc)
2. Monitor with docker stats
3. Consider building OpenCASCADE separately with ./scripts/deps/build-opencascade.sh

Permission issues

Files created in container are owned by root. To fix:

sudo chown -R $(whoami) output/

Cache issues

# Clear all cached builds
docker volume rm docker_kicad-build-cache

# Or clear specific stamps inside container
./docker/shell.sh
rm /workspace/build-wasm/stamps/*.stamp