Bug 2653 - contradiction between docs and local.conf comments regarding parallelism options
Summary: contradiction between docs and local.conf comments regarding parallelism options
Status: RESOLVED FIXED
Alias: None
Product: Quick Start
Classification: Documentation
Component: quick-start (show other bugs)
Version: unspecified
Hardware: x86 Multiple
: Low janitors
Target Milestone: 1.3
Assignee: Scott Rifenbark
QA Contact:
URL: http://git.yoctoproject.org/cgit.cgi/...
Whiteboard: 4 Oct 2012 - Resolved/Fixed
Depends on:
Blocks:
 
Reported: 2012-06-25 02:10 UTC by Cristian Ciupitu
Modified: 2012-10-04 14:50 UTC (History)
3 users (show)

See Also:
OS type for building Yocto: ---
Type of Regression: ---
Verified:
Documentation change: ---

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Cristian Ciupitu 2012-06-25 02:10:30 UTC 
The "Configuring the local.conf File" section[1] says:

    Briefly, set BB_NUMBER_THREADS and PARALLEL_MAKE to twice your host processor's number of cores.

So a quad-core machine should have them set to 8, but the local.conf from a poky denzil build says:

    # For a quad-core machine, BB_NUMBER_THREADS = "4", PARALLEL_MAKE = "-j 4" would
    # be appropriate for example.


[1] http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html#configuring-the-local.conf-file
Comment 1 Scott Rifenbark 2012-08-23 21:53:15 UTC 
So I checked out all the areas in the YP manuals that discuss BB_NUMBER_THREADS and PARALLEL_MAKE.  Every instance in the documents (except one in a note in the Appendix B of the YP Development Manual) suggests that both these variables be set to twice the number of processors the host machine has.  This single instance where the note suggested that PARALLEL_MAKE be set at 1.5x times the number of processors is an inconsistency in the manual set.  I fixed that inconsistency so that all suggest now 2x.  

However, the local.conf file (as noted) does indeed have a suggested example of setting these variables both at 1x.  What needs to be changed is the commented example in the local.conf file.  I am unsure of what base file is used to create the local.conf file when a user runs the environment setup script.  I am guessing it is local.conf.sample (http://git.yoctoproject.org/cgit.cgi/poky/tree/meta-yocto/conf) inside meta-yocto/conf.  

I think this bug needs to be re-assigned to whoever maintains that file.  The manuals are all in line now with a suggested 2x setting for both the variables.

Scott
Comment 2 Scott Rifenbark 2012-10-04 14:50:11 UTC 
I am marking this bug fixed because the YP documentation is consistent in how it advises the user to set both BB_NUMBER_THREADS and PARALLEL_MAKE.  Every occurrence suggests 2x based on the number of cores on the development system.  Because the bug is against the documentation it is fixed. 

I did comment below in Comment 1 that the local.conf file should be fixed to also say 2x and not 4 based on a quad-core machine.  There should be a new bug opened against the local.conf file or someone should just fix it.

Scott