Add --binary option as alias of --main --exe --build (#3625).

Changes

@@ -19,6 +19,7 @@ Verilator 5.001 devel
   clocks are now simulated correctly (#3278, #3384). [Geza Lore, Shunyao CAD]
 * Support timing controls (delays, event controls in any location, wait
   statements) and forks. See docs for details. [Krzysztof Bieganski, Antmicro Ltd]
+* Add --binary option as alias of --main --exe --build (#3625).
 
 
 Verilator 4.227 devel

Makefile.in

@@ -107,6 +107,7 @@ SUBDIRS = docs src test_regress \
 	examples/cmake_tracing_c \
 	examples/cmake_tracing_sc \
 	examples/cmake_protect_lib \
+	examples/make_hello_binary \
 	examples/make_hello_c \
 	examples/make_hello_sc \
 	examples/make_tracing_c \
@@ -243,6 +244,7 @@ installdata:
 	; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
@@ -278,6 +280,7 @@ uninstall:
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd
 	-rmdir $(DESTDIR)$(pkgdatadir)/include
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c

bin/verilator

@@ -244,6 +244,7 @@ Verilator - Translate and simulate SystemVerilog code using C++/SystemC
 
     verilator --help
     verilator --version
+    verilator --binary -j 0 [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --cc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --sc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --lint-only -Wall [source_files.v]...
@@ -282,6 +283,7 @@ detailed descriptions of these arguments.
     --autoflush                 Flush streams after all $displays
     --bbox-sys                  Blackbox unknown $system calls
     --bbox-unsup                Blackbox unsupported language features
+    --binary                    Build model binary
     --build                     Build model executable/library after Verilation
     --build-dep-bin <filename>  Override build dependency Verilator binary
     --build-jobs <jobs>         Parallelism for --build

docs/guide/example_binary.rst

@@ -0,0 +1,63 @@
+.. Copyright 2003-2022 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Example C++ Execution:
+
+Example C++ Execution
+=====================
+
+We'll compile this SystemC example into a Verilated simulation binary.  For
+an example that discusses the next level of detail see :ref:`Example C++
+Execution`.
+
+.. include:: example_common_install.rst
+
+Now, let's create an example Verilog file:
+
+.. code-block:: bash
+
+     mkdir test_our
+     cd test_our
+
+     cat >our.v <<'EOF'
+       module our;
+          initial begin $display("Hello World"); $finish; end
+       endmodule
+     EOF
+
+Now we run Verilator on our little example.
+
+.. code-block:: bash
+
+     verilator --binary -j 0 -Wall our.v
+
+Breaking this command down:
+
+#. :vlopt:`--binary` telling Verilator to do everything needed to create a
+   simulation executable.
+
+#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine
+   has.
+
+#. :vlopt:`-Wall` so Verilator has stronger lint warnings
+   enabled.
+
+#. An finally, :command:`our.v` which is our SystemVerilog design file.
+
+And now we run it:
+
+.. code-block:: bash
+
+     obj_dir/Vour
+
+And we get as output:
+
+.. code-block:: bash
+
+     Hello World
+     - our.v:2: Verilog $finish
+
+Really, you're better off using a Makefile to run the steps for you so when
+your source changes it will automatically run all of the appropriate steps.
+To aid this Verilator can create a makefile dependency file.  For examples
+that do this see the :file:`examples` directory in the distribution.

docs/guide/example_cc.rst

@@ -43,13 +43,10 @@ Now we run Verilator on our little example.
 
 .. code-block:: bash
 
-     verilator -Wall --cc --exe --build sim_main.cpp our.v
+     verilator --cc --exe --build -j 0 -Wall sim_main.cpp our.v
 
 Breaking this command down:
 
-#. :vlopt:`-Wall` so Verilator has stronger lint warnings
-   enabled.
-
 #. :vlopt:`--cc` to get C++ output (versus e.g. SystemC
    or only linting).
 
@@ -61,6 +58,12 @@ Breaking this command down:
    own compile rules, and run make yourself as we show in :ref:`Example
    SystemC Execution`.)
 
+#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine
+   has.
+
+#. :vlopt:`-Wall` so Verilator has stronger lint warnings
+   enabled.
+
 #. An finally, :command:`our.v` which is our SystemVerilog design file.
 
 Once Verilator completes we can see the generated C++ code under the

docs/guide/example_dist.rst

@@ -10,6 +10,8 @@ See the ``examples/`` directory that is part of the distribution, and
 is installed (in a OS-specific place, often in e.g.
 ``/usr/local/share/verilator/examples``).  These examples include:
 
+examples/make_hello_binary
+   Example GNU-make simple Verilog->binary conversion
 examples/make_hello_c
    Example GNU-make simple Verilog->C++ conversion
 examples/make_hello_sc

docs/guide/example_sc.rst

@@ -43,7 +43,7 @@ Now we run Verilator on our little example:
 
 .. code-block:: bash
 
-     verilator -Wall --sc --exe sc_main.cpp our.v
+     verilator --sc --exe -Wall sc_main.cpp our.v
 
 This example does not use --build, therefore we need to explicitly compile
 it:

docs/guide/examples.rst

@@ -17,6 +17,7 @@ This section covers the following examples:
    :maxdepth: 1
    :hidden:
 
+   example_binary.rst
    example_cc.rst
    example_sc.rst
    example_dist.rst

docs/guide/exe_verilator.rst

@@ -115,6 +115,13 @@ Summary:
 
    Using this argument will likely cause incorrect simulation.
 
+.. option:: --binary
+
+   Create a Verilated simulator binary.  Alias for :vlopt:`--main`
+   :vlopt:`--exe` :vlopt:`--build`.
+
+   See also :vlopt:`-j`.
+
 .. option:: --build
 
    After generating the SystemC/C++ code, Verilator will invoke the
@@ -780,6 +787,8 @@ Summary:
 
    Implies :vlopt:`--cc` if no other output mode was provided.
 
+   See also :vlopt:`--binary`.
+
 .. option:: --max-num-width <value>
 
    Set the maximum number literal width (e.g. in 1024'd22 this it the

examples/make_hello_binary/.gitignore

@@ -0,0 +1,6 @@
+*.dmp
+*.log
+*.csrc
+*.vcd
+obj_*
+logs

examples/make_hello_binary/Makefile

@@ -0,0 +1,49 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: Small Makefile
+#
+# This calls the object directory makefile.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+
+# This is intended to be a minimal example.  Before copying this to start a
+# real project, it is better to start with a more complete example,
+# e.g. examples/make_tracing_c.
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+endif
+
+default:
+	@echo "-- Verilator hello-world simple binary example"
+	@echo "-- VERILATE & BUILD --------"
+	$(VERILATOR) --binary -j 0 top.v
+	@echo "-- RUN ---------------------"
+	obj_dir/Vtop
+	@echo "-- DONE --------------------"
+	@echo "Note: Once this example is understood, see examples/make_hello_c."
+	@echo "Note: See also https://verilator.org/guide/latest/examples.html"
+
+######################################################################
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir *.log *.dmp *.vpd core

examples/make_hello_binary/top.v

@@ -0,0 +1,14 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+
+// See also https://verilator.org/guide/latest/examples.html"
+
+module top;
+   initial begin
+      $display("Hello World!");
+      $finish;
+   end
+endmodule

src/V3Options.cpp

@@ -741,7 +741,7 @@ void V3Options::notify() {
 
     if (!outFormatOk() && v3Global.opt.main()) ccSet();  // --main implies --cc if not provided
     if (!outFormatOk() && !cdc() && !dpiHdrOnly() && !lintOnly() && !preprocOnly() && !xmlOnly()) {
-        v3fatal("verilator: Need --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, "
+        v3fatal("verilator: Need --binary, --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, "
                 "--xml-only or --E option");
     }
 
@@ -1016,6 +1016,11 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc, char
         m_bboxUnsup = flag;
         FileLine::globalWarnOff(V3ErrorCode::E_UNSUPPORTED, true);
     });
+    DECL_OPTION("-binary", CbCall, [this]() {
+        m_build = true;
+        m_exe = true;
+        m_main = true;
+    });
     DECL_OPTION("-build", Set, &m_build);
     DECL_OPTION("-build-dep-bin", Set, &m_buildDepBin);
     DECL_OPTION("-build-jobs", CbVal, [this, fl](const char* valp) {

test_regress/t/t_flag_binary.pl

@@ -0,0 +1,30 @@
+#!/usr/bin/env perl
+if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; }
+# DESCRIPTION: Verilator: Verilog Test driver/expect definition
+#
+# Copyright 2019 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
+# Lesser General Public License Version 3 or the Perl Artistic License
+# Version 2.0.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+top_filename("t/t_flag_main.v");
+
+scenarios(simulator => 1);
+
+compile(
+    verilator_flags => [# Custom as don't want -cc
+                        "-Mdir $Self->{obj_dir}",
+                        "--debug-check", ],
+    verilator_flags2 => ['--binary'],
+    verilator_make_cmake => 0,
+    verilator_make_gmake => 0,
+    make_main => 0,
+    );
+
+execute(
+    check_finished => 1,
+    );
+
+ok(1);
+1;

test_regress/t/t_flag_noop_bad.out

@@ -1 +1 @@
-%Error: verilator: Need --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, --xml-only or --E option
+%Error: verilator: Need --binary, --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, --xml-only or --E option