docs/76515: missleading use of make -j flag in handbook

[pete wright]

>Number:         76515
>Category:       docs
>Synopsis:       missleading use of make -j flag in handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 20 23:20:01 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     pete wright
>Release:        5.3-STABLE
>Organization:
nomadlogic.org
>Environment:
FreeBSD finn.nomadlogic.org 5.3-STABLE FreeBSD 5.3-STABLE #1: Tue Jan  4 19:06:52 EST 2005     root at finn.nomadlogic.org:/usr/obj/usr/src/sys/SMP  i386
>Description:
At:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
It states that:
"It is now possible to specify a -j option to make which will cause it to spawn several simultaneous processes. This is most useful on multi-CPU machines. However, since much of the compiling process is IO bound rather than CPU bound it is also useful on single CPU machines."

After testing this out on a SMP system doing a:
$ make -jN buildworld
(when "N" ranges from 1 to 8) I found that compile times do *not* decrease after starting two make jobs (make -j2 buildworld).  This was also tested by others on Uniproc machines and they did not find a decrease in time after starting one make job (make -j1 buildworld).  Here are edited results on my SMP system:

building world with 1 jobs...

real    95m20.543s
user    83m18.550s
sys     13m20.120s

cleaning /usr/src....
building world with 2 jobs...

real    54m15.856s
user    84m42.337s
sys     16m39.216s

cleaning /usr/src....
building world with 3 jobs...

real    53m53.239s
user    85m12.189s
sys     17m13.039s

cleaning /usr/src....
building world with 4 jobs...

real    53m56.539s
user    85m22.767s
sys     17m22.433s


>How-To-Repeat:
Here is the script I used to produce these results:
#!/usr/local/bin/bash
MAX=8
for ((i=1; i <= MAX ; i++))
do
        echo "cleaning /usr/src...."
        sudo make clean > /home/pete/tmp/clean
        echo "building world with $i jobs..."
        time make -j$i buildworld > /home/pete/tmp/build_world_$i
        echo ""
        sleep 90
done

>Fix:
It seems that the -j flag is usefull only in direct proportion to the amount of CPU's available to the system.  Maybe the doc should be corrected to relate this.
>Release-Note:
>Audit-Trail:
>Unformatted: