Split -c sub-command into --cover-report and --cover-merge

NEWS.md

@@ -10,6 +10,11 @@
 - Updated to OSVVM 2024.07 for `nvc --install`.
 - Added a warning when an inner declaration hides an outer declaration
   in a way that is likely to be unintentional (#905).
+- The `-c` sub-command for coverage is deprecated and replaced with
+  separate `--cover-report` and `--cover-merge` commands.  See the
+  manual for details.
+- The argument to the `--cover-export` command is now the path to a
+  coverage database file instead of a top-level unit name.
 
 ## Version 1.13.1 - 2024-07-25
 - Windows installer was missing some standard library files.

contrib/nvc.bash

@@ -7,7 +7,7 @@ _nvc () {
   local have_cmd
   for i in "${COMP_WORDS[@]}"; do
     case "$i" in
-      -a|-e|-r|--do)
+      -a|-e|-r|--do|--cover-export|--cover-report|--cover-merge)
         have_cmd=$i
         ;;
     esac
@@ -38,13 +38,16 @@ _nvc () {
 
   local global_opts='-L -h --help --messages= --std= -v --version --init --list
                      --install --work= -a -e -r -i --dump --print-deps
-                     --syntax --map= --do'
+                     --syntax --map= --do --cover-report --cover-export --cover-merge'
   local analyse_opts='-D --define= --error-limit= --relaxed --psl --error-limit=
                       -f --files'
   local elab_opts='--cover --disable-opt --dump-llvm --dump-vcode --jit --no-save
                    --native -V --verbose'
   local run_opts='--trace --stop-time= --ieee-warnings= --stats= --stop-delta=
                   -w --wave --format='
+  local export_opts='--format= -o --output='
+  local merge_opts='-o --output='
+  local report_opts='-o --output= --exclude-file= --dont-print= --item-limit='
 
   case "$have_cmd" in
     -a)
@@ -70,6 +73,18 @@ _nvc () {
     --do)
       _filedir '@(pro|do|tcl)'
       ;;
+    --cover-export)
+      _filedir '@(covdb|ncdb)'
+      COMPREPLY+=( $( compgen -W "$export_opts" -- $cur ) )
+      ;;
+    --cover-report)
+      _filedir '@(covdb|ncdb)'
+      COMPREPLY+=( $( compgen -W "$report_opts" -- $cur ) )
+      ;;
+    --cover-merge)
+      _filedir '@(covdb|ncdb)'
+      COMPREPLY+=( $( compgen -W "$merge_opts" -- $cur ) )
+      ;;
     *)
       COMPREPLY+=( $( compgen -W "$global_opts" -- $cur ) )
       ;;

nvc.1

@@ -48,15 +48,16 @@ Elaborate a previously analysed top level design unit.
 .\" -r
 .It Fl r Ar unit
 Execute a previously elaborated top level design unit.
-.\" -c
-.It Fl c Ar
-Process code coverage data from
-.Ar file
-and generate coverage report.
 .\" --cover-export
-.It Fl \-cover-export Ar unit
-Export collected coverage information for a previously executed top
-level design unit to an external format such as Cobertura XML.
+.It Fl \-cover-export Ar
+Export collected coverage information from the internal database format
+to an external format such as Cobertura XML.
+.\" --cover-merge
+.It Fl \-cover-merge Ar
+Merge multiple coverage databases into a single database.
+.\" --cover-report
+.It Fl \-cover-report Ar
+Generate an HTML report from a coverage database.
 .\" --dump
 .It Fl \-dump Ar unit
 Print out a pseudo-VHDL representation of an analysed unit.  This is
@@ -83,6 +84,7 @@ Check input files for syntax errors only.
 .El
 .\"
 .Pp
+.\" TODO: move this to the EXAMPLES section
 Commands can be chained together arbitrarily and the top-level unit
 name need only be specified once.  For example to analyse a file
 .Ql source.vhd
@@ -92,19 +94,11 @@ and then elaborate and run a top-level entity
 $ nvc -a source.vhd -e tb -r
 .Ed
 .Pp
-Or to elaborate again with coverage collection enabled, run the
-simulation, and export the data to the Cobertura format:
-.Bd -literal -offset indent
-$ nvc -e --cover tb -r --cover-export --format=cobertura -o out.xml
-.Ed
-.Pp
 Note how the
 .Ar unit
 argument for the
 .Fl r
-and
-.Fl \-cover-export
-commands is taken from the earlier
+command is taken from the earlier
 .Fl e
 command.
 .\" ------------------------------------------------------------
@@ -443,27 +437,52 @@ option.  By default all signals in the design will be dumped: see the
 section below for how to control this.
 .El
 .\" ------------------------------------------------------------
-.\" Coverage processing options
+.\" Coverage export options
 .\" ------------------------------------------------------------
-.Ss Coverage processing options
+.Ss Coverage export options
 .Bl -tag -width Ds
-.It Fl \-merge= Ns Ar output
-Merge multiple
-.Ar file
-code coverage databases into
-.Ar output
-code coverage database.
-.It Fl \-report= Ns Ar dir
-Generate HTML code coverage report to
-.Ar dir
-directory.
+.\" --format
+.It Fl \-format= Ns Ar format
+Output file format.  Currently the only valid value is
+.Ql cobertura
+which is the Cobertura XML format widely supported by CI systems.
+.\" --output
+.It Fl o , Fl \-output= Ns Ar file
+Write output to
+.Ar file .
+If this option is not specified the standard output stream is used.
+.\" --relative
+.It Fl \-relative Ns Op = Ns Ar path
+Strip
+.Ar path
+or the current working directory from the front of any absolute path
+names in the output.
+.El
+.\" ------------------------------------------------------------
+.\" Coverage merge options
+.\" ------------------------------------------------------------
+.Ss Coverage export options
+.Bl -tag -width Ds
+.\" --output
+.It Fl o , Fl \-output= Ns Ar file
+File name of output coverage database.
+.El
+.\" ------------------------------------------------------------
+.\" Coverage report options
+.\" ------------------------------------------------------------
+.Ss Coverage report options
+.Bl -tag -width Ds
+.\" --output
+.It Fl o , Fl \-output= Ns Ar dir
+Name of output directory where HTML files will be generated.
 .It Fl \-exclude-file= Ns Ar efile
 Apply commands in
 .Ar efile
 exclude file when generating code coverage report.
 .It Fl \-dont-print= Ns Ar options
-When set, NVC does not place code coverage details specified by <options> to
-code coverage report.
+When set, NVC does not include code coverage details specified by
+.Ar options
+in the code coverage report.
 .Ar options
 is comma separated list of the following values:
 .Bl -tag -width "uncovered"
@@ -477,35 +496,11 @@ Does not include excluded items.
 .It Fl \-item-limit= Ns Ar limit
 NVC displays maximum
 .Ar limit
-items of single type (covered, uncovered, excluded) in
-a single hierarchy in the code coverage report. Each Bin
-is counted as one item. Default value of
+items of single type (covered, uncovered, excluded) in a single
+hierarchy in the code coverage report.  Each Bin is counted as one item.
+The default value of
 .Ar limit
 is 5000.
-.It Fl V , Fl \-verbose
-Prints detailed hierarchy coverage when generating code coverage report.
-.El
-.\" ------------------------------------------------------------
-.\" Coverage export options
-.\" ------------------------------------------------------------
-.Ss Coverage export options
-.Bl -tag -width Ds
-.\" --format
-.It Fl \-format= Ns Ar format
-Output file format.  Currently the only valid value is
-.Ql cobertura
-which is the Cobertura XML format widely supported by CI systems.
-.\" --output
-.It Fl o , Fl \-output= Ns Ar file
-Write output to
-.Ar file .
-If this option is not specified the standard output stream is used.
-.\" --relative
-.It Fl \-relative Ns Op = Ns Ar path
-Strip
-.Ar path
-or the current working directory from the front of any absolute path
-names in the output.
 .El
 .\" ------------------------------------------------------------
 .\" Make options
@@ -690,9 +685,18 @@ simulation is executed, NVC dumps coverage data into coverage database file
 (*.covdb). To merge coverage databases from multiple simulations, and generate
 hierarchy coverage report in HTML format, run:
 .Bd -literal -offset indent
-$ nvc -c --merge=merged.covdb --report=<path_to_folder_for_html_report> \\
-      first.covdb second.covdb third.covdb ...
+$ nvc --cover-merge -o merged.covdb first.covdb second.covdb third.covdb ...
+$ nvc --cover-report -o html merged.covdb
 .Ed
+.Pp
+This will generate a report in the
+.Pa html
+directory which can be viewed in a web browser.  If you do not wish to
+save the merged database this can also be performed in a single command:
+.Bd -literal -offset indent
+$ nvc --cover-report -o html first.covdb second.covdb third.covdb ...
+.Ed
+.Pp
 When NVC merges multiple coverage databse files, coverage bins with equal
 hierarchical paths in the elaborated design are summed together.
 When a coverage bin is non-zero, it is shown as covered in the coverage report.