cmake-js

What is cmake-js?

The cmake-js npm package is a tool that simplifies the process of building native C++ addons for Node.js using CMake. It provides a seamless integration between Node.js and CMake, allowing developers to leverage the powerful build system of CMake while working within the Node.js ecosystem.

What are cmake-js's main functionalities?

Building Native Addons

This feature allows you to build native C++ addons for Node.js using CMake. The code sample demonstrates how to use cmake-js to build a target named 'myAddon' in debug mode.

const cmake = require('cmake-js');

cmake.build({
  target: 'myAddon',
  debug: true
}).then(() => {
  console.log('Build complete');
}).catch(err => {
  console.error('Build failed', err);
});

Configuring Build Options

This feature allows you to configure various build options for your CMake project. The code sample shows how to set the build type to 'Release' and specify an installation prefix.

const cmake = require('cmake-js');

cmake.configure({
  CMAKE_BUILD_TYPE: 'Release',
  CMAKE_INSTALL_PREFIX: '/usr/local'
}).then(() => {
  console.log('Configuration complete');
}).catch(err => {
  console.error('Configuration failed', err);
});

Running CMake Commands

This feature allows you to run arbitrary CMake commands. The code sample demonstrates how to run a CMake build command to install the target.

const cmake = require('cmake-js');

cmake.run(['--build', '.', '--target', 'install']).then(() => {
  console.log('CMake command executed successfully');
}).catch(err => {
  console.error('CMake command failed', err);
});

Other packages similar to cmake-js

node-gyp

node-gyp is a cross-platform command-line tool written in Node.js for compiling native addon modules for Node.js. It uses the gyp build system instead of CMake. While node-gyp is widely used and well-supported, it lacks the flexibility and advanced features of CMake, which cmake-js leverages.

node-pre-gyp

node-pre-gyp is a tool that makes it easy to publish and install Node.js C++ addons from binaries. It is built on top of node-gyp and provides additional features like binary hosting and pre-built binary distribution. However, it does not offer the same level of integration with CMake as cmake-js.

neon-cli

neon-cli is a tool for building fast and safe native Node.js modules using Rust instead of C++. It provides a high-level abstraction over the Node.js C++ API and offers a more modern and safer language for writing native modules. While it is not directly comparable to cmake-js, it serves a similar purpose of enabling native module development for Node.js.

README

CMake.js (MIT)

About

CMake.js is a Node.js/io.js native addon build tool which works exactly like node-gyp, but instead of gyp, it is based on CMake build system. It's compatible with the following runtimes:

• Node.js 0.10+
• io.js
• nw.js (all CMake.js based native modules are compatible with nw.js out-of-the-box, there is no nw-gyp like magic required)

Why CMake?

Nearly every native addon is using node-gyp today, so what's wrong with it?

1. Fist of all, Google, the creator of the gyp platform is moving towards its new build system called gn, which means gyp's days of support are counted. (Just for the record, despite the announced gn switch, there is Bazel in the works, so sooner or later gn will be dropped in favor of it - IMHO.)

2. It uses Python 2 which is a huge PITA in the current century, and because of the above, there is no hope for upgrade, see: node-gyp Issue #193.

3. While gyp is very good in dependency management and project generation, it still lacks features of essential build customization
   (see: gyp wiki - Custom_build_steps).

4. Its wiki might be enough for an inhouse project, but far from what can be called for a good product documentation.

5. If you wanna port a native library to node as an addon, there is a (very-very) good chance that it doesn't use gyp for its build system, you have to make gyp binding by hand, which is really hard or nearly impossible considering the previous bulletpoint. Also you have to be an expert of the given build system and gyp to do it right.

6. There is no IDE that supports gyp as a native project format. Gyp can be used to generate IDE projects, but this is not a two way operation, if you tune your settings or setup in the IDE, you have to propagate changes back to gyp files by hand.

7. Gyp itself isn't capable to build node modules, there is fair amount custom JS code in node-gyp module to make it capable to doing so (that's why it named as Generate Your Project not Build Your Project). So supporting advanced build features like Ninja generators is impossible without extra development effort added to node-gyp (see node-gyp PR #429). It looks like node-gyp support itself eats up development resources, so there won't be new features like this added or merged in the near future. So with node-gyp you are stuck to good old Make which makes build times very long while working on large modules.

So, let's take a look at CMake compared to the above bulletpoints.

1. Cmake is quite mature and very widely used, making it quite stable and convenient. It's used by projects like Blender, LLVM, MySQL or Netflix, and it isn't likely to be abandoned in the near future.

2. It's a native software having no dependencies to any runtime.

3. Right now CMake have all of the features that was missing when development of gyp started, and on top of that it still have those features that gyp doesn't have since then. It has an own module ecosystem with internal modules, and with 3rd party gems like Compile Time Reducer (Cotire).

4. CMake have an excellent documentation, lots of tutorials, and examples.

5. If you pick a native cross platform library, there is a very good chance that is uses CMake as of its build system, or it has CMake build files somewhere, for example: Shark, Lua, SDL. If not, there are converters that helps you to create CMake files from other project formats.

6. CMake is widely supported by major cross platform C++ IDEs like: QtCreator, KDevelop and the upcoming CLion from JetBrains. With CMake.js you are gonna be able to develop Node.js addons by using those, even you have the ability to use features like integrated debugging.

7. CMake.js module doesn't build your project, CMake does. All of its commands (configure, build, clean, etc.) are simple CMake invocations without involving JS magic anywhere. Even you can print CMake command line with CMake.js module for each command (eg.: cmake-js print-configure, cmake-js print-build, cmake-js print-clean). This means supporting new features of a given native build system (like new version of Ninja or Visual Studio) won't involve developer efforts from CMake.js side, installing new versions of CMake will be enough.

Installation

npm install -g cmake-js

Help:

cmake-js --help

Requirements:

• CMake
• A proper C/C++ compiler toolchain of the given platform
  • Windows: a recent version of Visual C++ will do (the free Community version works well)
  • Unix/Posix:
    • Clang or GCC (Clang will be picked if both present)
    • Ninja or Make (Ninja will be picked if both present)

Usage

General

In a nutshell. (For more complete documentation please see the first tutorial.)

• Install cmake-js for you module npm install --save cmake-js
• Put a CMakeLists.txt file into you module root with this minimal required content:

project (your-addon-name-here)
include_directories(${CMAKE_JS_INC})
file(GLOB SOURCE_FILES "your-source files-location-here")
add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES})
set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
target_link_libraries(${PROJECT_NAME} ${CMAKE_JS_LIB})

• Add the following into your package.json scripts section:

"scripts": {
    "install": "node ./node_modules/cmake-js/bin/cmake-js rebuild"
  }

Commandline

In your module folder you can access cmake-js commands if you install cmake-js globally:

npm install -g cmake-js

Please refer to the --help for the lists of available commands (they are like commands in node-gyp).

Runtimes

You can configure runtimes for compiling target for all depending CMake.js modules in an application. Define a cmake-js key in the application's root package.json file, eg.:

{
  "name": "ta-taram-taram",
  "description": "pa-param-pam-pam",
  "version": "1.0.0",
  "main": "app.js",
  "cmake-js": {
    "runtime": "node",
    "runtimeVersion": "0.12.0",
    "arch": "ia32"
  }
}

Available settings:

• runtime: application's target runtime, possible values are:
  • node: Node.js
  • iojs: io.js
  • nw: nw.js
• runtimeVersion: version of the application's target runtime, for example: 0.12.1
• arch: architecutre of appication's target runtime (eg: x64, ia32, arm). Notice: on non-Windows systems the C++ toolset's architecture's gonna be used despite of this setting. If you don't specify this on Windows, then architecture of the main node/io.js runtime is gonna be used, so you have to choose a matching nw.js runtime.

nw.js

To make compatible your nw.js application with any CMake.js based modules, write the following to your application's package.json file:

{
  "cmake-js": {
    "runtime": "nw",
    "runtimeVersion": "nw.js-version-here",
    "arch": "whatever-setting-is-appropriate-for-your-application's-windows-build"
  }
}

That's it. There is nothing else to do either on the application's or on the module's side, CMake.js modules are compatible with nw.js out-of-the-box. For more complete documentation please see the third tutorial.

Tutorials

• TUTORIAL 01 Creating a native module by using CMake.js and NAN
• TUTORIAL 02 Creating CMake.js based native addons with Qt Creator
• TUTORIAL 03 Using CMake.js based native modules with nw.js

In the works

• Boost ;)