research/building-tools

Building Tools

Complete guide to building, bundling, and deploying P2P applications with the Holepunch ecosystem.

Overview

The Holepunch build system spans multiple layers from native C++ libraries to JavaScript bundling and cross-platform application distribution.

flowchart TB
    subgraph "Build System Layers"
        CMAKE["CMake Toolchain<br/>Native Dependencies"]
        BARE["Bare Build<br/>JS Runtime"]
        PEAR["Pear Build<br/>App Distribution"]
    end
    
    subgraph "Outputs"
        NATIVE["Native Binaries<br/>.so/.dylib/.dll"]
        BUNDLE["JS Bundles<br/>.bare/.pear"]
        APP["Applications<br/>.apk/.app/.exe"]
    end
    
    CMAKE --> NATIVE
    BARE --> BUNDLE
    PEAR --> APP
    NATIVE --> BUNDLE
    BUNDLE --> APP

---

1. CMake Build System

1.1 Overview

The CMake toolchain provides cross-platform building for native dependencies across iOS, Android, macOS, Windows, and Linux.

1.2 CMake Modules

Module	Purpose	Platforms
cmake-bare	Bare runtime builds	All
cmake-bare-bundle	Bare bundle creation	All
cmake-pear	Pear app builds	All
cmake-drive	Drive module builds	All
cmake-napi	Native addon builds	All
cmake-cargo	Rust integration	All
cmake-meson	Meson integration	All
cmake-gn	GN build integration	All

1.3 Platform-Specific CMake

Module	Platform	Purpose
cmake-ios	iOS	iOS builds
cmake-macos	macOS	macOS builds
cmake-windows	Windows	Windows builds
cmake-android	Android	Android builds
cmake-java	JVM / JNI	Java-side native integration
cmake-linux	Linux	Linux builds

KB articles: cmake-android, cmake-java; other cmake-* modules are listed under ../modules/tooling/.

1.4 Package Management

Module	Purpose
cmake-vcpkg	vcpkg integration
cmake-ports	Port management
cmake-fetch	Dependency fetching
cmake-toolchains	Cross-compilation
musl-toolchains	musl libc builds

1.5 Distribution

Module	Purpose
cmake-app-image	Linux AppImage
cmake-msix	Windows MSIX
cmake-harden	Security hardening

1.6 Language Support

Module	Purpose
cmake-zig	Zig language
cmake-rust	Rust language

1.7 CMake Workflow

flowchart LR
    SRC["Source Code"] --> CONFIG["CMake Configure"]
    CONFIG --> GEN["Generate Build Files"]
    GEN --> BUILD["Build Native"]
    BUILD --> LINK["Link Libraries"]
    LINK --> OUT["Native Binary"]

Example CMakeLists.txt:

cmake_minimum_required(VERSION 3.25)
project(my_app)

# Include Holepunch cmake modules
include(cmake-bare)
include(cmake-napi)

# Find native dependencies
find_package(sodium REQUIRED)
find_package(rocksdb REQUIRED)

# Build native addon
add_bare_addon(my_addon
  SOURCES src/my_addon.c
  LIBRARIES sodium rocksdb
)

# Build Bare bundle
add_bare_bundle(my_bundle
  ENTRY src/index.js
  OUTPUT my_app.bare
)

---

2. Bare Build System

2.1 Overview

Bare provides tools for building JavaScript applications into native binaries and bundles.

2.2 Build Tools

Tool	Purpose	Command
bare-make	Build system	bare-make
bare-build	Compile app	bare-build
bare-dev	Development	bare-dev
bare-run	Run app	bare-run

2.3 Bundling Tools

Tool	Purpose	Output
bare-bundle	Create bundle	.bare file
bare-pack	Package app	Archive
bare-unpack	Extract bundle	Source
bare-bundle-compile	Compile bundle	Binary
bare-bundle-evaluate	Execute bundle	Runtime

2.4 Distribution Tools

Tool	Purpose	Output
bare-distributable	Create distributable	Platform package
bare-app-image	Linux AppImage	.AppImage
bare-sidecar	Sidecar bundle	Bundle

2.5 Platform Builds

Platform	Tool	Output
iOS	bare-ios	.ipa
Android	bare-android	.apk
macOS	bare-kit	.app
Windows	bare-win-ui	.exe
Linux	bare-gtk	Binary

2.6 Bare Build Workflow

flowchart TB
    JS["JavaScript Source"] --> RESOLVE["bare-module-resolve"]
    RESOLVE --> LEX["bare-module-lexer"]
    LEX --> BUNDLE["bare-bundle"]
    BUNDLE --> COMPILE["bare-bundle-compile"]
    COMPILE --> PACK["bare-pack"]
    PACK --> DIST["bare-distributable"]
    DIST --> OUT["Platform Binary"]

Example bare-build workflow:

# Initialize project
bare-init my-app
cd my-app

# Development mode
bare-dev

# Build for production
bare-build --release

# Create bundle
bare-bundle --entry index.js --output app.bare

# Package for distribution
bare-pack --bundle app.bare --output app.tar.gz

# Build platform-specific
bare-distributable --platform android --output my-app.apk

2.7 Bare Module System

Module	Purpose
bare-module	Module loader
bare-module-resolve	Resolution algorithm
bare-module-lexer	Fast parsing
bare-module-traverse	Dependency walking

2.8 Native Addons

Module	Purpose
bare-addon	Addon loader
bare-addon-resolve	Addon resolution
bare-compat-napi	NAPI compatibility
bare-prebuild	Prebuilt binaries

Building native addons:

# Configure build
bare-make configure

# Build addon
bare-make build

# Create prebuild
bare-prebuild --upload

---

3. Pear Build System

3.1 Overview

Pear provides the complete application lifecycle from initialization to distribution.

3.2 Pear CLI commands (Pear v2.4+)

Command	Purpose	Example
pear init	Initialize project	pear init my-app
pear dev	Local development / hot reload	pear dev
pear build	Multi-architecture deployment folder (v2.5+)	pear build
pear stage	Stage files to pear drive (set pear.stage.ignore)	pear stage
pear seed	Seed a link	pear seed
pear touch	Create or refresh pear links	pear touch
pear multisig	Production signing (pear.json)	pear multisig
pear release	Release step when used in your workflow	pear release
pear inspect	Debug app	pear inspect
pear doctor	Diagnostics	pear doctor
pear info	App information	pear info

Deprecated: CLI pear run (v2.4+) — use pear dev and embed pear-runtime for OTA-capable binaries. KB: Pear, commands, core-concepts/pear-runtime.

3.2a Distribution bundles

For multi-architecture app folders and related tooling, see bundlebee and bundlebee-cli.

3.3 Pear Build Tools

Tool	Purpose
pear-bundle	Application bundling
pear-pack	Package creation
pear-build	Build orchestration
pear-stage	Release staging
pear-release	Release management

3.4 Pear Update System

Tool	Purpose
pear-updater	Update client
pear-updates	Update server
pear-updater-bootstrap	Bootstrap updates

3.5 Pear Application Types

Type	Runtime	Use Case
Desktop	pear-desktop	Desktop GUI apps
Terminal	pear-terminal	CLI/TUI apps
Electron	pear-electron	Electron-based
Mobile	pear-appling	iOS/Android

3.6 Pear Build Workflow

flowchart TB
    INIT["pear init"] --> DEV["pear dev"]
    DEV --> BUILD["pear build"]
    BUILD --> STAGE["pear stage"]
    STAGE --> RELEASE["pear release"]
    RELEASE --> SEED["pear seed"]
    SEED --> UPDATE["pear-updater"]

Example pear workflow:

# Initialize new app
pear init my-app --template desktop
cd my-app

# Development (Pear v2.4+: prefer pear dev; CLI pear run is deprecated)
pear dev

# Build for production (see pear --help for flags valid on your version)
pear build

# Stage / seed / release — exact flags depend on template; consult docs.pears.com
pear stage
pear seed
pear release

3.7 Pear Configuration

pear.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "desktop",
  "main": "index.js",
  "scripts": {
    "build": "pear build",
    "test": "brittle test/*.js"
  },
  "dependencies": {
    "hypercore": "^10.0.0",
    "hyperswarm": "^4.0.0"
  },
  "pear": {
    "platforms": ["darwin", "linux", "win32"],
    "architectures": ["x64", "arm64"],
    "icon": "assets/icon.png"
  }
}

---

4. Project Templates

4.1 Available Templates

Template	Command	Description
Desktop	pear init --template desktop	Desktop GUI app
Terminal	pear init --template terminal	Terminal app
Mobile	pear init --template mobile	iOS/Android app
Library	pear init --template lib	Reusable library
Addon	pear init --template addon	Native addon

4.2 Template Structure

my-app/
├── package.json          # Project config
├── pear.json            # Pear config
├── index.js             # Entry point
├── CMakeLists.txt       # Native build (optional)
├── src/
│   ├── index.js         # Main code
│   ├── app.js           # App logic
│   └── components/      # UI components
├── test/
│   └── test.js          # Tests
├── assets/
│   ├── icon.png         # App icon
│   └── splash.png       # Splash screen
└── docs/
    └── README.md        # Documentation

---

5. Testing Tools

5.1 Test Frameworks

Tool	Purpose	Usage
brittle	Primary test framework	brittle test/*.js
bare-tap	TAP output	bare-tap test.js
bare-cov	Coverage	bare-cov test.js

5.2 Test Utilities

Tool	Purpose
canary-runner	CI/CD testing
hyper-health-check	Health monitoring
hypercore-e2e-tests	E2E tests
hyperswarm-e2e-tests	Network E2E

5.3 Testing Workflow

# Run tests
brittle test/*.js

# With coverage
bare-cov -- brittle test/*.js

# E2E tests
npm run test:e2e

# CI/CD
canary-runner --config .canary.yml

---

6. Debugging Tools

6.1 Pear Debugging

Tool	Purpose	Command
pear-inspect	Inspector	pear inspect
pear-doctor	Diagnostics	pear doctor
pear-info	System info	pear info

6.2 Bare Debugging

Tool	Purpose
bare-inspect	Code inspection
bare-inspector	Debug protocol
bare-console	Console utilities
bare-repl	Interactive shell

6.3 Network Debugging

Tool	Purpose
hyperswarm-doctor	Network diagnostics
hypertrace	Distributed tracing
hypertrace-logger	Trace logging
hypertrace-prometheus	Metrics export
hypermetrics	Performance metrics

---

7. Prebuilds and Containers

7.1 Prebuild System

Tool	Purpose
prebuild-containers	Build containers
chromium-prebuilds	Chromium binaries
bare-prebuild	Bare prebuilds

7.2 Container Images

# Build with container
docker run -v $(pwd):/app holepunch/prebuild-container

# Prebuild for all platforms
bare-prebuild --all

---

8. Performance Benchmarks

8.1 Runtime Comparison

Platform	Runtime	Score	Size	Efficiency
Ubuntu x64	Bare	40k	43MB	947 ops/MB
Ubuntu x64	Node.js	41k	102MB	406 ops/MB
macOS arm64	Bare	53k	33MB	1638 ops/MB
macOS arm64	Node.js	55k	94MB	591 ops/MB

Bare achieves ~97% of Node.js performance with 2-3x better efficiency.

8.2 Bundle Sizes

Bundle Type	Size	Use Case
Minimal	~50KB	Hello world
Hypercore	~500KB	Data structures
Full Stack	~2MB	Complete app
Desktop App	~50MB	With runtime

---

9. Cross-Platform Builds

9.1 Platform Matrix

Platform	Bare	Pear	CMake	Native
iOS	✅	✅	✅	✅
Android	✅	✅	✅	✅
macOS	✅	✅	✅	✅
Windows	✅	✅	✅	✅
Linux	✅	✅	✅	✅

9.2 Cross-Compilation

# Build for iOS from macOS
bare-build --platform ios --arch arm64

# Build for Android from Linux
bare-build --platform android --arch arm64-v8a

# Build for Windows from macOS
bare-build --platform win32 --arch x64

---

10. Best Practices

10.1 Development Workflow

1. Initialize: Use pear init with appropriate template
2. Develop: Use pear dev for hot reload (CLI pear run is deprecated v2.4+)
3. Test: Write tests with brittle
4. Build: Use pear build for production
5. Release: Stage with pear stage, release with pear release
6. Distribute: Seed with pear seed

10.2 Native Dependencies

1. Use cmake-* modules for native builds
2. Prebuild binaries with bare-prebuild
3. Test on all target platforms
4. Document native requirements

10.3 Bundle Optimization

1. Minimize dependencies
2. Use tree shaking
3. Compress assets
4. Lazy load modules

---

Quick Reference

Essential Commands

# Initialize
pear init my-app
cd my-app

# Development
pear dev

# Build
pear build

# Test
brittle test/*.js

# Release
pear stage
pear release

# Debug
pear inspect
pear doctor

File Locations

File	Purpose
package.json	NPM dependencies
pear.json	Pear configuration
CMakeLists.txt	Native build config
bare-bundle.config.js	Bundle config

---

See Also

• Architecture - System architecture
• Core Concepts - Key concepts
• Interconnections - Component composition
• Existing Projects - Real-world examples