From ab6e1c23998788a4f3048b189024c5fd535e268d Mon Sep 17 00:00:00 2001
From: Wilson Snyder <wsnyder@wsnyder.org>
Date: Thu, 15 Sep 2022 20:26:08 -0400
Subject: [PATCH] Commentary on --main

---
 bin/verilator                |  3 +--
 docs/guide/exe_verilator.rst | 21 +++++++++------------
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/bin/verilator b/bin/verilator
index b68812d61..36332490c 100755
--- a/bin/verilator
+++ b/bin/verilator
@@ -341,10 +341,9 @@ detailed descriptions of these arguments.
     --lib-create <name>         Create a DPI library
      +libext+<ext>+[ext]...     Extensions for finding modules
     --lint-only                 Lint, but do not make output
-    --main                      Generate a main C++ file
     --make <build-tool>         Generate scripts for specified build tool
      -MAKEFLAGS <flags>         Arguments to pass to make during --build
-    --main                      Generate C++ main()
+    --main                      Generate C++ main() file
     --max-num-width <value>     Maximum number width (default: 64K)
     --Mdir <directory>          Name of output object directory
     --MMD                       Create .d dependency files
diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst
index ce2140c7a..123d56059 100644
--- a/docs/guide/exe_verilator.rst
+++ b/docs/guide/exe_verilator.rst
@@ -684,16 +684,6 @@ Summary:
    If the design is not to be completely Verilated see also the
    :vlopt:`--bbox-sys` and :vlopt:`--bbox-unsup` options.
 
-.. option:: --main
-
-   Generates a simple main C++ file. Without :vlopt:`--timing`, you need to
-   modify this file to provide some stimuli to the design. However, this option
-   is especially useful with :vlopt:`--timing` and delay-generated clocks, as
-   then the main file provides a timing-enabled eval loop and requires no
-   modification by the user. :vlopt:`--build` can then be used to build the
-   simulation, allowing you to use Verilator without directly invoking
-   the C++ toolchain.
-
 .. option:: --make <build-tool>
 
    Generates a script for the specified build tool.
@@ -720,8 +710,15 @@ Summary:
 
    Generates a top-level C++ main() file that supports parsing arguments,
    but does not drive any inputs.  This is sufficient to use for top-level
-   SystemVerilog designs that has no inputs, and does not need the C++ to
-   do any time advancement.
+   SystemVerilog designs that has no inputs.
+
+   This option can also be used once to generate a main .cpp file as a
+   starting point for editing.  Copy it outside the obj directory, manually
+   edit, and then pass the filename on later Verilator command line
+   invocations.
+
+   Typically used with :vlopt:`--timing` to support delay-generated clocks,
+   and :vlopt:`--build`.
 
    Implies :vlopt:`--cc` if no other output mode was provided.