first pass at linux+macos+wsl support (#790)

* first pass at linux+macos+wsl support

Signed-off-by: Dave Grantham <dwg@linuxprogrammer.org>

* fix local cache and get_num_cpu use

Signed-off-by: Dave Grantham <dwg@linuxprogrammer.org>

* add early exit when no tests

Signed-off-by: Dave Grantham <dwg@linuxprogrammer.org>

---------

Signed-off-by: Dave Grantham <dwg@linuxprogrammer.org>
Co-authored-by: Dave Grantham <dwg@linuxprogrammer.org>
Co-authored-by: Manu Sheel Gupta <manusheel.edu@gmail.com>

Author: 3 people

.gitignore

@@ -55,3 +55,6 @@ downloads/
 
 # Rust build artifacts
 target/
+
+# the local build cache folder
+**/.cache/

docs/bash.md

@@ -97,6 +97,8 @@ WORKER_COUNT="${WORKER_COUNT:-1}"
 DEBUG="${DEBUG:-false}"
 ```
 
+Note: The test framework uses `get_cpu_count()` from `lib/lib-host-os.sh` for cross-platform CPU detection (macOS uses `sysctl`, Linux/WSL uses `nproc`).
+
 **snake_case** for:
 - Local variables
 - Function parameters
@@ -132,7 +134,7 @@ Use parameter expansion for defaults:
 IMAGES_YAML="${IMAGES_YAML:-./images.yaml}"
 
 # Command substitution default
-WORKER_COUNT="${WORKER_COUNT:-$(nproc 2>/dev/null || echo 4)}"
+WORKER_COUNT="${WORKER_COUNT:-$(get_cpu_count)}"
 
 # Empty string default (variable may not be set)
 TEST_IGNORE="${TEST_IGNORE:-}"
@@ -918,7 +920,7 @@ done
 
 **Pattern**:
 ```bash
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 run_test() {
   local index="${1}"
@@ -976,7 +978,7 @@ seq 0 $((TEST_COUNT - 1)) | xargs -P "${WORKER_COUNT}" -I {} bash -c 'run_test {
 **Alternative pattern** using bash job control:
 
 ```bash
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 for ((i=0; i<TEST_COUNT; i++)); do
   # Run in background
@@ -1034,7 +1036,7 @@ wait  # Wait for all background jobs
 **2. Resource Limits**:
 ```bash
 # Respect system resources
-WORKER_COUNT=$(nproc)
+WORKER_COUNT=$(get_cpu_count)
 
 # Or limit explicitly
 WORKER_COUNT=4

docs/overall-flow.md

@@ -178,8 +178,8 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 
 4. Set test-specific defaults:
    - **Perf**: `ITERATIONS=10`, `UPLOAD_BYTES=1GB`, `DOWNLOAD_BYTES=1GB`
-   - **Transport**: `WORKER_COUNT=$(nproc)`
-   - **Hole-Punch**: `WORKER_COUNT=$(nproc)`
+   - **Transport**: `WORKER_COUNT=$(get_cpu_count)` (from lib-host-os.sh)
+   - **Hole-Punch**: `WORKER_COUNT=$(get_cpu_count)` (from lib-host-os.sh)
 
 **Code Location**:
 - `perf/run.sh:88-207`
@@ -674,6 +674,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 
    b. **Parallel** (transport, hole-punch with WORKER_COUNT>1):
    ```bash
+   WORKER_COUNT=$(get_cpu_count)  # From lib-host-os.sh
    for ((i=0; i<TEST_COUNT; i++)); do
      bash "${SCRIPT_DIR}/run-single-test.sh" "$i" "tests" "$RESULTS_FILE" &
 
@@ -1061,7 +1062,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 ### Transport Tests
 
 **Unique Characteristics**:
-- Parallel execution (WORKER_COUNT=$(nproc))
+- Parallel execution (WORKER_COUNT=$(get_cpu_count))
 - Browser implementations (dialOnly)
 - GitHub sources with patches
 - Simple pass/fail (no measurements)
@@ -1074,7 +1075,7 @@ The `inputs.yaml` file must be loaded *before* libraries are sourced because it
 ### Hole-Punch Tests
 
 **Unique Characteristics**:
-- Parallel execution (WORKER_COUNT=$(nproc))
+- Parallel execution (WORKER_COUNT=$(get_cpu_count))
 - 5-container topology per test
 - Unique subnets per test (NAT simulation)
 - DCUtR protocol measurements
@@ -1131,7 +1132,7 @@ These stop the entire run:
 
 ### Parallel Execution
 
-- **Transport/Hole-Punch**: WORKER_COUNT=$(nproc) for fast execution
+- **Transport/Hole-Punch**: WORKER_COUNT=$(get_cpu_count) for fast execution (from lib-host-os.sh)
 - **Perf**: WORKER_COUNT=1 for accurate measurements
 
 ### Network Isolation

hole-punch/README.md

@@ -110,7 +110,17 @@ Check dependencies:
 ./run.sh --check-deps
 ```
 
-Required: bash 4.0+, docker 20.10+, yq 4.0+, wget, unzip
+**Required dependencies**:
+- bash 4.0+
+- docker 20.10+ (with daemon running)
+- yq 4.0+
+- git 2.0+
+- docker compose (plugin or standalone)
+- Standard UNIX utilities (see [lib/check-dependencies.sh](../lib/check-dependencies.sh) for complete list)
+
+**Optional dependencies** (for advanced features):
+- gnuplot 5.0+ (for performance charts)
+- pandoc (for HTML report generation)
 
 ### Basic Usage
 
@@ -134,7 +144,7 @@ Required: bash 4.0+, docker 20.10+, yq 4.0+, wget, unzip
 ### Parallel Execution
 
 Hole-punch tests run in **parallel** (like transport tests):
-- Default workers: `$(nproc)` (number of CPU cores)
+- Default workers: `$(get_cpu_count)` from lib-host-os.sh (cross-platform CPU detection)
 - Override with `--workers N`
 - Tests execute concurrently for faster completion
 - Each test creates isolated Docker networks to avoid collisions

hole-punch/images/linux/run.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Linux NAT Router Configuration Script
 # Configures iptables-based NAT between LAN and WAN networks
 

hole-punch/images/rust/v0.56/run-peer.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e
 
 # Set route to relay subnet

hole-punch/images/rust/v0.56/run-relay.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e
 
 # Set route to dialer subnet

hole-punch/lib/generate-dashboard.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Generate results.md dashboard from results.yaml
 
 set -euo pipefail

hole-punch/lib/generate-tests.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Generate test matrix from images.yaml with filtering
 # Outputs test-matrix.yaml with content-addressed caching
 # Permutations: dialer × listener × transport × secureChannel × muxer × relay × dialer_router × listener_router
@@ -12,6 +12,7 @@ trap 'echo "ERROR in generate-tests.sh at line $LINENO: Command exited with stat
 # Source common libraries
 source "${SCRIPT_LIB_DIR}/lib-filter-engine.sh"
 source "${SCRIPT_LIB_DIR}/lib-generate-tests.sh"
+source "${SCRIPT_LIB_DIR}/lib-host-os.sh"
 source "${SCRIPT_LIB_DIR}/lib-image-building.sh"
 source "${SCRIPT_LIB_DIR}/lib-image-naming.sh"
 source "${SCRIPT_LIB_DIR}/lib-output-formatting.sh"
@@ -422,8 +423,8 @@ echo ""
 main_tests=()
 ignored_main_tests=()
 
-# Determine worker count (from environment, defaults to nproc)
-WORKER_COUNT="${WORKER_COUNT:-$(nproc 2>/dev/null || echo 4)}"
+# Determine worker count (from environment, defaults to hardware cpu count)
+WORKER_COUNT="${WORKER_COUNT:-$(get_cpu_count)}"
 
 # Worker function to generate tests for a chunk of dialers
 # Args: worker_id dialer_id1 dialer_id2 ...

hole-punch/lib/run-single-test.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Run a single hole punch test using docker compose
 
 set -euo pipefail