github.com/westcoastroms/westcoastroms-build@v0.0.0-20190928114312-2350e5a73030/build/make/tools/makeparallel/README.md (about)

     1  <!---
     2  Copyright (C) 2015 The Android Open Source Project
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8       http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  -->
    16  
    17  makeparallel
    18  ============
    19  makeparallel communicates with the [GNU make jobserver](http://make.mad-scientist.net/papers/jobserver-implementation/)
    20  in order claim all available jobs, and then passes the number of jobs
    21  claimed to a subprocess with `-j<jobs>`.
    22  
    23  The number of available jobs is determined by reading tokens from the jobserver
    24  until a read would block.  If the makeparallel rule is the only one running the
    25  number of jobs will be the total size of the jobserver pool, i.e. the value
    26  passed to make with `-j`.  Any jobs running in parallel with with the
    27  makeparellel rule will reduce the measured value, and thus reduce the
    28  parallelism available to the subprocess.
    29  
    30  To run a multi-thread or multi-process binary inside GNU make using
    31  makeparallel, add
    32  ```Makefile
    33  	+makeparallel subprocess arguments
    34  ```
    35  to a rule.  For example, to wrap ninja in make, use something like:
    36  ```Makefile
    37  	+makeparallel ninja -f build.ninja
    38  ```
    39  
    40  To determine the size of the jobserver pool, add
    41  ```Makefile
    42  	+makeparallel echo > make.jobs
    43  ```
    44  to a rule that is guarantee to run alone (i.e. all other rules are either
    45  dependencies of the makeparallel rule, or the depend on the makeparallel
    46  rule.  The output file will contain the `-j<num>` flag passed to the parent
    47  make process, or `-j1` if no flag was found.  Since GNU make will run
    48  makeparallel during the execution phase, after all variables have been
    49  set and evaluated, it is not possible to get the output of makeparallel
    50  into a make variable.  Instead, use a shell substitution to read the output
    51  file directly in a recipe.  For example:
    52  ```Makefile
    53  	echo Make was started with $$(cat make.jobs)
    54  ```