{"id":13671164,"url":"https://github.com/cmake-js/cmake-js","last_synced_at":"2025-05-14T10:10:17.487Z","repository":{"id":29254346,"uuid":"32786829","full_name":"cmake-js/cmake-js","owner":"cmake-js","description":"CMake.js - a Node.js native addon build tool","archived":false,"fork":false,"pushed_at":"2025-04-21T11:23:32.000Z","size":943,"stargazers_count":914,"open_issues_count":41,"forks_count":146,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-05-05T00:30:26.775Z","etag":null,"topics":["build-system","cmake","cmake-js","nodejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/cmake-js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmake-js.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-24T08:46:48.000Z","updated_at":"2025-04-21T16:40:06.000Z","dependencies_parsed_at":"2024-02-01T21:58:31.782Z","dependency_job_id":"48aa67fc-2345-4803-a96b-df43908f22e3","html_url":"https://github.com/cmake-js/cmake-js","commit_stats":{"total_commits":380,"total_committers":61,"mean_commits":6.229508196721311,"dds":"0.41315789473684206","last_synced_commit":"3922fb87993685ab49992343ae689f2f740d0b85"},"previous_names":["unbornchikken/cmake-js"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmake-js%2Fcmake-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmake-js%2Fcmake-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmake-js%2Fcmake-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmake-js%2Fcmake-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmake-js","download_url":"https://codeload.github.com/cmake-js/cmake-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253156187,"owners_count":21862847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-system","cmake","cmake-js","nodejs"],"created_at":"2024-08-02T09:01:01.426Z","updated_at":"2025-05-14T10:10:17.475Z","avatar_url":"https://github.com/cmake-js.png","language":"JavaScript","readme":"# CMake.js (MIT)\n\n[![Node CI](https://github.com/cmake-js/cmake-js/actions/workflows/node.yaml/badge.svg)](https://github.com/cmake-js/cmake-js/actions/workflows/node.yaml)\n[![npm](https://img.shields.io/npm/v/cmake-js)](https://www.npmjs.com/package/cmake-js)\n\n## About\n\nCMake.js is a Node.js native addon build tool which works (almost) _exactly_ like [node-gyp](https://github.com/TooTallNate/node-gyp), but instead of [gyp](http://en.wikipedia.org/wiki/GYP_%28software%29), it is based on [CMake](http://cmake.org) build system. It's compatible with the following runtimes:\n\n- Node.js 14.15+ since CMake.js v7.0.0 (for older runtimes please use an earlier version of CMake.js). Newer versions can produce builds targeting older runtimes\n- [NW.js](https://github.com/nwjs/nw.js): all CMake.js based native modules are compatible with NW.js out-of-the-box, there is no [nw-gyp like magic](https://github.com/nwjs/nw.js/wiki/Using-Node-modules#3rd-party-modules-with-cc-addons) required\n- [Electron](https://github.com/electron/electron): out-of-the-box build support, [no post build steps required](https://github.com/electron/electron/blob/main/docs/tutorial/using-native-node-modules.md)\n\nIf you use `node-api` for your module instead of `nan` it should be able to run on all the runtimes above without needing to be built separately for each.\n\n## Installation\n\n```bash\nnpm install cmake-js\n```\n\n**Help:**\n\n```bash\ncmake-js --help\n```\n\n```\nUsage: cmake-js [\u003ccommand\u003e] [options]\n\nCommands:\n  cmake-js install                Install Node.js distribution files if needed\n  cmake-js configure              Configure CMake project\n  cmake-js print-configure        Print the configuration command\n  cmake-js print-cmakejs-src      Print the value of the CMAKE_JS_SRC variable\n  cmake-js print-cmakejs-include  Print the value of the CMAKE_JS_INC variable\n  cmake-js print-cmakejs-lib      Print the value of the CMAKE_JS_LIB variable\n  cmake-js build                  Build the project (will configure first if\n                                  required)\n  cmake-js print-build            Print the build command\n  cmake-js clean                  Clean the project directory\n  cmake-js print-clean            Print the clean command\n  cmake-js reconfigure            Clean the project directory then configure the\n                                  project\n  cmake-js rebuild                Clean the project directory then build the\n                                  project\n  cmake-js compile                Build the project, and if build fails, try a\n                                  full rebuild\n\nOptions:\n      --version          Show version number                           [boolean]\n  -h, --help             Show help                                     [boolean]\n  -l, --log-level        set log level (silly, verbose, info, http, warn,\n                         error), default is info                        [string]\n  -d, --directory        specify CMake project's directory (where CMakeLists.txt\n                         located)                                       [string]\n  -D, --debug            build debug configuration                     [boolean]\n  -B, --config           specify build configuration (Debug, RelWithDebInfo,\n                         Release), will ignore '--debug' if specified   [string]\n  -c, --cmake-path       path of CMake executable                       [string]\n  -m, --prefer-make      use Unix Makefiles even if Ninja is available (Posix)\n                                                                       [boolean]\n  -x, --prefer-xcode     use Xcode instead of Unix Makefiles           [boolean]\n  -g, --prefer-gnu       use GNU compiler instead of default CMake compiler, if\n                         available (Posix)                             [boolean]\n  -G, --generator        use specified generator                        [string]\n  -t, --toolset          use specified toolset                          [string]\n  -A, --platform         use specified platform name                    [string]\n  -T, --target           only build the specified target                [string]\n  -C, --prefer-clang     use Clang compiler instead of default CMake compiler,\n                         if available (Posix)                          [boolean]\n      --cc               use the specified C compiler                   [string]\n      --cxx              use the specified C++ compiler                 [string]\n  -r, --runtime          the runtime to use                             [string]\n  -v, --runtime-version  the runtime version to use                     [string]\n  -a, --arch             the architecture to build in                   [string]\n  -p, --parallel         the number of threads cmake can use            [number]\n      --CD               Custom argument passed to CMake in format:\n                         -D\u003cyour-arg-here\u003e                              [string]\n  -i, --silent           Prevents CMake.js to print to the stdio       [boolean]\n  -O, --out              Specify the output directory to compile to, default is\n                         projectRoot/build                              [string]\n```\n\n**Requirements:**\n\n- [CMake](http://www.cmake.org/download/)\n- A proper C/C++ compiler toolchain of the given platform\n  - **Windows**:\n    - [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). If you installed nodejs with the installer, you can install these when prompted.\n    - An alternate way is to install the [Chocolatey package manager](https://chocolatey.org/install), and run `choco install visualstudio2017-workload-vctools` in an Administrator Powershell\n    - If you have multiple versions installed, you can select a specific version with `npm config set msvs_version 2017` (Note: this will also affect `node-gyp`)\n  - **Unix/Posix**:\n    - Clang or GCC\n    - Ninja or Make (Ninja will be picked if both present)\n\n## Usage\n\n### General\n\nIt is advised to use Node-API for new projects instead of NAN. It provides ABI stability making usage simpler and reducing maintainance.\n\n- Install cmake-js for your module `npm install --save cmake-js`\n- Put a CMakeLists.txt file into your module root with this minimal required content:\n\n```cmake\ncmake_minimum_required(VERSION 3.15...3.31)\nproject(your-addon-name-here)\n\nadd_compile_definitions(-DNAPI_VERSION=4)\n\nfile(GLOB SOURCE_FILES \"your-source files-location-here\")\n\nadd_library(${PROJECT_NAME} SHARED ${SOURCE_FILES} ${CMAKE_JS_SRC})\nset_target_properties(${PROJECT_NAME} PROPERTIES PREFIX \"\" SUFFIX \".node\")\ntarget_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_JS_INC})\ntarget_link_libraries(${PROJECT_NAME} PRIVATE ${CMAKE_JS_LIB})\ntarget_compile_features(${PROJECT_NAME} PRIVATE cxx_std_17)\n\nif(MSVC AND CMAKE_JS_NODELIB_DEF AND CMAKE_JS_NODELIB_TARGET)\n  # Generate node.lib\n  execute_process(COMMAND ${CMAKE_AR} /def:${CMAKE_JS_NODELIB_DEF} /out:${CMAKE_JS_NODELIB_TARGET} ${CMAKE_STATIC_LINKER_FLAGS})\nendif()\n```\n\n- Add the following into your package.json scripts section:\n\n```json\n\"scripts\": {\n    \"install\": \"cmake-js compile\"\n  }\n```\n\n- Add the following into your package.json, using the same NAPI_VERSION value you provided to cmake\n\n```json\n\"binary\": {\n    \"napi_versions\": [7]\n  },\n```\n\n#### Commandline\n\nWith cmake-js installed as a depdendency or devDependency of your module, you can access run commands directly with:\n\n```\nnpx cmake-js --help\n# OR\nyarn cmake-js --help\n```\n\nPlease refer to the `--help` for the lists of available commands (they are like commands in `node-gyp`).\n\nYou 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.\n\n### CMake Specific\n\n`CMAKE_JS_VERSION` variable will reflect the actual CMake.js version. So CMake.js based builds could be detected, eg.:\n\n```cmake\nif (CMAKE_JS_VERSION)\n    add_subdirectory(node_addon)\nelse()\n    add_subdirectory(other_subproject)\nendif()\n```\n\n### NPM Config Integration\n\nYou can set npm configuration options for CMake.js.\n\nFor all users (global):\n\n```\nnpm config set cmake_\u003ckey\u003e \u003cvalue\u003e --global\n```\n\nFor current user:\n\n```\nnpm config set cmake_\u003ckey\u003e \u003cvalue\u003e\n```\n\nCMake.js will set a variable named `\"\u003ckey\u003e\"` to `\u003cvalue\u003e` (by using `-D\u003ckey\u003e=\"\u003cvalue\u003e\"` option). User settings will **overwrite** globals.\n\nUPDATE:\n\nYou can set CMake.js command line arguments with npm config using the following pattern:\n\n```\nnpm config set cmake_js_G \"Visual Studio 56 Win128\"\n```\n\nWhich sets the CMake generator, basically defaults to:\n\n```\ncmake-js -G \"Visual Studio 56 Win128\"\n```\n\n#### Example:\n\nEnter at command prompt:\n\n```\nnpm config set cmake_Foo=\"bar\"\n```\n\nThen write to your CMakeLists.txt the following:\n\n```cmake\nmessage (STATUS ${Foo})\n```\n\nThis will print during configure:\n\n```\n--- bar\n```\n\n### Custom CMake options\n\nYou can add custom CMake options by beginning option name with `CD`.\n\n#### Example\n\nIn command prompt:\n\n```\ncmake-js compile --CDFOO=\"bar\"\n```\n\nThen in your CMakeLists.txt:\n\n```cmake\nmessage (STATUS ${FOO})\n```\n\nThis will print during configure:\n\n```\n--- bar\n```\n\n### Runtimes\n\n#### Important\n\nIt 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](#about). 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.\n\n#### Configuration\n\nIf any of the `runtime`, `runtimeVersion`, or `arch` configuration parameters is not explicitly configured, sensible defaults will be auto-detected based on the JavaScript environment where CMake.js runs within.\n\nYou 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.:\n\n```json\n{\n\t\"name\": \"ta-taram-taram\",\n\t\"description\": \"pa-param-pam-pam\",\n\t\"version\": \"1.0.0\",\n\t\"main\": \"app.js\",\n\t\"cmake-js\": {\n\t\t\"runtime\": \"node\",\n\t\t\"runtimeVersion\": \"0.12.0\",\n\t\t\"arch\": \"ia32\"\n\t}\n}\n```\n\nAvailable settings:\n\n- **runtime**: application's target runtime, possible values are:\n  - `node`: Node.js\n  - `nw`: nw.js\n  - `electron`: Electron\n- **runtimeVersion**: version of the application's target runtime, for example: `0.12.1`\n- **arch**: architecture of application's target runtime (eg: `x64`, `ia32`, `arm64`, `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 runtime is gonna be used, so you have to choose a matching nw.js runtime._\n\n#### Node-API and `node-addon-api`\n\n[ABI-stable Node.js API\n(Node-API)](https://nodejs.org/api/n-api.html#n_api_node_api),\nwhich was previously known as N-API, supplies a set of C\nAPIs that allow to compilation and loading of native modules by\ndifferent versions of Node.js that support Node-API which includes\nall versions of Node.js v10.x and later.\n\nTo compile a native module that uses only the\n[plain `C` Node-API calls](https://nodejs.org/api/n-api.html#n_api_node_api),\nfollow the directions for plain `node` native modules.\n\nYou must also add the following lines to your CMakeLists.txt, to allow for building on windows\n\n```\nif(MSVC AND CMAKE_JS_NODELIB_DEF AND CMAKE_JS_NODELIB_TARGET)\n  # Generate node.lib\n  execute_process(COMMAND ${CMAKE_AR} /def:${CMAKE_JS_NODELIB_DEF} /out:${CMAKE_JS_NODELIB_TARGET} ${CMAKE_STATIC_LINKER_FLAGS})\nendif()\n```\n\nTo compile a native module that uses the header-only C++ wrapper\nclasses provided by\n[`node-addon-api`](https://github.com/nodejs/node-addon-api),\nyou need to make your package depend on it with:\n\n    npm install --save node-addon-api\n\ncmake-js will then add it to the include search path automatically\n\nYou should add the following to your package.json, with the correct version number, so that cmake-js knows the module is node-api and that it can skip downloading the nodejs headers\n\n```json\n\"binary\": {\n    \"napi_versions\": [7]\n  },\n```\n\n#### Electron\n\nOn Windows, the [`win_delay_load_hook`](https://www.electronjs.org/docs/tutorial/using-native-node-modules#a-note-about-win_delay_load_hook) is required to be embedded in the module or it will fail to load in the render process.\ncmake-js will add the hook if the CMakeLists.txt contains the library `${CMAKE_JS_SRC}`.\n\nWithout the hook, the module can only be called from the render process using the Electron [remote](https://github.com/electron/electron/blob/master/docs/api/remote.md) module.\n\n#### Runtime options in CMakeLists.txt\n\nThe actual node runtime parameters are detectable in CMakeLists.txt files, the following variables are set:\n\n- **NODE_RUNTIME**: `\"node\"`, `\"nw\"`, `\"electron\"`\n- **NODE_RUNTIMEVERSION**: for example: `\"0.12.1\"`\n- **NODE_ARCH**: `\"x64\"`, `\"ia32\"`, `\"arm64\"`, `\"arm\"`\n\n#### NW.js\n\nTo make compatible your NW.js application with any NAN CMake.js based modules, write the following to your application's package.json file (this is not neccessary for node-api modules):\n\n```json\n{\n\t\"cmake-js\": {\n\t\t\"runtime\": \"nw\",\n\t\t\"runtimeVersion\": \"nw.js-version-here\",\n\t\t\"arch\": \"whatever-setting-is-appropriate-for-your-application's-windows-build\"\n\t}\n}\n```\n\nThat'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.\n\n#### Heroku\n\n[Heroku](https://heroku.com) uses the concept of a [buildpack](https://devcenter.heroku.com/articles/buildpacks) to define\nhow an application should be prepared to run in a [dyno](https://devcenter.heroku.com/articles/dynos).\nThe typical buildpack for note-based applications,\n[heroku/nodejs](https://github.com/heroku/heroku-buildpack-nodejs),\nprovides an environment capable of running [node-gyp](https://github.com/TooTallNate/node-gyp),\nbut not [CMake](http://cmake.org).\n\nThe least \"painful\" way of addressing this is to use heroku's multipack facility:\n\n- Set the applications' buildpack to\n  [https://github.com/heroku/heroku-buildpack-multi.git](https://github.com/heroku/heroku-buildpack-multi.git)\n\n- In the root directory of the application,\n  create a file called `.buildpacks` with these two lines:\n\n          https://github.com/brave/heroku-cmake-buildpack.git\n          https://github.com/heroku/heroku-buildpack-nodejs.git\n\n- Deploy the application to have the changes take effect\n\nThe `heroku-buildpack-multi` will run each buildpack in order allowing the node application to reference CMake in the Heroku\nbuild environment.\n\n## Using external C/C++ libraries\n\nBecause you are using CMake, there are many ways to load libraries in your CMakeLists.txt.  \nVarious places on the internet and in the CMake docs will suggest various approaches you can take. Common ones are:\n* [conan](https://vcpkg.io/) (This may not work properly currently, we hope to improve support in a future release)\n* [vcpkg](https://conan.io/) (This may not work properly currently, we hope to improve support in a future release)\n* [hunter](https://github.com/cpp-pm/hunter)\n* [CMake ExternalProject](https://cmake.org/cmake/help/latest/module/ExternalProject.html)\n* If on linux, using system libraries from the system package-manager\n* Importing as a git submodule\n\nWe aim to be agnostic about how to use CMake, so it should be possible to use whatever approach you desire.\n\n## Real examples\n\n- [@julusian/jpeg-turbo](https://github.com/julusian/node-jpeg-turbo) - A Node-API wrapping around libjpeg-turbo. cmake-js was a good fit here, as libjpeg-turbo provides cmake files that can be used, and would be hard to replicate correctly in node-gyp\n- [node-datachannel](https://github.com/murat-dogan/node-datachannel) - Easy to use WebRTC data channels and media transport\n- [aws-iot-device-sdk-v2](https://github.com/aws/aws-iot-device-sdk-js-v2) AWS IoT Device SDK for JavaScript v2\n\nOpen a PR to add your own project here.\n\n## Changelog\n\nView [changelog.md](changelog.md)\n\n## Credits\n\nhttps://github.com/cmake-js/cmake-js/graphs/contributors\n\nTy all!\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmake-js%2Fcmake-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmake-js%2Fcmake-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmake-js%2Fcmake-js/lists"}