Node.js Build Environment Checker

0.0.7 · maintenance · verified Sun Apr 19

buildcheck is a Node.js utility library designed to perform autoconf-like environment checks for native addons and build scripts. It allows developers to programmatically determine the capabilities of the host system's C/C++ build environment, such as the existence of specific functions, headers, or the ability to compile arbitrary code snippets. Currently at version 0.0.7, its release cadence appears slow or inactive, and it primarily supports Node.js versions 10.0.0 and newer. Key differentiators include its direct integration within the Node.js ecosystem, providing a JavaScript API to probe compiler features (GCC, Clang, MSVC 2013+) and abstracting away the underlying compilation commands, making cross-platform build configuration more manageable for Node.js projects that rely on native components.

Warnings

gotcha The package is currently at version 0.0.7, indicating a pre-release or early-stage development status. API stability is not guaranteed, and breaking changes may occur in future minor or patch releases.
Fix: Consider pinning to an exact version (e.g., `"buildcheck": "0.0.7"`) and performing thorough testing before relying on this in production environments. Monitor for updates cautiously.
gotcha This package is specifically designed for build environments directly supported by Node.js. Obsolete, exotic, or unsupported build environments and platforms (e.g., very old compilers or niche operating systems) might not be detected correctly or supported, potentially leading to build failures.
Fix: Verify that your target build environment and compiler versions (e.g., gcc, clang, MSVC 2013+) meet the stated requirements. Consult Node.js documentation for officially supported platforms and toolchains.
gotcha The package appears to be CommonJS-only based on its examples (`require`). Directly using ESM `import` statements may not work without a CommonJS wrapper, transpilation, or specific Node.js configuration (e.g., `package.json` `"type": "module"` with `createRequire`).
Fix: Always use `const BuildEnvironment = require('buildcheck');` for importing the module. If integrating into an ESM-only project, you might need to use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const BuildEnvironment = require('buildcheck');`

Install

npm install buildcheck npm
yarn add buildcheck yarn
pnpm add buildcheck pnpm

Imports

BuildEnvironment
wrong:
```
import { BuildEnvironment } from 'buildcheck';
```
correct:
```
const BuildEnvironment = require('buildcheck');
```
The package is CommonJS-only based on provided examples. Direct ESM import might not work without a CommonJS wrapper or transpilation, especially for Node.js versions that require explicit module types.

Quickstart

This example demonstrates how to create a BuildEnvironment instance and use it to check for the existence of a C function, the usability of a C header, and the ability to compile both valid and intentionally invalid C code snippets.

'use strict';

const BuildEnvironment = require('buildcheck');

async function runChecks() {
  const buildEnv = new BuildEnvironment();

  console.log('--- Checking C function preadv2 ---');
  const preadv2Exists = buildEnv.checkFunction('c', 'preadv2');
  console.log(`preadv2 exists: ${preadv2Exists}`);

  console.log('--- Checking C header linux/io_uring.h ---');
  const ioUringHeaderUsable = buildEnv.checkHeader('c', 'linux/io_uring.h');
  console.log(`linux/io_uring.h usable: ${ioUringHeaderUsable}`);

  console.log('--- Trying to compile simple C code ---');
  const successfulCompile = buildEnv.tryCompile('c', 'int main() { return 0; }');
  console.log(`Successful compile: ${successfulCompile}`);

  console.log('--- Trying to compile failing C code ---');
  const failedCompile = buildEnv.tryCompile('c', 'int main() { return z; }');
  console.log(`Failed compile (as expected): ${failedCompile}`);
}

runChecks();

view raw JSON →