Document that ninja should be run with ninja -j1 or cmake --build . --parallel 1

[traversaro]

Historically, we never documented the use of Ninja with the superbuild as:

• It did not worked on Windows (fixed in Fix support for building on Windows with Ninja #1682)
• It made the build run out of RAM

The second point happens has by default ninja uses N threads (where N is the number of cores of the machine) and in the case of the superbuild each thread builds a subproject, that itself is build with ninja that by default uses N threads, that results in N^2 compilation threads running that do not speed up the compilation (as they are much higher then the number of cores, so they lead to frequent context switch that increase the overhead) and even works they really frequently finish the RAM of the machine.

If you want to use ninja, a better strategy is to run with just one thread, i.e. ninja -j1 or cmake --build . --parallel 1. In this way, you launch a subproject at the time, and as of CMake 3.30 the -j1 setting is not passed down to the subproject, so each subproject instead uses N compilation threads, resulting in a speed up anyhow w.r.t. to a single thread build.

Today discussing with @giotherobot I realized that this may not be a well-known information, so we may want to document it somewhere.