[lit] Introduce LIT_WORKERS environment variable

[jansvoboda11]

Summary

There is no way to specify the number of workers when invoking lit indirectly (e.g. when building targets similar "check-clang"). Lit does not see the -j N target passed to the build tool (e.g. ninja).

This patch introduces the LIT_WORKERS environment variable, which works around this. Now, the number of cores for building dependencies of a lit test and runing the lit test can be both parametrized:
LIT_WORKERS=N ninja check-clang -j M

When invoking lit directly, the value specified via LIT_WORKERS can be overwritten by lit -j argument.

[dexonsmith]

LGTM! Thanks for implementing this.

[yln]

There is no way to specify the number of workers when invoking lit indirectly ...

You could have accomplished this with LIT_OPTS=--workers=4 instead of adding a dedicated env var.

[jansvoboda11]

In D97373#2585720, @yln wrote:

There is no way to specify the number of workers when invoking lit indirectly ...

You could have accomplished this with LIT_OPTS=--workers=4 instead of adding a dedicated env var.

Ah, I totally missed that in the documentation, thanks for pointing this out.

What's the reason for having granular environment variables then? (e.g. LIT_FILTER, LIT_FILTER_OUT, LIT_XFAIL)

[yln]

In D97373#2585852, @jansvoboda11 wrote:

What's the reason for having granular environment variables then? (e.g. LIT_FILTER, LIT_FILTER_OUT, LIT_XFAIL)

LIT_FILTER predates LIT_OPTS and the others were added for convenience I guess (not too happy about that).

[jansvoboda11]

In D97373#2585887, @yln wrote:

LIT_FILTER predates LIT_OPTS and the others were added for convenience I guess (not too happy about that).

I see, thanks for the clarification.

Abandoning in favor of LIT_OPTS="-j N".

llvm/docs/CommandGuide/lit.rst

 
 .. option:: -h, --help
 
  Show the :program:`lit` help message.
 
 .. option:: -j N, --workers=N
 
  Run ``N`` tests in parallel.  By default, this is automatically chosen to
- match the number of detected available CPUs.
+ match the number of detected available CPUs. The environment variable
+ ``LIT_WORKERS`` can be also used in place of this option, which is especially
+ useful in environments where the call to ``lit`` is issued indirectly.
 
 .. option:: --config-prefix=NAME
 
  Search for :file:`{NAME}.cfg` and :file:`{NAME}.site.cfg` when searching for
  test suites, instead of :file:`lit.cfg` and :file:`lit.site.cfg`.
 
 .. option:: -D NAME[=VALUE], --param NAME[=VALUE]
 

llvm/utils/lit/lit/cl_arguments.py

parser.add_argument('--version',
             action='version',
             version='%(prog)s ' + lit.__version__)
 
     parser.add_argument("-j", "--threads", "--workers",
             dest="workers",
             metavar="N",
             help="Number of workers used for testing",
             type=_positive_int,
-            default=lit.util.usable_core_count())
+            default=os.environ.get("LIT_WORKERS", lit.util.usable_core_count()))
     parser.add_argument("--config-prefix",
             dest="configPrefix",
             metavar="NAME",
             help="Prefix for 'lit' config files")
     parser.add_argument("-D", "--param",
             dest="user_params",
             metavar="NAME=VAL",
             help="Add 'NAME' = 'VAL' to the user defined parameters",

llvm/utils/lit/tests/Inputs/lit-workers/lit.cfg

+import lit.formats
+config.name = 'lit-workers'
+config.suffixes = ['.txt']
+config.test_format = lit.formats.ShTest()
+config.test_source_root = None
+config.test_exec_root = None

llvm/utils/lit/tests/Inputs/lit-workers/test1.txt

+# RUN: true

llvm/utils/lit/tests/Inputs/lit-workers/test2.txt

+# RUN: true

llvm/utils/lit/tests/Inputs/lit-workers/test3.txt

+# RUN: true

llvm/utils/lit/tests/Inputs/lit-workers/test4.txt

+# RUN: true

llvm/utils/lit/tests/lit-workers.py

+# Check that the number of workers can be specified via the `-j` argument.
+# RUN:                   %{lit} -s %{inputs}/lit-workers -j 4 | FileCheck %s
+
+# Check that the number of workers can be specified via the `LIT_WORKERS`
+# environment variable.
+# RUN: env LIT_WORKERS=4 %{lit} -s %{inputs}/lit-workers      | FileCheck %s
+
+# Check that the number of workers specified via the `LIT_WORKERS` environment
+# variable can be overwritten by the `-j` argument.
+# RUN: env LIT_WORKERS=2 %{lit} -s %{inputs}/lit-workers -j 4 | FileCheck %s
+
+# CHECK: 4 workers