Change `--output-groups` to default to value of `--build-jobs`.

Those using build farms may need to now use `--output-groups 0` or otherwise.

Changes

@@ -13,6 +13,9 @@ Verilator 5.035 devel
 
 **Other:**
 
+* Change `--output-groups` to default to value of `--build-jobs`.
+  Those using build farms may need to now use `--output-groups 0` or otherwise.
+
 
 Verilator 5.034 2025-02-24
 ==========================

docs/guide/exe_verilator.rst

@@ -146,13 +146,16 @@ Summary:
 
    This option was named `--bin` before version 4.228.
 
-.. option:: --build-jobs [<value>]
+.. option:: --build-jobs <value>
 
    Specify the level of parallelism for :vlopt:`--build`. If zero, uses the
    number of threads in the current hardware. Otherwise, the <value> must
    be a positive integer specifying the maximum number of parallel build
    jobs.
 
+   If not provided, and :vlopt:`-j` is provided, the :vlopt:`-j` value is
+   used.
+
    This forms the :command:`make` option ``-j`` value, unless the
    :option:`MAKEFLAGS` environment variable contains ``-jobserver-auth``,
    in which case Verilator assumes that make's jobserver is being used.
@@ -788,9 +791,12 @@ Summary:
 
    Specify the level of parallelism for :vlopt:`--build` if
    :vlopt:`--build-jobs` isn't provided, and the internal compilation steps
-   of Verilator if :vlopt:`--verilate-jobs` isn't provided. If zero, uses
-   the number of threads in the current hardware. Otherwise, must be a
-   positive integer specifying the maximum number of parallel build jobs.
+   of Verilator if :vlopt:`--verilate-jobs` isn't provided. Also sets
+   :vlopt:`--output-groups` if isn't provided.
+
+   If zero, uses the number of threads in the current hardware. Otherwise,
+   must be a positive integer specifying the maximum number of parallel
+   build jobs.
 
 .. option:: --json-only
 
@@ -1016,18 +1022,24 @@ Summary:
 .. option:: --output-groups <numfiles>
 
    Enables concatenating the output .cpp files into the given number of
-   effective output .cpp files.  This is useful if the compiler startup
-   overhead from compiling many small files becomes unacceptable,
-   which can happen in designs making extensive use of SystemVerilog classes,
-   templates or generate blocks.
+   effective output .cpp files.  This minimizes the compiler startup
+   overhead from compiling many small files, which can happen in designs
+   making extensive use of SystemVerilog classes, templates or generate
+   blocks.
 
    Using :vlopt:`--output-groups` can adversely impact caching and stability
    (as in reproducibility) of compiled code.  Compilation of larger .cpp
    files also has higher memory requirements.  Too low values might result in
-   swap thrashing with large designs, high values give no benefits.  The
-   value should range from 2 to 20 for small to medium designs.
+   swap thrashing with large designs, high values give no benefits.
 
-   Default is zero, which disables this feature.
+   Typically setting the number of files to the hardware thread count,
+   corresponding to number of compiler jobs that can run in parallel, will
+   lead to fastest build times. (e.g. for small to medium designs the value
+   should range from 2 to 20.)
+
+   Zero disables this feature.  Negative one, the default, sets the groups
+   to the value from :vlopt:`--build-jobs`, or from :vlopt:`-j`, or zero in
+   that priority.
 
 .. option:: --output-split <statements>
 
@@ -1700,13 +1712,16 @@ Summary:
    execute only the build. This can be useful for rebuilding the Verilated code
    produced by a previous invocation of Verilator.
 
-.. option:: --verilate-jobs [<value>]
+.. option:: --verilate-jobs <value>
 
    Specify the level of parallelism for the internal compilation steps of
    Verilator. If zero, uses the number of threads in the current hardware.
    Otherwise, must be a positive integer specifying the maximum number of
    parallel build jobs.
 
+   If not provided, and :vlopt:`-j` is provided, the :vlopt:`-j` value is
+   used.
+
    See also :vlopt:`-j`.
 
 .. option:: +verilog1995ext+<ext>

src/V3Options.cpp

@@ -962,6 +962,7 @@ void V3Options::notify() VL_MT_DISABLED {
 
     // Sanity check of expected configuration
     UASSERT(threads() >= 1, "'threads()' must return a value >= 1");
+    if (m_outputGroups == -1) m_outputGroups = (m_buildJobs != -1) ? m_buildJobs : 0;
     if (m_buildJobs == -1) m_buildJobs = 1;
     if (m_verilateJobs == -1) m_verilateJobs = 1;
 
@@ -1464,7 +1465,7 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc,
     });
     DECL_OPTION("-output-groups", CbVal, [this, fl](const char* valp) {
         m_outputGroups = std::atoi(valp);
-        if (m_outputGroups < 0) { fl->v3error("--output-groups must be >= 0: " << valp); }
+        if (m_outputGroups < -1) fl->v3error("--output-groups must be >= -1: " << valp);
     });
     DECL_OPTION("-output-split", Set, &m_outputSplit);
     DECL_OPTION("-output-split-cfuncs", CbVal, [this, fl](const char* valp) {
@@ -1834,6 +1835,7 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc,
             }
             if (m_buildJobs == -1) m_buildJobs = val;
             if (m_verilateJobs == -1) m_verilateJobs = val;
+            if (m_outputGroups == -1) m_outputGroups = val;
         } else if (argv[i][0] == '-' || argv[i][0] == '+') {
             const char* argvNoDashp = (argv[i][1] == '-') ? (argv[i] + 2) : (argv[i] + 1);
             if (const int consumed = parser.parse(i, argc, argv)) {

src/V3Options.h

@@ -322,7 +322,7 @@ private:
     VOptionBool m_makeDepend;  // main switch: -MMD
     int         m_maxNumWidth = 65536;  // main switch: --max-num-width
     int         m_moduleRecursion = 100;  // main switch: --module-recursion-depth
-    int         m_outputGroups = 0;  // main switch: --output-groups
+    int         m_outputGroups = -1;  // main switch: --output-groups
     int         m_outputSplit = 20000;  // main switch: --output-split
     int         m_outputSplitCFuncs = -1;  // main switch: --output-split-cfuncs
     int         m_outputSplitCTrace = -1;  // main switch: --output-split-ctrace

test_regress/t/t_flag_output_groups_bad.out

@@ -1,2 +1,2 @@
-%Error: --output-groups must be >= 0: -1
+%Error: --output-groups must be >= -1: -2
 %Error: Exiting due to

test_regress/t/t_flag_output_groups_bad.py

@@ -11,7 +11,7 @@ import vltest_bootstrap
 
 test.scenarios('vlt')
 
-test.lint(verilator_flags2=['--output-groups -1'],
+test.lint(verilator_flags2=['--output-groups -2'],
           fails=True,
           expect_filename=test.golden_filename)
 

test_regress/t/t_uvm_all.py

@@ -13,7 +13,7 @@ test.scenarios('vlt')
 
 test.compile(
     v_flags2=[
-        "--binary --timing +incdir+t/uvm",  #
+        "--binary --timing -j 0 +incdir+t/uvm",  #
         "--error-limit 200 --debug-exit-uvm"
     ],
     verilator_make_gmake=False)

test_regress/t/t_uvm_todo.py

@@ -8,14 +8,11 @@
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 import vltest_bootstrap
-import multiprocessing
 
 test.scenarios('vlt')
 
-test.compile(v_flags2=["--timing", "+incdir+t/uvm", "t/t_uvm_todo.vlt"],
-             make_flags=['-k -j ' + str(multiprocessing.cpu_count())],
+test.compile(v_flags2=["--timing", "+incdir+t/uvm", "t/t_uvm_todo.vlt", "-j 0"],
+             make_flags=['-k'],
              verilator_make_gmake=False)
 
-#test.execute()
-
 test.passes()