diff --git a/doc/api/_toc.md b/doc/api/_toc.md index 2527ad84e2e360..7a3aba16220f2b 100644 --- a/doc/api/_toc.md +++ b/doc/api/_toc.md @@ -2,6 +2,7 @@ @// point at the new location. * [About these Docs](documentation.html) * [Usage & Example](synopsis.html) +* [Guides](guides/index.html)
diff --git a/doc/guides/_toc.md b/doc/guides/_toc.md new file mode 100644 index 00000000000000..0972174a2b2b4a --- /dev/null +++ b/doc/guides/_toc.md @@ -0,0 +1,11 @@ +* [About the Guides](guides/about.html) + +
+ +* [Compilation](guides/compilation.md) + * [Compile Node with Ninja](guides/compilation/building-node-with-ninja.html) + +
+ +* [GitHub Repo & Issue Tracker](https://github.com/nodejs/node) +* [Mailing List](http://groups.google.com/group/nodejs) diff --git a/doc/guides/about.md b/doc/guides/about.md new file mode 100644 index 00000000000000..e69de29bb2d1d6 diff --git a/doc/guides/compilation/building-node-with-ninja.md b/doc/guides/compilation/building-node-with-ninja.md new file mode 100644 index 00000000000000..550effa976a468 --- /dev/null +++ b/doc/guides/compilation/building-node-with-ninja.md @@ -0,0 +1,39 @@ +# Building Node with Ninja + +The purpose of this guide is to show how to build Node.js using [Ninja][], as doing so can be significantly quicker than using `make`. Please see [Ninja's site][Ninja] for installation instructions (unix only). + +To build Node with ninja, there are 4 steps that must be taken: + +1. Configure the project's OS-based build rules via `./configure` as usual. +2. Use `tools/gyp_node.py -f ninja` to produce Ninja-buildable `gyp` output. +3. Run `ninja -C out/Release` to produce a compiled release binary. +4. Lastly, make symlink to `./node` using `ln -fs out/Release/node node`. + +When running `ninja -C out/Release` you will see output similar to the following if the build has succeeded: +``` +ninja: Entering directory `out/Release` +[4/4] LINK node, POSTBUILDS +``` + +The bottom line will change while building, showing the progress as `[finished/total]` build steps. +This is useful output that `make` does not produce and is one of the benefits of using Ninja. +Also, Ninja will likely compile much faster than even `make -j8` (or `-j`). + +## Considerations + +Ninja builds vary slightly from `make` builds. If you wish to run `make test` after, `make` will likely still need to rebuild some amount of Node. + +As such, if you wish to run the tests, it can be helpful to invoke the test runner directly, like so: +`tools/test.py --mode=release message parallel sequential -J` + +## Alias + +`alias nnode='./configure && tools/gyp_node.py -f ninja && ninja -C out/Release && ln -fs out/Release/node node'` + +## Producing a debug build + +The above alias can be modified slightly to produce a debug build, rather than a release build as shown below: +`alias nnodedebug='./configure && tools/gyp_node.py -f ninja && ninja -C out/Debug && ln -fs out/Debug/node node_g'` + + +[Ninja]: https://martine.github.io/ninja/ diff --git a/doc/guides/compilation/compilation.md b/doc/guides/compilation/compilation.md new file mode 100644 index 00000000000000..e69de29bb2d1d6 diff --git a/doc/guides/index.md b/doc/guides/index.md new file mode 100644 index 00000000000000..c9beaee56405c7 --- /dev/null +++ b/doc/guides/index.md @@ -0,0 +1,8 @@ +# Guides + +Welcome to the Node guides. The guides discuss high-level and more advanced +topics and is hence an extension to the API documentation. Also the format of +the guides allows for more opinionated discussion about topics of the Node and +JavaScript community, while being strictly educative. + +@include _toc.md