A skeleton for building a C++ addon for Node.js. This is a small, helper repository that generates simple
More examples of how to port C++ libraries to node can be found at nodejs.org/api/addons.html.
This repository itself can be cloned and edited to your needs. The skeleton prepares a C++ port to Node.js and provides the following for quick development:
test/directory. Travis CI file is prepared to build and test your project on every push.
.cppfiles. Docs are located in
package.jsonthat can be deployed to NPM's registry.
make command is specified in
git clone email@example.com:mapbox/node-cpp-skel.git cd node-cpp-skel # Build binaries. This looks to see if there were changes in the C++ code. This does not reinstall deps. make # Run tests make test # Cleans your current builds and removes potential cache make clean # Build binaries in Debug mode (https://github.com/mapbox/cpp/blob/master/glossary.md#debug-build) make debug # Cleans everything, including the things you download from the network in order to compile (ex: npm packages). # This is useful if you want to nuke everything and start from scratch. # For example, it's super useful for making sure everything works for Travis, production, someone else's machine, etc make distclean # This skel uses documentation.js to auto-generate API docs. # If you'd like to generate docs for your code, you'll need to install documentation.js, # and then add your subdirectory to the docs command in package.json npm install -g firstname.lastname@example.org npm run docs
NOTE: we are pinned to
email@example.com because 5.x removed C++ support: https://github.com/documentationjs/documentation/blob/master/CHANGELOG.md#500-2017-07-27
By default we use
clang++ via mason. The reason we do this is:
The version of the clang++ binary (and related tools) is controlled by the
mason-versions.ini, and uses
mason-js uses to install the toolchain.
All that said, it is still absolutely possible and encouraged to compile your module with another compiler toolchain. In fact we hope that modules based on node-cpp-skel do this!
To customize the toolchain you can override the defaults by setting these environment variables: CXX, CC, LINK, AR, NM. For example to use g++-6 you could do:
export CXX="g++-6" export CC="gcc-6" export LINK="g++-6" export AR="ar" export NM="nm" make
These environment variables will override the compiler toolchain defaults in
make_global_settings in the
By default the build errors on compiler warnings. To disable this do:
You can run the sanitizers, to catch additional bugs, by doing:
The sanitizers are part of the compiler and are also run in a specific job on Travis.
Depending on your usecase, there are a variety of ways to start using this skeleton for your project.
Easily use this skeleton as a starting off point for a new custom project:
# Clone node-cpp-skel locally git clone firstname.lastname@example.org:mapbox/node-cpp-skel.git cd node-cpp-skel/ # Create your new repo on GitHub and have the remote repo url handy for liftoff # Then run the liftoff script from within your local node-cpp-skel root directory. # # This will: # - prompt you for the new name of your project and the new remote repo url # - automatically create a new directory for your new project repo # - create a new branch called "node-cpp-skel-port" within your new repo directory # - add, commit, and push that branch to your new repo ./scripts/liftoff.sh
Once your project has ported node-cpp-skel, follow these steps to integrate your own code:
./srcto hold your custom code. See the example code within
#includeit at the top
makeand see what surprises await on your new journey ⛵
With updated versions of npm, a
package-lock.json file is created, which is now included in node-cpp-skel. See
npm-and-package-lock.md for more info on how to interact with this file and how to add new dependencies.
Code coverage is critical for knowing how well your tests actually test all your code. To see code coverage you can view current results online at or you can build in a customized way and display coverage locally like:
For more details about what
make coverage is doing under the hood see https://github.com/mapbox/cpp#code-coverage.
Contributors are welcome! ✨ This repo exists as a place to gather C++/Node Addon knowledge that will benefit the larger community. Please contribute your knowledge if you'd like.
Node-cpp-skel is licensed under CC0. Attribution is not required, but definitely welcome! If your project uses this skeleton, please add the node-cpp-skel badge to your readme so that others can learn about the resource.
To include the badge, paste this into your README.md file: