bug 259768: "Use optimal jobs number" highly misleading.

Do not allow 1 as a choice for number of jobs for parallel build

build/org.eclipse.cdt.managedbuilder.core/schema/buildDefinitions.exsd

@@ -1757,8 +1757,27 @@ If this attribute is not specified, MBS will assume that there are no reserved m
          <attribute name="parallelBuildCmd" type="string">
             <annotation>
                <documentation>
-                  specifies the &quot;parallel build&quot; builder option. 
+                  Specifies the command for &quot;parallel build&quot;.
-If the builder supports specifying custom number of parallel jobs, the option definition may contain &quot;*&quot; the Build System sill substitute the &quot;*&quot; with the number of parallel threads to be used.
+If the builder supports specifying custom number of parallel jobs the option definition may contain &quot;*&quot;. The Build System will substitute the &quot;*&quot; with the number of parallel threads to be used. In case of &quot;unlimited&quot; jobs jobs number will be omitted.
+For example, builder representing GNU make would define parallelBuildCmd as &quot;-j*&quot;.
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="parallelBuildOn" type="boolean">
+            <annotation>
+               <documentation>
+                  Defines if the parallel build is enabled in newly created project by default (when parallel build is supported). The number of jobs is defined by &quot;parallelizationNumber&quot; attribute. If &quot;parallelizationNumber&quot; is not defined &quot;optimal&quot; value will be used.
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="parallelizationNumber" type="string">
+            <annotation>
+               <documentation>
+                  Sets maximum number of parallel threads/jobs to be used by builder (that value can be changed after creation of project by user).
+A positive number or value &quot;optimal&quot; or &quot;unlimited&quot; are recognized:
+- number 1 will cause parallel build to be turned off,
+- &quot;optimal&quot; will set maximum number of jobs to number of processors on the system,
+- &quot;unlimited&quot; will make builder to run as many threads/jobs as possible.
                </documentation>
             </annotation>
          </attribute>

build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/core/IBuilder.java

@@ -80,12 +80,12 @@ public interface IBuilder extends IHoldsOptions, IMakeBuilderInfo {
 	static final String ATTRIBUTE_STOP_ON_ERR = "stopOnErr"; //$NON-NLS-1$
 	
 	static final String ATTRIBUTE_PARALLEL_BUILD_CMD = "parallelBuildCmd"; //$NON-NLS-1$
+	static final String ATTRIBUTE_PARALLEL_BUILD_ON = "parallelBuildOn"; //$NON-NLS-1$
 	static final String ATTRIBUTE_PARALLELIZATION_NUMBER = "parallelizationNumber"; //$NON-NLS-1$
 	/** @since 8.1 */
 	static final String VALUE_OPTIMAL = "optimal"; //$NON-NLS-1$
 	/** @since 8.1 */
 	static final String VALUE_UNLIMITED = "unlimited"; //$NON-NLS-1$
-	static final String ATTRIBUTE_PARALLEL_BUILD_ON = "parallelBuildOn"; //$NON-NLS-1$
 	static final String PARALLEL_PATTERN_NUM = "*"; //$NON-NLS-1$
 	static final String PARALLEL_PATTERN_NUM_START = "["; //$NON-NLS-1$
 	static final String PARALLEL_PATTERN_NUM_END = "]"; //$NON-NLS-1$

build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/core/IMultiConfiguration.java

@@ -49,11 +49,8 @@ public interface IMultiConfiguration extends IConfiguration, ICMultiItemsHolder
 
 	/**
 	 * Sets maximum number of parallel threads/jobs to be used by each builder.
-	 * Note that the number will be set only if the builder is in "parallel"
-	 * mode.
 	 * 
-	 * @param jobs - maximum number of jobs or threads. If the number is 0
+	 * @param jobs - maximum number of jobs or threads, see for more details
-	 *    or negative, negative "optimal" number will be set, see
 	 *    {@link Builder#getOptimalParallelJobNum()}.
 	 */
 	void setParallelNumber(int jobs);

build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/internal/core/Builder.java

@@ -567,7 +567,7 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 			isParallelBuildEnabled = Boolean.valueOf(tmp);
 			if (isParallelBuildEnabled) {
 				tmp = element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER);
-				decodeParallelizationNumber(element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER));
+				setParallelizationNumAttribute(decodeParallelizationNumber(element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER)));
 			}
 		}
 
@@ -630,29 +630,31 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 		return jobsNumber.toString();
 	}
 
-	private void decodeParallelizationNumber(String value) {
+	private int decodeParallelizationNumber(String value) {
+		int parallelNumber = -1;
 		if (VALUE_OPTIMAL.equals(value)) {
-			parallelNumberAttribute = -getOptimalParallelJobNum();
+			parallelNumber = -getOptimalParallelJobNum();
 		} else if (VALUE_UNLIMITED.equals(value)) {
-			parallelNumberAttribute = UNLIMITED_JOBS;
+			parallelNumber = UNLIMITED_JOBS;
 		} else {
 			try {
-				parallelNumberAttribute = Integer.decode(value);
+				parallelNumber = Integer.decode(value);
 			} catch (NumberFormatException e) {
 				ManagedBuilderCorePlugin.log(e);
-				parallelNumberAttribute = getOptimalParallelJobNum();
+				parallelNumber = getOptimalParallelJobNum();
 			}
-			if (parallelNumberAttribute <= 0) {
+			if (parallelNumber <= 0) {
 				// compatibility with legacy representation - it was that inconsistent
 				if (isInternalBuilder()) {
 					// "optimal" for Internal Builder
-					parallelNumberAttribute = -getOptimalParallelJobNum();
+					parallelNumber = -getOptimalParallelJobNum();
 				} else {
 					// unlimited for External Builder
-					parallelNumberAttribute = UNLIMITED_JOBS;
+					parallelNumber = UNLIMITED_JOBS;
 				}
 			}
 		}
+		return parallelNumber;
 	}
 
 	/**
@@ -798,7 +800,7 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 			isParallelBuildEnabled = Boolean.valueOf(tmp);
 			if (isParallelBuildEnabled) {
 				tmp = element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER);
-				decodeParallelizationNumber(element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER));
+				setParallelizationNumAttribute(decodeParallelizationNumber(element.getAttribute(ATTRIBUTE_PARALLELIZATION_NUMBER)));
 			}
 		}
 
@@ -2526,7 +2528,7 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 	/**
 	 * Returns the internal representation of maximum number of parallel jobs
 	 * to be used for a build.
-	 * Note that "optimal" value is represented by negative number.
+	 * Note that negative number represents "optimal" value.
 	 * 
 	 * The value of the number is encoded as follows:
 	 * <pre>
@@ -2549,15 +2551,36 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 		}
 		return parallelNumberAttribute.intValue();
 	}
-	
+
+	private void setParallelizationNumAttribute(int parallelNumber) {
+		isParallelBuildEnabled = (parallelNumber != 1);
+		if (parallelNumber > 0) {
+			parallelNumberAttribute = parallelNumber;
+		} else {
+			// "optimal"
+			parallelNumberAttribute = -getOptimalParallelJobNum();
+		}
+	}
+
 	@Override
 	public int getParallelizationNum() {
 		return Math.abs(getParallelizationNumAttribute());
 	}
 
+	/**
+	 * {@inheritDoc}
+	 * 
+	 * @param jobs - maximum number of jobs. There are 2 special cases:
+	 *    <br>- any number <=0 is interpreted as setting "optimal" property,
+	 *    the value of the number itself is ignored in this case
+	 *    <br>- value 1 will turn parallel mode off.
+	 */
 	@Override
 	public void setParallelizationNum(int jobs) throws CoreException {
-		if (isParallelBuildOn() && (parallelNumberAttribute == null || parallelNumberAttribute != jobs)) {
+		if (!supportsParallelBuild())
+			return;
+
+		if (parallelNumberAttribute == null || parallelNumberAttribute != jobs) {
 			String curCmd = getParallelizationCmd(getParallelizationNum());
 			String args = getArgumentsAttribute();
 			String updatedArgs = removeCmd(args, curCmd);
@@ -2565,12 +2588,7 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 				setArgumentsAttribute(updatedArgs);
 			}
 
-			if (jobs > 0) {
+			setParallelizationNumAttribute(jobs);
-				parallelNumberAttribute = jobs;
-			} else {
-				// "optimal"
-				parallelNumberAttribute = -getOptimalParallelJobNum();
-			}
 			setDirty(true);
 		}
 	}
@@ -2620,6 +2638,9 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 
 	@Override
 	public boolean isParallelBuildOn() {
+		if (!supportsParallelBuild()) {
+			return false;
+		}
 		if (isParallelBuildEnabled == null) {
 			if (superClass != null) {
 				return getSuperClass().isParallelBuildOn();
@@ -2639,27 +2660,12 @@ public class Builder extends HoldsOptions implements IBuilder, IMatchKeyProvider
 	 */
 	@Override
 	public void setParallelBuildOn(boolean on) throws CoreException {
-		if (isParallelBuildOn() == on)
+		if (on) {
-			return;
+			// set "optimal" jobs by default when enabling parallel build
-		if (on && !supportsParallelBuild())
+			setParallelizationNum(-1);
-			return;
-
-		String curCmd = getParallelizationCmd(getParallelizationNum());
-		String args = getArgumentsAttribute();
-		String updatedArgs = removeCmd(args, curCmd);
-		if (!updatedArgs.equals(args)) {
-			setArgumentsAttribute(updatedArgs);
-		}
-
-		isParallelBuildEnabled = on;
-
-		if (isParallelBuildEnabled) {
-			// "optimal"
-			parallelNumberAttribute = -getOptimalParallelJobNum();
 		} else {
-			parallelNumberAttribute = 1;
+			setParallelizationNum(1);
 		}
-		setDirty(true);
 	}
 
 	public Set<String> contributeErrorParsers(Set<String> set){

build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/internal/core/Configuration.java

@@ -2268,12 +2268,9 @@ public class Configuration extends BuildObject implements IConfiguration, IBuild
 	
 	/**
 	 * Sets maximum number of parallel threads/jobs to be used by builder.
-	 * Note that the number will be set only if the builder is in "parallel"
-	 * mode.
 	 * 
-	 * @param jobs - maximum number of jobs or threads. If the number is 0
+	 * @param jobs - maximum number of jobs or threads. For details how
-	 *    or negative, "optimal" number will be set,
+	 *    the number is interpreted see {@link Builder#setParallelizationNum(int)}.
-	 *    see {@link Builder#getOptimalParallelJobNum()}.
 	 */
 	public void setParallelNumber(int jobs){
 		try {

build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/newmake/core/IMakeCommonBuildInfo.java

@@ -50,12 +50,10 @@ public interface IMakeCommonBuildInfo {
 
 	/**
 	 * Sets maximum number of parallel threads/jobs to be used by builder.
-	 * Note that the number will be set only if the builder is in "parallel"
+	 * Note that this number can be interpreted by builder in a special way.
-	 * mode.
+	 * @see Builder#setParallelizationNum(int)
 	 * 
 	 * @param jobs - maximum number of jobs.
-	 *    Any number <=0 is treated as setting "optimal" property,
-	 *    the value of the number itself is ignored in this case.
 	 */
 	void setParallelizationNum(int jobs) throws CoreException;
 

build/org.eclipse.cdt.managedbuilder.ui/src/org/eclipse/cdt/managedbuilder/ui/properties/BuildBehaviourTab.java

@@ -53,6 +53,7 @@ import org.eclipse.swt.widgets.Widget;
  */
 public class BuildBehaviourTab extends AbstractCBuildPropertyTab {
 	private static final int SPINNER_MAX_VALUE = 10000;
+	private static final int SPINNER_MIN_VALUE = 2;
 	
 	private static final int TRI_STATES_SIZE = 4;
 	// Widgets
@@ -153,7 +154,7 @@ public class BuildBehaviourTab extends AbstractCBuildPropertyTab {
 
 		s_parallelNumber = new Spinner(c3, SWT.BORDER);
 		setupControl(s_parallelNumber, 1, GridData.BEGINNING);
-		s_parallelNumber.setValues(cpuNumber, 1, SPINNER_MAX_VALUE, 0, 1, 10);
+		s_parallelNumber.setValues(cpuNumber, SPINNER_MIN_VALUE, SPINNER_MAX_VALUE, 0, 1, 10);
 		s_parallelNumber.addSelectionListener(new SelectionAdapter () {
 			@Override
 			public void widgetSelected(SelectionEvent e) {
@@ -299,7 +300,7 @@ public class BuildBehaviourTab extends AbstractCBuildPropertyTab {
 					bldr.supportsStopOnError(true) &&
 					bldr.supportsStopOnError(false));
 		}
-		
+
 
 		updateParallelBlock();