[-j maxjobs]

-j maxjobs Set the maximum number of targets that can be updated concurrently. If this option is specified multiple times, the last value of maxjobs specified shall take precedence. If this option is not specified, or if maxjobs is 1, only one target shall be updated at a time (no parallelization). If the value of maxjobs is non-positive, the behavior is unspecified. When this option is specified with maxjobs greater than 1 and a rule invokes make (perhaps via <tt>$(MAKE)</tt>), the parent make shall attempt to establish communication with the child make in an unspecified manner, possibly via an implementation-specific flag in MAKEFLAGS. If the -j option is passed to the child make via the MAKEFLAGS environment variable with the same maxjobs value as the parent and is not overridden by a maxjobs value from another source (even if it has the same value), the child make shall establish communication with the parent make before it attempts to update any targets. In all other cases it is unspecified whether the child make establishes communication with the parent make. The parent make and any children it is communicating with, recursively, shall between them update no more than maxjobs targets in parallel. Implementations are permitted to silently limit maxjobs to an unspecified positive value; if this limit is 1, make need not attempt to establish communication with a child make.

The make utility shall treat all prerequisites as targets themselves and recursively ensure that they are up-to-date, processing them in the order in which they appear in the rule. The make utility shall use the modification times of files to determine whether the corresponding targets are out-of-date.

The make utility shall treat all prerequisites as targets themselves and recursively ensure that they are up-to-date, using the modification times of files to determine whether the corresponding targets are out-of-date. If the -j option is not specified, a rule's prerequisites shall be processed in the order in which they appear in the rule. If targets are being updated in parallel (see -j in OPTIONS), the order of processing of prerequisites is unspecified except the make utility shall ensure that all of a prerequisite's own prerequisites are up-to-date before the prerequisite itself is made up-to-date.

Syntax supporting parallel execution (such as from various multi-processor vendors, GNU, and others)

Some implementations of make allow omission of the option-argument for the -j option, although not in the manner described in item 2.b in [xref to XBD 12.1] (where the option-argument, if present, needs to be directly adjacent to the option in the same argument string). To allow the option-argument to follow -j as a separate argument, these implementations check whether the next argument begins with a digit. If it does, it is treated as an option-argument for -j; if it does not, the -j is processed as not having an option-argument and the next argument is processed as if it followed a -j option-argument. This behavior is not suitable for inclusion in this standard as it does not meet the syntax guidelines. However, it is an allowed extension since following -j with an argument that does not begin with a digit would otherwise be a syntax error. At least one implementation of make uses <tt>-j 0</tt> to mean "use a sensible value for the maximum number of targets that can be updated in parallel". If an implementation wants to add this feature, the standard developers suggest following this convention.

The make utilities in most historical implementations process the prerequisites of a target in left-to-right order, and the makefile format requires this. It supports the standard idiom used in many makefiles that produce yacc programs; for example:

foo: y.tab.o lex.o main.o
    $(CC) $(CFLAGS) −o $@ t.tab.o lex.o main.o

In this example, if make chose any arbitrary order, the lex.o might not be made with the correct y.tab.h. Although there may be better ways to express this relationship, it is widely used historically. Implementations that desire to updatem prerequisites in parallel should require an explicit extension to make or the makefile format to accomplish it, as described previously.

When targets are not being updated in parallel (see -j in OPTIONS), make processes the prerequisites of a target in left-to-right order. This supports a common idiom used in many makefiles that produce yacc programs; for example:

foo: y.tab.o lex.o main.o
    $(CC) $(CFLAGS) −o $@ y.tab.o lex.o main.o

In this example, if make chose any arbitrary order, the lex.o might not be made with the correct y.tab.h. Although there may be better ways to express this relationship (that would be needed if -j is specified), it is widely used historically.

It's not clear from the text whether this set of targets includes make itself. In a recursive make scenario, you will be running sub-makes to create targets. In GNU make we do not count make itself as one of the targets to be updated and I recommend this behavior here as well.

In GNU make, we basically say that each invocation of make is given one "free" jobserver token that it can use for starting one job at a time: if it ever wants to start more than one job it needs to get another jobserver token as expected.

all:
    i=0; subs=''; while [ $$i -lt 10 ]; do $(MAKE) -C subdir$$i & subs="$$subs $$!"; i
=$$((i+1)); done; for sub in $$subs; do wait $$sub || exit 1; done

-j maxjobs Set the maximum number of targets that can be updated concurrently. If this option is specified multiple times, the last value of maxjobs specified shall take precedence. If this option is not specified, or if maxjobs is 1, only one target shall be updated at a time (no parallelization). If the value of maxjobs is non-positive, the behavior is unspecified. When maxjobs is greater than 1, make shall create a pool of up to maxjobs - 1 tokens. (Note that implementations are not required to create a pool of exactly maxjobs - 1 tokens. For example, an implementation could limit the pool size based on the number of processors available.) If the size of the token pool would be 0, make need not implement a token pool.

When all of the following are true:

• there is a target with commands that is not up-to-date


• the target's prerequisites (if any) are up-to-date


• make is not waiting to bring the target up-to-date (see .WAIT)


• make is currently bringing a different target with commands up-to-date


• make is not currently bringing maxjobs targets up-to-date in parallel


• the special target .NOTPARALLEL is not specified


• the token pool is not empty

then make may attempt to remove one token from the pool. If a token is successfully removed, it shall attempt to bring this target up-to-date in parallel, and after this processing completes shall return the token to the pool. When make is bringing a target without commands up-to-date, it need not remove a token from the pool.

If a rule invokes a sub-make either via the MAKE macro or via a command line that begins with '+', the sub-make is the same implementation as the make that invoked the sub-make, and the -j option is passed to the sub-make via the MAKEFLAGS environment variable with the same maxjobs value and is not overridden by a maxjobs value from another source (even if it has the same value), the sub-make shall use the same token pool as its invoking make rather than create a new token pool. Otherwise, it is unspecified whether the sub-make uses the same token pool as its invoking make or creates a new token pool. If a rule executes multiple sub-make processes asynchronously the behavior is unspecified.

However, lines with a <plus-sign> (<tt>'+'</tt>) prefix shall be executed.

However, lines with a <plus-sign> (<tt>'+'</tt>) prefix and lines that expand the MAKE macro shall be executed.

Specifying that command lines containing the strings "${MAKE}" and "$(MAKE)" are executed when the −n option is specified (GNU and System V).

The standard specifies a way for portable applications to request parallel updating of targets with commands by using the -j maxjobs option. This feature is described in terms of a token pool initially containing up to maxjobs - 1 tokens. Note that this is not intended to prescribe a particular implementation design; the usual "as if" rule applies.

Implementations are permitted to silently limit the pool size for a few reasons, including:
Implementations that do not support parallelism can support the -j option by simply ignoring the option (other than passing it to sub-make invocations via the MAKEFLAGS environment variable). In effect, such an implementation silently restricts the size of the token pool to zero (and therefore need not create a token pool).
Some historical implementations dynamically limit the token pool size based on current system load to avoid overloading the system.
Implementations may want to limit the token pool size based on the number of processors available.
Implementations may want to limit the token pool size based on resource limits.
Limiting the pool size does not change the value of maxjobs that is passed to sub-make invocations via the MAKEFLAGS environment variable.

When a different maxjobs value is passed to a sub-make, some historical make implementations created a separate pool of tokens while other historical make implementations continued to obtain tokens from the invoking make but limited the number of tokens held at a time to the new value of maxjobs - 1. Both behaviors are believed to have merit in different situations: The former gives a sub-make complete control the amount of parallelism while the latter allows the user to control overall system load. The standard permits either behavior.

The standard calls for a token pool of size maxjobs - 1, and for removal from that pool only for the second and subsequent tasks in a set of parallel tasks. This design was chosen because this is effectively what existing implementations do, and also because the token consumed by a parallel task that invokes a sub-make is effectively lent to the sub-make. Lending the token to the sub-make has the following advantages:

• It prevents the sub-make from being completely idle due to token starvation, allowing it to always make some progress regardless of how many tokens other sub-make invocations have consumed.


• It prevents token pool exhaustion caused by a long chain of sub-make invocations. If the token consumed by the invoking rule was not effectively lent to the sub-make, then the pool would be exhausted by a chain of sub-make invocations that is maxjobs long. Such a chain would never accomplish any work, and would thus never complete.

When a rule invokes multiple sub-make processes asynchronously (for example by using an asynchronous list in the shell), some implementations allow each sub-make to execute at least one rule even though this would cause the total number of parallel rule executions across all make instances to exceed maxjobs (after discounting the rules that execute sub-make processes). This behavior may not be ideal, but it is easier to implement and is unlikely to cause problems in practice because applications typically do not have any rules that invoke multiple sub-make processes asynchronously. For this reason the behavior is unspecified if a rule executes multiple sub-make processes asynchronously.

When multiple sub-make processes are running in parallel there is no requirement placed on the ordering of output from these processes. Some implementations of make attempt to serialize output from each sub-<make>; others make no such attempt. If diagnostic messages from failed commands are intermixed, the usual way to deal with this is to repeat the make without -j (or with -j 1) so that intermixing will not occur.