qemu-npm

Platform-specific QEMU binaries distributed via npm, sourced from GitHub Releases.

Overview

qemu-npm provides an easy way to include QEMU emulator binaries in your Node.js projects. The binaries are automatically downloaded for your platform during installation, eliminating the need for manual QEMU installation.

Features

• ✅ Automatic platform detection - Downloads the correct binaries for your OS and architecture
• ✅ GitHub Releases hosting - Binaries are hosted on GitHub, no additional infrastructure needed
• ✅ Simple API - Easy-to-use functions to locate QEMU binaries
• ✅ Cross-platform support - Supports macOS (x64, arm64), Linux (x64, arm64), and Windows (x64)

Installation

npm install qemu-npm --save-dev

During installation, the package will automatically download the appropriate QEMU binaries for your platform.

Usage

Basic Usage

const { getQemuBinaryPath } = require('qemu-npm');
const { spawn } = require('child_process');

// Get the path to a specific QEMU binary
const qemuPath = getQemuBinaryPath('qemu-system-aarch64');

// Use it to spawn a QEMU process
const args = ['-m', '2048', 'my_os_image.img'];
const qemuProcess = spawn(qemuPath, args, { stdio: 'inherit' });

qemuProcess.on('error', (err) => {
  console.error('Failed to start QEMU:', err);
});

qemuProcess.on('exit', (code) => {
  console.log(`QEMU exited with code ${code}`);
});

API Reference

getQemuBinaryPath(emulatorName)

Returns the absolute path to the specified QEMU emulator binary.

• Parameters:
  • emulatorName (string): The specific QEMU binary needed (e.g., 'qemu-system-aarch64')
• Returns: (string) The absolute file path
• Throws: Error if the binary directory or binary file doesn't exist

Example:

const path = getQemuBinaryPath('qemu-system-x86_64');
console.log(path); // /path/to/node_modules/qemu-npm/bin/qemu-system-x86_64

getQemuBinDir()

Returns the directory containing all QEMU binaries.

• Returns: (string) The absolute path to the bin directory

Example:

const binDir = getQemuBinDir();
console.log(binDir); // /path/to/node_modules/qemu-npm/bin

listQemuBinaries()

Lists all available QEMU binaries.

• Returns: (string[]) Array of binary filenames

Example:

const binaries = listQemuBinaries();
console.log(binaries); // ['qemu-system-aarch64', 'qemu-system-x86_64', ...]

Supported Platforms

Platform	Architecture	Status
macOS	x64 (Intel)	✅
macOS	arm64 (Apple Silicon)	✅
Linux	x64	✅
Linux	arm64	✅
Windows	x64	✅

Architecture

This package uses a two-phase architecture:

Provider Phase (GitHub Actions)

1. Matrix build CI/CD runs for all supported platforms when a tag is pushed
2. QEMU binaries are packaged for each platform
3. Archives are uploaded to GitHub Releases

Consumer Phase (npm install)

1. The postinstall script detects your platform
2. Downloads the appropriate archive from GitHub Releases
3. Extracts binaries to ./node_modules/qemu-npm/bin
4. Sets executable permissions (Unix-like systems)

Environment Variables

• QEMU_NPM_REPO_OWNER - Override the GitHub repository owner (default: YOUR_GITHUB_USER)
• QEMU_NPM_REPO_NAME - Override the GitHub repository name (default: qemu-npm)

Development

Building a Release

1. Update the version in package.json
2. Create and push a git tag:

   git tag v1.0.0
   git push origin v1.0.0

3. GitHub Actions will automatically build and release binaries for all platforms

Testing Locally

npm test

Troubleshooting

Installation fails with "Failed to download"

• Ensure the release exists for your platform on GitHub
• Check your internet connection
• Verify the repository URL in package.json

Binary not found after installation

• Check that the postinstall script ran successfully
• Verify binaries exist in ./node_modules/qemu-npm/bin
• Try reinstalling: npm rebuild qemu-npm

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Credits

This package provides QEMU binaries. QEMU is developed by the QEMU team and is licensed under the GPL.