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.
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);
});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 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 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.
First of all, thanks for the PRs! Keep'em comm=ing! I try to verify and release stuff as fast as I can. So, you should not bother to compile and include ES5 files along with your PRs, generating them is the part of the release process.
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:
Nearly every native addon is using node-gyp today, so what's wrong with it?
First 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.)
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.
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).
Its wiki might be enough for an in-house project, but far from what can be called for a good product documentation.
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.
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.
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 bullet points.
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.
It's native software, having no dependencies to any runtime.
Right now CMake has all of the features that were missing when development of gyp started, and on top of that it still has those features that gyp didn't have since then. It has an own module ecosystem with internal modules, and with 3rd party gems like Compile Time Reducer (Cotire).
CMake has excellent documentation, lots of tutorials, and examples.
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.
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.
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.
npm install -g cmake-js
Help:
cmake-js --help
Usage: cmake-js [<command>] [options]
Commands:
install Install Node.js/io.js distribution files if needed
configure Configure CMake project
print-configure Print the configuration command
build Build the project (will configure first if required)
print-build Print the build command
clean Clean the project directory
print-clean Print the clean command
reconfigure Clean the project directory then configure the project
rebuild Clean the project directory then build the project
compile Build the project, and if build fails, try a full rebuild
Options:
--version Show version number [boolean]
-h, --help show this screen [boolean]
-l, --log-level set log level (silly, verbose, info, http, warn,
error), default is info [string]
-d, --directory specify CMake project's directory (where CMakeLists.txt
located) [string]
-D, --debug build debug configuration [boolean]
-c, --cmake-path path of CMake executable [string]
-m, --prefer-make use Unix Makefiles even if Ninja is available (Posix)
[boolean]
-x, --prefer-xcode use Xcode instead of Unix Makefiles [boolean]
-g, --prefer-gnu use GNU compiler instead of default CMake compiler, if
available (Posix) [boolean]
-G, --generator use specified generator [string]
-t, --toolset use specified toolset [string]
-T, --target only build the specified target [string]
-C, --prefer-clang use Clang compiler instead of default CMake compiler,
if available (Posix) [boolean]
-r, --runtime the runtime to use [string]
-v, --runtime-version the runtime version to use [string]
-a, --arch the architecture to build in [string]
--CD Custom argument passed to CMake in format:
-D<your-arg-here> [string]
-i, --silent Prevents CMake.js to print to the stdio [boolean]
-O, --out Specify the output directory to compile to, default is
projectRoot/build [string]
projectRoot/build [string]
Requirements:
In a nutshell. (For more complete documentation please see the first tutorial.)
npm install --save cmake-jsproject (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} ${CMAKE_JS_SRC})
set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
target_link_libraries(${PROJECT_NAME} ${CMAKE_JS_LIB})
"scripts": {
"install": "cmake-js compile"
}
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).
You can override the project default runtimes via --runtime and --runtime-version, such as: --runtime=electron --runtime-version=0.26.0. See below for more info on runtimes.
CMAKE_JS_VERSION variable will reflect the actual CMake.js version. So CMake.js based builds could be detected, eg.:
if (CMAKE_JS_VERSION)
add_subdirectory(node_addon)
else()
add_subdirectory(other_subproject)
endif()
You can set npm configuration options for CMake.js.
For all users (global):
npm config set cmake_<key> <value> --global
For current user:
npm config set cmake_<key> <value>
CMake.js will set a variable named "<key>" to <value> (by using -D<key>="<value>" option). User settings will overwrite globals.
UPDATE:
You can set CMake.js command line arguments with npm config using the following pattern:
npm config set cmake_js_G "Visual Studio 56 Win128"
Which sets the CMake generator, basically defaults to:
cmake-js -G "Visual Studio 56 Win128"
Enter at command prompt:
npm config set cmake_BuBu="kittyfck"
Then write to your CMakeLists.txt the following:
message (STATUS ${BuBu})
This will print during configure:
--- kittyfck
You can add custom CMake options by beginning option name with CD.
In command prompt:
cmake-js compile --CDBUBU="kittyfck"
Then in your CMakeLists.txt:
message (STATUS ${BUBU})
This will print during configure:
--- kittyfck
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:
node: Node.jsnw: nw.jselectron: Electron0.12.1x64, ia32, arm). Notice: on non-Windows systems the C++ toolset's architecture's gonna be used despite 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.The actual node runtime parameters are detectable in CMakeLists.txt files, the following variables are set:
"node", "nw", "electron""0.12.1""x64", "ia32", "arm"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.
To make compatible your Electron application with any CMake.js based modules, write the following to your application's package.json file:
{
"cmake-js": {
"runtime": "electron",
"runtimeVersion": "electron-runtime-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 Electron out-of-the-box.
Currently Electron (V1.4.x+) can only call modules built using CMake.js from the main process. To call such a module from a render process use the Electron remote module in your require statement:
var yourModule = require('electron').remote.require('pathToYourModule/cmakeModuleName.node')
It is important to understand that this setting is to be configured in the application's root package.json file. If you're creating a native module targeting nw.js for example, then do not specify anything in your module's package.json. It's the actual application's decision to specify its runtime, your module's just compatible anything that was mentioned in the About chapter. Actually defining cmake-js key in your module's package.json file may lead to an error. Why? If you set it up to use nw.js 0.12.1 for example, then when it gets compiled during development time (to run its unit tests for example) it's gonna be compiled against io.js 1.2 runtime. But if you're having io.js 34.0.1 at the command line then, which is binary incompatible with 1.2, then your unit tests will fail for sure. So it is advised to not use cmake-js target settings in your module's package.json, because that way CMake.js will use that you have, and your tests will pass.
Heroku uses the concept of a buildpack to define how an application should be prepared to run in a dyno. The typical buildpack for note-based applications, heroku/nodejs, provides an environment capable of running node-gyp, but not CMake.
The least "painful" way of addressing this is to use heroku's multipack facility:
Set the applications' buildpack to https://github.com/heroku/heroku-buildpack-multi.git
In the root directory of the application,
create a file called .buildpacks with these two lines:
https://github.com/brave/heroku-cmake-buildpack.git
https://github.com/heroku/heroku-buildpack-nodejs.git
Deploy the application to have the changes take effect
The heroku-buildpack-multi will run each buildpack in order allowing the node application to reference CMake in the Heroku
build environment.
node-addon-apiABI-stable Node.js API
(N-API) are a set of experimental C
APIs that allow to compile a native module and have it loaded by
different versions of Node.js that provide the N-API. At the moment,
only Node.js v8.0.0 implements and exports N-API symbols under the flag
--napi-modules:
node --napi-modules index.js
To compile a native module that uses only the
plain C N-API calls,
follow the directions for plain node native modules.
To compile a native module that uses the header-only C++ wrapper
classes provided by
node-addon-api,
you need at the moment to make your package depend on it with
npm install --save-dev node-addon-api
and add it to the include directories of your CMake project file
CMakeLists.txt:
# Include N-API wrappers
execute_process(COMMAND node -p "require('node-addon-api').include"
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
OUTPUT_VARIABLE NODE_ADDON_API_DIR
)
string(REPLACE "\n" "" NODE_ADDON_API_DIR ${NODE_ADDON_API_DIR})
string(REPLACE "\"" "" NODE_ADDON_API_DIR ${NODE_ADDON_API_DIR})
target_include_directories(${PROJECT_NAME} PRIVATE ${NODE_ADDON_API_DIR})
I'm working on the Node.js port of the awesome ArrayFire CPU/GPU computing library, please follow its status in its repo: ArrayFire.js.
View changelog.md
v5.3.0 - 09/07/19
FAQs
CMake.js - a Node.js native addon build tool
The npm package cmake-js receives a total of 174,702 weekly downloads. As such, cmake-js popularity was classified as popular.
We found that cmake-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.