How to setup Debugging Node.js C++ Add-on on Windows with Visual Studio 2017

NodeDebugWinVS2017Setup.md

How to setup Debugging Node.js C++ Add-on on Windows with Visual Studio 2017

This is a succinct step-by-step guide to setting up a debugging environment for Node.js C++ Addons.

It is based on this great article which goes into a lot more detail.

1. Build Node.js with Debug symbols enabled

NOTE: You'll need an archive utility that can handle gzip and tar extensions. I used 7-Zip

1.1 Download Node.js source tarball

• Go to the Node.js downloads page and click the Source Code link OR
• Go to https://nodejs.org/dist/v$VERISON/node-v$VERSION.tar.gz (e.g. https://nodejs.org/dist/v8.9.3/node-v8.9.3.tar.gz)
• Extract tar.gz and then extract the internal tar file (7zip seems to require that you do these operations separately - if theres a better way, sound off in the comments)

1.2 Bootstrapping Dependencies

The following instructions are from the official Node.js Bootstrapping Guide and will install the required dependencies to build Node.js with debug symbols

• Open an elevated PowerShell terminal:
  • Open Start menu
  • Type powershell
  • Right-click Windows Powershell and 'Run as Administrator'
• Paste the following and press Enter:

Set-ExecutionPolicy Unrestricted -Force
iex ((New-Object System.Net.WebClient).DownloadString('http://boxstarter.org/bootstrapper.ps1'))
get-boxstarter -Force
Install-BoxstarterPackage https://raw.githubusercontent.com/nodejs/node/master/tools/bootstrap/windows_boxstarter -DisableReboots

• (Optional) Keep the Powershell console open - I did this in case the BoxStarter/Chocolately install modified the environment in some way that wasnt persistent, this may not be necessary.

1.3 Building Node.js with debug symbols

• In your Powershell terminal change to the directory where your Node source was extracted e.g. %USERPROFILE%\Downloads\node-v8.9.3
• Run vcbuild.bat with the follow arguments:
  • vcbuild.bat debug nosign x64
• Wait... took around 10 minutes on my i7 8800k so be patient.
• Once Node is done compiling test it with > Debug\node -e "console.log('Hello from Node.js', process.version)"

2. Rebuild your addon using your debug Node.js build

• Rebuild with node-gyp pointing to your debug Node.js build:
  • node-gyp configure rebuild --debug --nodedir="%USERPROFILE%\Downloads\node-v8.9.3"
  • Note the --nodedir= argument, this is critical or node-gyp will default to the System version of Node
  • Also, note the --debug flag, without this node-gyp will look in "USERPROFILE%\Downloads\node-v8.9.3\Release for node.lib and the Linker will throw a fatal.

3. Debugging in VS2017

• You'll need to create a Js file that utilizes your addon. It could be something as simple as:

// example filename: addon.js
// Import your addon
const addon = require('./build/Debug/addon');

// Call a function exposed by your addon.
addon.myFunc();

• Navgate to your addon directory and open the build\ folder.
• Open binding.sln in VS2017
• Ensure the Run Configuration is set to Debug
• Right click your Project in the Solution Explorer and open its Properties.
• Set the Command field to the path to your newly built Node executable e.g. %USERPROFILE%\Downloads\node-v8.9.3\Debug\node.exe
• Set the Command Arguments field to the filename of your addon test script e.g. addon.js
• Set the Working Directory field to ..
• Click Apply and close the Property Pages.
• Open one of your Addon's C++ files e.g. addon.cc
• Set a breakpoint
• Hit F5 to start debugging
• Have fun!