Skip to content

Commit 5c2a6d8

Browse files
Troels Liebe Bentsentargos
Troels Liebe Bentsen
authored andcommitted
doc: add section on how to build debug build
PR-URL: #22510 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]>
1 parent f5520cc commit 5c2a6d8

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

BUILDING.md

+38
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,44 @@ To install this version of Node.js into a system directory:
253253
$ [sudo] make install
254254
```
255255

256+
#### Building a debug build
257+
258+
If you run into an issue where the information provided by the JS stack trace
259+
is not enough, or if you suspect the error happens outside of the JS VM, you
260+
can try to build a debug enabled binary:
261+
262+
```console
263+
$ ./configure --debug
264+
$ make -j4
265+
```
266+
267+
`make` with `./configure --debug` generates two binaries, the regular release
268+
one in `out/Release/node` and a debug binary in `out/Debug/node`, only the
269+
release version is actually installed when you run `make install`.
270+
271+
To use the debug build with all the normal dependencies overwrite the release
272+
version in the install directory:
273+
274+
``` console
275+
$ make install --prefix=/opt/node-debug/
276+
$ cp -a -f out/Debug/node /opt/node-debug/node
277+
```
278+
279+
When using the debug binary, core dumps will be generated in case of crashes.
280+
These core dumps are useful for debugging when provided with the
281+
corresponding original debug binary and system information.
282+
283+
Reading the core dump requires `gdb` built on the same platform the core dump
284+
was captured on (i.e. 64 bit `gdb` for `node` built on a 64 bit system, Linux
285+
`gdb` for `node` built on Linux) otherwise you will get errors like
286+
`not in executable format: File format not recognized`.
287+
288+
Example of generating a backtrace from the core dump:
289+
290+
``` console
291+
$ gdb /opt/node-debug/node core.node.8.1535359906
292+
$ backtrace
293+
```
256294

257295
### Windows
258296

0 commit comments

Comments
 (0)