From 3fe81a3832809bdec63605f0d3caf2e733a86cb4 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Tue, 17 Jan 2023 19:15:54 -0500 Subject: [PATCH] Add manpages for missing user commands (using help2man) --- Makefile.in | 16 +++++++++++++--- bin/verilator_ccache_report | 5 ++++- bin/verilator_difftree | 15 ++++++--------- bin/verilator_gantt | 12 ++++++------ bin/verilator_profcfunc | 12 ++++++------ ci/ci-install.bash | 4 ++-- ci/docker/buildenv/Dockerfile | 1 + docs/guide/install.rst | 2 +- 8 files changed, 39 insertions(+), 28 deletions(-) diff --git a/Makefile.in b/Makefile.in index 68af6d11f..916f6c756 100644 --- a/Makefile.in +++ b/Makefile.in @@ -126,7 +126,12 @@ EXAMPLES_FIRST = \ EXAMPLES = $(EXAMPLES_FIRST) $(filter-out $(EXAMPLES_FIRST), $(sort $(wildcard examples/*))) # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff -VL_INST_MAN_FILES = verilator.1 verilator_coverage.1 +# No verilator_ccache_report.1, verilator_difftree.1 as those are not bin/ installed +VL_INST_MAN_FILES = \ + verilator.1 \ + verilator_coverage.1 \ + verilator_gantt.1 \ + verilator_profcfunc.1 \ default: all all: all_nomsg msg_test @@ -179,8 +184,12 @@ docs: info info: $(INFOS) -%.1: ${srcdir}/bin/% +verilator.1: ${srcdir}/bin/verilator pod2man $< $@ +verilator_coverage.1: ${srcdir}/bin/verilator_coverage + pod2man $< $@ +%.1: ${srcdir}/bin/% + help2man --no-info --no-discard-stderr --version-string=- $< -o $@ .PHONY: verilator.html verilator.html: @@ -193,7 +202,7 @@ verilator.pdf: Makefile # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff VL_INST_BIN_FILES = verilator verilator_bin$(EXEEXT) verilator_bin_dbg$(EXEEXT) verilator_coverage_bin_dbg$(EXEEXT) \ - verilator_ccache_report verilator_coverage verilator_gantt verilator_includer verilator_profcfunc + verilator_ccache_report verilator_coverage verilator_difftree verilator_gantt verilator_includer verilator_profcfunc # Some scripts go into both the search path and pkgdatadir, # so they can be found by the user, and under $VERILATOR_ROOT. @@ -226,6 +235,7 @@ installbin: $(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/bin ( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_includer $(DESTDIR)$(pkgdatadir)/bin/verilator_includer ) ( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_ccache_report $(DESTDIR)$(pkgdatadir)/bin/verilator_ccache_report ) + ( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_difftree $(DESTDIR)$(pkgdatadir)/bin/verilator_difftree ) # Man files can either be part of the original kit, or built in current directory # So important we use $^ so VPATH is searched diff --git a/bin/verilator_ccache_report b/bin/verilator_ccache_report index af8ccf50e..31e3b9cdb 100755 --- a/bin/verilator_ccache_report +++ b/bin/verilator_ccache_report @@ -12,7 +12,10 @@ from datetime import datetime parser = argparse.ArgumentParser( allow_abbrev=False, formatter_class=argparse.RawDescriptionHelpFormatter, - description="""Report ccache behavior of a Verilated model build.""", + description="""Report ccache behavior of a Verilated model build. + + For documentation see + https://verilator.org/guide/latest/exe_verilator_ccache_report.html""", epilog= """Copyright 2002-2023 by Wilson Snyder. This program is free software; you can redistribute it and/or modify it under the terms of either the GNU diff --git a/bin/verilator_difftree b/bin/verilator_difftree index 01df446eb..f298bcf07 100755 --- a/bin/verilator_difftree +++ b/bin/verilator_difftree @@ -104,16 +104,13 @@ def filterf(fn1, fn2): parser = argparse.ArgumentParser( allow_abbrev=False, formatter_class=argparse.RawDescriptionHelpFormatter, - description="""Compare two Verilator debugging trees""", - epilog= - """Verilator_difftree is used for debugging Verilator tree output files. + description="""Compare two Verilator debugging trees. + +Verilator_difftree is used for debugging Verilator tree output files. It performs a diff between two files, or all files common between two -directories, ignoring irrelevant pointer differences. - -For documentation see -https://verilator.org/guide/latest/exe_verilator_difftree.html - -Copyright 2005-2023 by Wilson Snyder. This program is free software; you +directories, ignoring irrelevant pointer differences.""", + epilog= + """Copyright 2005-2023 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. diff --git a/bin/verilator_gantt b/bin/verilator_gantt index 0db90c427..0015cb57f 100755 --- a/bin/verilator_gantt +++ b/bin/verilator_gantt @@ -475,16 +475,16 @@ def write_vcd(filename): parser = argparse.ArgumentParser( allow_abbrev=False, formatter_class=argparse.RawDescriptionHelpFormatter, - description="""Create Gantt chart of multi-threaded execution""", - epilog= - """Verilator_gantt creates a visual representation to help analyze Verilator + description="""Create Gantt chart of multi-threaded execution. + +Verilator_gantt creates a visual representation to help analyze Verilator #xmultithreaded simulation performance, by showing when each macro-task #xstarts and ends, and showing when each thread is busy or idle. For documentation see -https://verilator.org/guide/latest/exe_verilator_gantt.html - -Copyright 2018-2023 by Wilson Snyder. This program is free software; you +https://verilator.org/guide/latest/exe_verilator_gantt.html""", + epilog= + """Copyright 2018-2023 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. diff --git a/bin/verilator_profcfunc b/bin/verilator_profcfunc index 5fa64e0b7..cd72060df 100755 --- a/bin/verilator_profcfunc +++ b/bin/verilator_profcfunc @@ -171,17 +171,17 @@ def profcfunc(filename): parser = argparse.ArgumentParser( allow_abbrev=False, formatter_class=argparse.RawDescriptionHelpFormatter, - description="""Read gprof report created with --prof-cfuncs""", - epilog= - """Verilator_profcfunc reads a profile report created by gprof. The names of + description="""Read gprof report created with --prof-cfuncs. + +Verilator_profcfunc reads a profile report created by gprof. The names of the functions are then transformed, assuming the user used Verilator's --prof-cfuncs, and a report printed showing the percentage of time, etc, in each Verilog block. For documentation see -https://verilator.org/guide/latest/exe_verilator_profcfunc.html - -Copyright 2002-2023 by Wilson Snyder. This program is free software; you +https://verilator.org/guide/latest/exe_verilator_profcfunc.html""", + epilog= + """Copyright 2002-2023 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. diff --git a/ci/ci-install.bash b/ci/ci-install.bash index 2424e595b..d3372a798 100755 --- a/ci/ci-install.bash +++ b/ci/ci-install.bash @@ -59,8 +59,8 @@ if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then if [ "$CI_OS_NAME" = "linux" ]; then sudo apt-get update || sudo apt-get update - sudo apt-get install libfl-dev ccache || - sudo apt-get install libfl-dev ccache + sudo apt-get install ccache help2man libfl-dev || + sudo apt-get install ccache help2man libfl-dev if [ "$CI_RUNS_ON" != "ubuntu-22.04" ]; then # Some conflict of libunwind verison on 22.04, can live without it for now sudo apt-get install libgoogle-perftools-dev || diff --git a/ci/docker/buildenv/Dockerfile b/ci/docker/buildenv/Dockerfile index 7adf4b3d2..3e3fbe177 100644 --- a/ci/docker/buildenv/Dockerfile +++ b/ci/docker/buildenv/Dockerfile @@ -23,6 +23,7 @@ RUN apt-get update \ gdb \ git \ gtkwave \ + help2man \ libfl2 \ libfl-dev \ libgoogle-perftools-dev \ diff --git a/docs/guide/install.rst b/docs/guide/install.rst index 834f0b707..b6e50d16b 100644 --- a/docs/guide/install.rst +++ b/docs/guide/install.rst @@ -91,7 +91,7 @@ To build or run Verilator, you need these standard packages: :: - sudo apt-get install git perl python3 make + sudo apt-get install git help2man perl python3 make sudo apt-get install g++ # Alternatively, clang sudo apt-get install libgz # Non-Ubuntu (ignore if gives error) sudo apt-get install libfl2 # Ubuntu only (ignore if gives error)