bare-make

bare-make — Opinionated build system generator based on CMake.

npm i bare-make

UsageCopy Anchor Link

Like CMake, builds happen in three steps: You first generate a build system, then run the build system, and finally install the built artefacts. To perform the steps programmatically from JavaScript, do:

const make = require('bare-make')

await make.generate()
await make.build()
await make.install()

The steps can also be performed interactively from the command line using the included CLI:

bare-make generate
bare-make build
bare-make install

TestingCopy Anchor Link

To run tests for projects that use enable_testing() and add_test(), do:

await make.test()

Tests can also be run from the command line:

bare-make test

EnvironmentCopy Anchor Link

Programs built with some toolchains need environment changes to run. For example, the macOS, Linux, and Windows toolchains add the directory of llvm-symbolizer, which the sanitizers use to print readable reports, to PATH. bare-make test applies these changes automatically, but programs you run outside of CTest, such as a JavaScript test suite that loads an addon, must apply them themselves. Added in v2.1.0: to get the variables to set, do:

const env = await make.test.env()

env maps each variable that the test launcher adds or changes to its resolved value. For PATH the value is the complete resolved list, not only the added directory. The variables can also be printed from the command line as NAME=value lines:

bare-make test env

test.env() reads the build tree, so call it after generate(). It rejects with ENV_FAILED if there is no build tree at build. A build tree generated by a version before v2.1.0 records no test launcher, so its result is empty until you generate it again.

To record the launcher, generate() sets CMAKE_PROJECT_INCLUDE itself. A CMAKE_PROJECT_INCLUDE entry in define is kept and runs first, so it can change the launcher that is recorded.

Added in v2.1.1: with --sanitize address and a Clang toolchain on macOS or Linux, the variables also preload the AddressSanitizer runtime, through DYLD_INSERT_LIBRARIES on macOS and LD_PRELOAD on Linux. This is what lets a sanitized addon report bugs inside a bare that was not built with the sanitizer. Pass the variables to bare directly: the runtime removes them before it starts child processes, so exporting them in a shell does not work.

ToolchainCopy Anchor Link

bare-make ships the tools it drives. It depends on cmake-runtime, ninja-runtime, llvm-runtime, and nasm-runtime. Changed in v2.0.0: the macOS, iOS, Linux, and win32 targets use the Clang from llvm-runtime and, for the targets that assemble with NASM, the NASM from nasm-runtime, rather than a Clang and NASM found on the machine. Version 1.x used a Clang it found on the machine, such as Apple Clang on macOS. The Android targets still use the Android NDK, and the MinGW targets still use a MinGW compiler found on PATH.

The toolchain files locate llvm-runtime and nasm-runtime by running node, so node must be on PATH when you generate a build system for a target that uses them, including when bare-make itself runs on Bare. Without it, generate() rejects with GENERATE_FAILED, and CMake prints that it cannot find node, which it needs to resolve llvm-runtime. Version 1.x had no such requirement.

Added in v2.1.0: the wasi-wasm32 target, selected with platform: 'wasi' and arch: 'wasm32' (--platform wasi --arch wasm32 on the command line). The target comes from cmake-toolchains v2.1.0, which bare-make v2.1.0 is the first release to require. With an earlier cmake-toolchains, such as the one bare-make v1.8.0 uses, generate() rejects it with UNKNOWN_TOOLCHAIN. The target needs the optional wasi-sysroot package to be installed, and without it generate() rejects with GENERATE_FAILED. Executables built for it get the .wasm suffix.

Changed in v2.1.0, also through cmake-toolchains v2.1.0: the musl targets need the optional musl-sysroot package to be installed. They are selected with environment: 'musl', or 'muslsf' for the soft-float mips and mipsel targets. Earlier versions of cmake-toolchains needed a musl cross compiler, such as x86_64-linux-musl-cc, on PATH.

Compiler and linker flagsCopy Anchor Link

generate() passes the flags it adds, such as those for sanitize, fuzz, color, and the frame pointer of debug builds, through the CFLAGS, CXXFLAGS, and LDFLAGS environment variables. Changed in v2.0.0: version 1.x set the CMAKE_C_FLAGS and linker flag cache entries instead. This has three effects:

• Flags already in those variables when you call generate() are kept, and the flags bare-make adds are appended. In version 1.x the cache entries replaced them.
• The compiler flags apply to C and C++. In version 1.x they applied to C only.
• CMake reads the variables when it first configures a build tree. Calling generate() again on an existing tree with a different sanitize value, or with debug turned on, leaves its compiler and linker flags as they were, although the build type still changes. Set cache to false, or pass --no-cache, to configure the tree again with the new flags. In version 1.x the flags changed on every call.

When the target platform is win32, sanitize also passes /OPT:NOICF to the linker, because identical code folding merges identical globals, which AddressSanitizer then reports as one-definition-rule violations. Added in v2.0.1.

APICopy Anchor Link

errorsCopy Anchor Link

new errors(msg: string, code: string, fn?: MakeError)Copy Anchor Link

Construct a MakeError with the given message and code.

Parameters

errors.BUILD_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'BUILD_FAILED'.

Parameters

errors.ENV_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'ENV_FAILED'. Added in v2.1.0.

Parameters

errors.GENERATE_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'GENERATE_FAILED'.

Parameters

errors.INSTALL_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'INSTALL_FAILED'.

Parameters

errors.TEST_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'TEST_FAILED'.

Parameters

errors.UNKNOWN_TOOLCHAIN(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'UNKNOWN_TOOLCHAIN'.

Parameters

FunctionsCopy Anchor Link

build(opts?: BuildOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• BUILD_FAILED — the build exits with a non-zero status.

generate(opts?: GenerateOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• UNKNOWN_TOOLCHAIN — no toolchain is available for the resolved platform-arch target.
• GENERATE_FAILED — build system generation exits with a non-zero status.

install(opts?: InstallOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• INSTALL_FAILED — the install exits with a non-zero status.

test(opts?: TestOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• TEST_FAILED — one or more tests fail.

test.env(opts?: EnvOptions): Promise<Record<string, string>>Copy Anchor Link

Resolve the environment variables that programs from the build tree need to run, as changed by the test launcher, plus the AddressSanitizer runtime to preload into a program not built with it. Added in v2.1.0, and the AddressSanitizer runtime in v2.1.1.

Parameters

Returns Promise<Record<string, string>> — The changed variables with their resolved values.

Throws

• ENV_FAILED — the build tree does not exist or the environment cannot be resolved.

TypesCopy Anchor Link

build.BuildOptionsCopy Anchor Link

interface BuildOptions {
  build?: string
  clean?: boolean
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  target?: string
  verbose?: boolean
}

Options for build().

generate.GenerateOptionsCopy Anchor Link

interface GenerateOptions {
  arch?: string
  build?: string
  cache?: boolean
  cwd?: string
  debug?: boolean
  define?: string[]
  environment?: string
  fuzz?: boolean
  platform?: string
  preset?: string
  sanitize?: string
  simulator?: boolean
  source?: string
  stdio?: Pipe
  verbose?: boolean
  withDebugSymbols?: boolean
  withMinimalSize?: boolean
}

Options for generate(). See Compiler and linker flags for how the flag options are applied. A define entry for CMAKE_PROJECT_INCLUDE is combined with the include that generate() adds, see Environment. generate() also reads a color option (default false) that enables colored compiler diagnostics. The type declarations omit it, and the CLI sets it from --color and --no-color.

install.InstallOptionsCopy Anchor Link

interface InstallOptions {
  build?: string
  component?: string
  cwd?: string
  link?: boolean
  parallel?: boolean
  prefix?: string
  stdio?: Pipe
  strip?: boolean
  verbose?: boolean
}

Options for install().

test.TestOptionsCopy Anchor Link

interface TestOptions {
  build?: string
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  timeout?: number
  verbose?: boolean
}

Options for test().

test.EnvOptionsCopy Anchor Link

interface EnvOptions {
  build?: string
  cwd?: string
}

Options for test.env(). build is the path to the build tree, and cwd is the working directory it is resolved against.

bare-make/errorsCopy Anchor Link

MakeErrorCopy Anchor Link

new MakeError(msg: string, code: string, fn?: MakeError)Copy Anchor Link

Construct a MakeError with the given message and code.

Parameters

MakeError.BUILD_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'BUILD_FAILED'.

Parameters

MakeError.ENV_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'ENV_FAILED'. Added in v2.1.0.

Parameters

MakeError.GENERATE_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'GENERATE_FAILED'.

Parameters

MakeError.INSTALL_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'INSTALL_FAILED'.

Parameters

MakeError.TEST_FAILED(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'TEST_FAILED'.

Parameters

MakeError.UNKNOWN_TOOLCHAIN(msg: string): MakeErrorCopy Anchor Link

Create a MakeError with code 'UNKNOWN_TOOLCHAIN'.

Parameters

bare-make/buildCopy Anchor Link

FunctionsCopy Anchor Link

build.build(opts?: BuildOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• BUILD_FAILED — the build exits with a non-zero status.

TypesCopy Anchor Link

BuildOptionsCopy Anchor Link

interface BuildOptions {
  build?: string
  clean?: boolean
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  target?: string
  verbose?: boolean
}

Options for build().

bare-make/generateCopy Anchor Link

FunctionsCopy Anchor Link

generate.generate(opts?: GenerateOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• UNKNOWN_TOOLCHAIN — no toolchain is available for the resolved platform-arch target.
• GENERATE_FAILED — build system generation exits with a non-zero status.

TypesCopy Anchor Link

GenerateOptionsCopy Anchor Link

interface GenerateOptions {
  arch?: string
  build?: string
  cache?: boolean
  cwd?: string
  debug?: boolean
  define?: string[]
  environment?: string
  fuzz?: boolean
  platform?: string
  preset?: string
  sanitize?: string
  simulator?: boolean
  source?: string
  stdio?: Pipe
  verbose?: boolean
  withDebugSymbols?: boolean
  withMinimalSize?: boolean
}

Options for generate(). See Compiler and linker flags for how the flag options are applied. A define entry for CMAKE_PROJECT_INCLUDE is combined with the include that generate() adds, see Environment. generate() also reads a color option (default false) that enables colored compiler diagnostics. The type declarations omit it, and the CLI sets it from --color and --no-color.

bare-make/installCopy Anchor Link

FunctionsCopy Anchor Link

install.install(opts?: InstallOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• INSTALL_FAILED — the install exits with a non-zero status.

TypesCopy Anchor Link

InstallOptionsCopy Anchor Link

interface InstallOptions {
  build?: string
  component?: string
  cwd?: string
  link?: boolean
  parallel?: boolean
  prefix?: string
  stdio?: Pipe
  strip?: boolean
  verbose?: boolean
}

Options for install().

bare-make/testCopy Anchor Link

FunctionsCopy Anchor Link

test.test(opts?: TestOptions): Promise<void>Copy Anchor Link

Parameters

Throws

• TEST_FAILED — one or more tests fail.

test.test.env(opts?: EnvOptions): Promise<Record<string, string>>Copy Anchor Link

Resolve the environment variables that programs from the build tree need to run, as changed by the test launcher, plus the AddressSanitizer runtime to preload into a program not built with it. Added in v2.1.0, and the AddressSanitizer runtime in v2.1.1.

Parameters

Returns Promise<Record<string, string>> — The changed variables with their resolved values.

Throws

• ENV_FAILED — the build tree does not exist or the environment cannot be resolved.

TypesCopy Anchor Link

EnvOptionsCopy Anchor Link

interface EnvOptions {
  build?: string
  cwd?: string
}

Options for test.env(). build is the path to the build tree, and cwd is the working directory it is resolved against.

TestOptionsCopy Anchor Link

interface TestOptions {
  build?: string
  cwd?: string
  parallel?: number
  preset?: string
  stdio?: Pipe
  timeout?: number
  verbose?: boolean
}

Options for test().

CLICopy Anchor Link

bare-make generate [flags]Copy Anchor Link

Flags include:

--source|-s <path>                   The path to the source tree
--build|-b <path>                    The path to the build tree
--platform|-p <name>                 The operating system platform to build for
--arch|-a <name>                     The operating system architecture to build for
--simulator                          Build for a simulator
--environment|-e <name>              The environment to build for
--no-cache                           Disregard the build variable cache
--preset <name>                      The preset to use
--debug|-d                           Configure a debug build
--with-debug-symbols                 Configure a release build with debug symbols
--with-minimal-size                  Configure a release build with minimal size
--sanitize <name>                    Enable a sanitizer
--fuzz                               Configure for fuzzing
--define|-D <var>[:<type>]=<value>   Create or update a build variable cache entry
--no-color                           Disable colored output
--verbose                            Enable verbose output
--help|-h                            Show help

bare-make build [flags]Copy Anchor Link

Flags include:

--build|-b <path>        The path to the build tree
--target|-t <name>       The target to build
--clean|-c               Clean before building
--parallel|-j <number>   Build in parallel using the given number of jobs
--preset <name>          The preset to use
--verbose                Enable verbose output
--help|-h                Show help

bare-make install [flags]Copy Anchor Link

Flags include:

--build|-b <path>        The path to the build tree
--prefix|-p <path>       The prefix to install to
--component|-c <name>    The component to install
--link|-l                Link rather than copy the files
--strip|-s               Strip before installing
--parallel|-j <number>   Install in parallel using the given number of jobs
--verbose                Enable verbose output
--help|-h                Show help

bare-make test [flags]Copy Anchor Link

Flags include:

--build|-b <path>        The path to the build tree
--timeout <seconds>      The default test timeout
--parallel|-j <number>   Run tests in parallel using the given number of jobs
--preset <name>          The preset to use
--verbose                Enable verbose output
--help|-h                Show help

bare-make test env [flags]Copy Anchor Link

Print the environment that tests run with, one NAME=value line per variable. Added in v2.1.0. Flags include:

--build|-b <path>   The path to the build tree
--help|-h           Show help

See alsoCopy Anchor Link

• Builds on bare-env, bare-fs, bare-os, and bare-path.
• It drives CMake with Ninja and Clang for a consistent toolchain across platforms, while staying plain CMake underneath so you can eject.
• The CLI is installed globally via npm i -g bare-make.
• v2.0.0 dropped bare-process. The JavaScript API still runs on Bare, but the CLI is a Node.js script: run through bare, bin.js fails with MODULE_NOT_FOUND for process, which v1.8.0 resolved through bare-process.
• Bundle a Bare app — where addon compilation fits in packaging.
• bare-pack — bundles the compiled addons.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.