diff --git a/doc/contributing/investigating_native_memory_leak.md b/doc/contributing/investigating_native_memory_leak.md index 8c193d1285fe29..fba03a1ed9a7cf 100644 --- a/doc/contributing/investigating_native_memory_leak.md +++ b/doc/contributing/investigating_native_memory_leak.md @@ -1,14 +1,14 @@ -# Investigating memory leaks with valgrind +# Investigating memory leaks with Valgrind A Node.js process may run out of memory due to excessive consumption of native memory. Native Memory is memory which is not managed by the V8 Garbage collector and is allocated either by the Node.js runtime, its dependencies or native [addons](https://nodejs.org/docs/latest/api/n-api.html). -This guide provides information on how to use valgrind to investigate these +This guide provides information on how to use Valgrind to investigate these issues on Linux platforms. -## valgrind +## Valgrind [Valgrind](https://valgrind.org/docs/manual/quick-start.html) is a tool available on Linux distributions which can be used to investigate @@ -16,9 +16,9 @@ memory usage including identifying memory leaks (memory which is allocated and not freed) and other memory related problems like double freeing memory. -To use valgrind: +To use Valgrind: -* Be patient, running under valgrind slows execution significantly +* Be patient, running under Valgrind slows execution significantly due to the checks being performed. * Reduce your test case to the smallest reproduce. Due to the slowdown it is important to run the minimum test case in order to be able to do it in @@ -35,7 +35,7 @@ apt-get install valgrind ## Invocation -The simplest invocation of valgrind is: +The simplest invocation of Valgrind is: ```console valgrind node test.js @@ -317,7 +317,7 @@ From the stack trace we can tell that the leak came from a native addon: What we can't tell is where in the native addon the memory is being allocated. This is because by default the addon is compiled without -the debug symbols which valgrind needs to be able to provide more +the debug symbols which Valgrind needs to be able to provide more information. ## Enabling debug symbols to get more information @@ -345,7 +345,7 @@ npm install --debug npm rebuild ``` -The next step is to run valgrind after the rebuild. This time the information +The next step is to run Valgrind after the rebuild. This time the information for the leaking location includes the name of the source file and the line number: @@ -409,7 +409,7 @@ its symbols using `-rdynamic` so that they can be used by addons. If the stack gives you enough information to track down where the leak is, that's great, otherwise the next step is to compile a debug build of Node.js. -To get additional information with valgrind: +To get additional information with Valgrind: * Check out the Node.js source corresponding to the release that you want to debug. For example: @@ -432,7 +432,7 @@ make -j4 `./configure --debug`, two binaries will have been built when `make` was run. You must use the one which is in `out/Debug`. -Running valgrind using the debug build of Node.js shows: +Running Valgrind using the debug build of Node.js shows: ```console ==44112== 592 bytes in 1 blocks are possibly lost in loss record 26 of 27 diff --git a/doc/contributing/maintaining-the-build-files.md b/doc/contributing/maintaining-the-build-files.md index 67c86281c63ed4..e1d3fa6e04969f 100644 --- a/doc/contributing/maintaining-the-build-files.md +++ b/doc/contributing/maintaining-the-build-files.md @@ -13,17 +13,17 @@ There are three main build files that may be directly run when building Node.js: create platform-dependent build files. Its output is usually in one of these formats: Makefile, MSbuild, ninja, or XCode project files (the main Makefile mentioned below is maintained separately by humans). For a detailed - guide on this script, see [configure](#configure). + guide on this script, see [configure][]. * `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a - subset of the targets available in the [Makefile](#makefile), and a few + subset of the targets available in the [Makefile][], and a few targets of its own. For a detailed guide on this script, see [vcbuild.bat](#vcbuildbat). * `Makefile`: A Makefile that can be run with GNU Make. It provides a set of targets that build and test the Node.js binary, produce releases and documentation, and interact with the CI to run benchmarks or tests. For a - detailed guide on this file, see [Makefile](#makefile). + detailed guide on this file, see [Makefile][]. -On Windows `vcbuild.bat` runs [configure](#configure) before building the +On Windows `vcbuild.bat` runs [configure][] before building the Node.js binary, on other systems `configure` must be run manually before running `make` on the `Makefile`. @@ -58,3 +58,5 @@ maintained by humans. This is not usually run on Windows, where of this option. [GYP]: https://gyp.gsrc.io/docs/UserDocumentation.md +[Makefile]: #makefile +[configure]: #configure diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/contributing/maintaining-types-for-nodejs.md index 5cc52bd6ce931e..ea7fbf46c44942 100644 --- a/doc/contributing/maintaining-types-for-nodejs.md +++ b/doc/contributing/maintaining-types-for-nodejs.md @@ -1,11 +1,11 @@ # Maintaining types for Node.js While JavaScript is an untyped language, there are a number of complementary -technologies like [TypeScript](https://www.typescriptlang.org/) and -[Flow](https://flow.org/) which allow developers to use types within their +technologies like [TypeScript][] and +[Flow][] which allow developers to use types within their JavaScript projects. While many people don't use types, there are enough who do that the project has agreed it's important to work towards having -[suitable types for end-users](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#suitable-types-for-end-users). +[suitable types for end-users][]. ## High level approach @@ -14,7 +14,7 @@ from shipping them with the Node.js runtime to having them be externally maintained. The different options were discussed as part of the -[next-10](https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#suitable-types-for-end-users) +[next-10][] effort and it was agreed that maintaining them externally is the best approach. Some of the advantages to this approach include: @@ -34,22 +34,22 @@ The agreement was that the ideal flow would be as follows: When you run `make doc` the canonical markdown files used to document the Node.js APIs in the -[doc/api](https://github.com/nodejs/node/tree/master/doc/api) +[doc/api][] directory are converted to both an `.html` file and a `.json` file. As part of the regular build/release process both the `html` and -`json` files are published to [nodejs.org](https://nodejs.org/en/docs/). +`json` files are published to [nodejs.org][]. The generator that does the conversion is in the -[tools/doc](https://github.com/nodejs/node/tree/master/tools/doc) +[tools/doc][] directory. ## Markdown structure The constraints required on the markdown files in the -[doc/api](https://github.com/nodejs/node/tree/master/doc/api) directory +[doc/api][] directory in order to be able to generate the JSON files are defined in the -[documentation-style-guide](https://github.com/nodejs/node/blob/master/doc/README.md#documentation-style-guide). +[documentation-style-guide][]. ## Planned changes (as of Jan 1 2022) @@ -61,3 +61,12 @@ afterwards. There is an ongoing effort to add additional markdown constraints and then update the flow in order to be able to generate a better JSON output. + +[doc/api]: https://github.com/nodejs/node/tree/master/doc/api +[documentation-style-guide]: https://github.com/nodejs/node/blob/master/doc/README.md#documentation-style-guide +[tools/doc]: https://github.com/nodejs/node/tree/master/tools/doc +[nodejs.org]: https://nodejs.org/en/docs/ +[next-10]: https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#suitable-types-for-end-users +[suitable types for end users]: https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#suitable-types-for-end-users +[Flow]: https://flow.org/ +[TypeScript]: https://www.typescriptlang.org/