Number of processes used by 'make' should not be specified in documentation

[thecoolestguy]

• v6.4.0
• Darwin 14.5.0
• doc

In several of the documentation files, the number of simultaneous jobs is specified by the -j option and the number varies between files. According to the 'make' man page, "If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously." The documentation should just have a '-j' without a number, so as to remain system-agnostic.

The files in which this issue resides are as follows:

https://github.com/nodejs/node/blob/master/doc/onboarding.md
https://github.com/nodejs/node/blob/master/doc/onboarding-extras.md
https://github.com/nodejs/node/blob/master/doc/guides/building-node-with-ninja.md
https://github.com/nodejs/node/blob/master/CONTRIBUTING.md
https://github.com/nodejs/node/blob/master/.github/PULL_REQUEST_TEMPLATE.md

[Trott]

Running make clean && make distclean && ./configure && make -j puts the load on my machine way up...it peaked in the high 200s, and then build failed with:

make[1]: *** wait: No child processes.  Stop.

Probably best bet is to just standardize everything on make -j8. Smallest changeset too. Just one file.

[addaleax]

According to the 'make' man page, "If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously."

That is a very good reason not to recommend -j – when hundreds of tasks can run in parallel, make will allow that with -j, as @Trott observed. I’d be surprised if there were any circumstances under which that would not either crash or freeze the system? 😄

make -j8 sounds fine, people who know what that “magic” 8 means could still use something else.

[jasnell]

I always turn my -j up to 11.

[silverwind]

I'd rather not recommend -j at all.

BTW: Wouldn't something like make -j $(nproc) be ideal in most cases? (Linux only)

[Trott]

I think any of the following would be a slight improvement over the current situation:

• standardize all docs on -j8
• standardize all docs on -j4
• standardize all docs to not mentioning -j option; advanced users will already know about it and what to do with it
• standardize all docs to not use -j in initial examples but to sometimes include an optional explanation (one or two sentences) of the -j option where it makes sense; for example, it probably makes sense in the BUILDING.md doc; it probably is OK to omit in the .github template where brevity is important

[Fishrock123]

I think we should standardize -j4. Easy enough on most laptops, and means newcomers have a better experience. Anyone who knows more about it can adjust it to their liking.

(Note: I use -j8. I also have an i7 processor.)

[mhdawson]

We had problems in the release CI where -j was specified, causing failures due to the high load so we definitely don't want -j. What we really want is -j $(NUM_CPUS) but that might be a bit wordy to explain properly.

[bnoordhuis]

On most UNIX-y systems you can write make -j$(getconf _NPROCESSORS_ONLN). Still a bit wordy though.

[Trott]

@thecoolestguy It seems like there are a lot of options here, none of which is the clear frontrunner for consensus. However, all seem better than the current situation.

I'd recommend reading the discussion here, picking the option you are most convinced of, and updating your pull request appropriately. While I have my preference, I can live with any of the alternatives discussed and I'd rather see one land than have it stall out due to a lack of clear consensus.

I suspect others will feel the same way as the one thing we do have consensus about is that the current docs about make options can be improved.