Merge branch 'topic/bbannier/spicy-dump-profiling'

zeek · Jan 23, 2025 · 399d758 · 399d758
2 parents 8c73937 + 125f906
commit 399d758
Show file tree

Hide file tree

Showing 9 changed files with 93 additions and 73 deletions.
diff --git a/CHANGES b/CHANGES
@@ -1,3 +1,11 @@
+1.13.0-dev.75 | 2025-01-23 10:29:10 +0100
+
+  * Regenerate usage documentation. (Benjamin Bannier, Corelight)
+
+  * Clean up minor warts in usage strings of some executables. (Benjamin Bannier, Corelight)
+
+  * Add `spicy-dump` option to enable profiling. (Benjamin Bannier, Corelight)
+
 1.13.0-dev.71 | 2025-01-14 17:26:02 +0100
 
   * Prevent unneeded copy in setting up unit `parseX` functions. (Benjamin Bannier, Corelight)

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.13.0-dev.71
+1.13.0-dev.75
diff --git a/doc/examples/_usage-spicy-build.output b/doc/examples/_usage-spicy-build.output
@@ -2,6 +2,7 @@
 spicy-build [options] <input files>
 
     -d          Build a debug version.
+    -g          Disable HILTI-side optimizations of the generated code.
     -o <file>   Destination name for the compiled executable; default is "a.out".
     -t          Do not delete tmp files (useful for inspecting, and use with debugger)
     -v          Verbose output, display command lines executing.

diff --git a/doc/examples/_usage-spicy-driver.output b/doc/examples/_usage-spicy-driver.output
@@ -3,26 +3,29 @@ Usage: cat <data> | spicy-driver [options] <inputs> ...
 
 Options:
 
-  -d | --debug                    Include debug instrumentation into generated code.
-  -i | --increment <i>            Feed data incrementally in chunks of size n.
-  -f | --file <path>              Read input from <path> instead of stdin.
-  -l | --list-parsers             List available parsers and exit.
-  -p | --parser <name>            Use parser <name> to process input. Only neeeded if more than one parser is available.
-  -v | --version                  Print version information.
-  -A | --abort-on-exceptions      When executing compiled code, abort() instead of throwing HILTI exceptions.
-  -B | --show-backtraces          Include backtraces when reporting unhandled exceptions.
-  -D | --compiler-debug <streams> Activate compile-time debugging output for given debug streams (comma-separated; 'help' for list).
-  -F | --batch-file <path>        Read Spicy batch input from <path>; see docs for description of format.
-  -L | --library-path <path>      Add path to list of directories to search when importing modules.
-  -O | --optimize                 Build optimized release version of generated code.
-  -R | --report-times             Report a break-down of compiler's execution time.
-  -S | --skip-dependencies        Do not automatically compile dependencies during JIT.
-  -U | --report-resource-usage    Print summary of runtime resource usage.
-  -X | --debug-addl <addl>        Implies -d and adds selected additional instrumentation (comma-separated; see 'help' for list).
+  -c | --require-accept               Return failure exit code if parser did not call accept_input(), or called decline_input().
+  -d | --debug                        Include debug instrumentation into generated code.
+  -g | --disable-optimizations        Disable HILTI-side optimizations of the generated code.
+  -i | --increment <i>                Feed data incrementally in chunks of size n.
+  -f | --file <path>                  Read input from <path> instead of stdin.
+  -l | --list-parsers                 List available parsers and exit; use twice to include aliases.
+  -p | --parser <name>                Use parser <name> to process input. Only needed if more than one parser is available.
+  -v | --version                      Print version information.
+  -A | --abort-on-exceptions          When executing compiled code, abort() instead of throwing HILTI exceptions.
+  -B | --show-backtraces              Include backtraces when reporting unhandled exceptions.
+  -D | --compiler-debug <streams>     Activate compile-time debugging output for given debug streams (comma-separated; 'help' for list).
+  -F | --batch-file <path>            Read Spicy batch input from <path>; see docs for description of format.
+  -L | --library-path <path>          Add path to list of directories to search when importing modules.
+  -P | --parser-alias <alias>=<name>  Add alias name for parser of existing name.
+  -R | --report-times                 Report a break-down of compiler's execution time.
+  -S | --skip-dependencies            Do not automatically compile dependencies during JIT.
+  -U | --report-resource-usage        Print summary of runtime resource usage.
+  -X | --debug-addl <addl>            Implies -d and adds selected additional instrumentation (comma-separated; see 'help' for list).
+  -Z | --enable-profiling             Report profiling statistics after execution.
 
 Environment variables:
 
   SPICY_PATH                      Colon-separated list of directories to search for modules. In contrast to --library-paths using this flag overwrites builtin paths.
 
-Inputs can be .hlt, .spicy, .cc/.cxx, *.o, *.hlto.
+Inputs can be .spicy, .hlt, .cc/.cxx, *.o, *.hlto.
 
diff --git a/doc/examples/_usage-spicy-dump.output b/doc/examples/_usage-spicy-dump.output
@@ -5,24 +5,24 @@ Options:
 
   -d | --debug                    Include debug instrumentation into generated code.
   -f | --file <path>              Read input from <path> instead of stdin.
-  -l | --list-parsers             List available parsers and exit.
-  -p | --parser <name>            Use parser <name> to process input. Only neeeded if more than one parser is available.
+  -l | --list-parsers             List available parsers and exit; use twice to include aliases.
+  -p | --parser <name>            Use parser <name> to process input. Only needed if more than one parser is available.
   -v | --version                  Print version information.
   -A | --abort-on-exceptions      When executing compiled code, abort() instead of throwing HILTI exceptions.
   -B | --show-backtraces          Include backtraces when reporting unhandled exceptions.
   -D | --compiler-debug <streams> Activate compile-time debugging output for given debug streams (comma-separated; 'help' for list).
   -L | --library-path <path>      Add path to list of directories to search when importing modules.
   -J | --json                     Print JSON output.
-  -O | --optimize                 Build optimized release version of generated code.
   -P | --enable-print             Show output of Spicy 'print' statements (default: off).
   -Q | --include-offsets          Include stream offsets of parsed data in output.
   -R | --report-times             Report a break-down of compiler's execution time.
   -S | --skip-dependencies        Do not automatically compile dependencies during JIT.
   -X | --debug-addl <addl>        Implies -d and adds selected additional instrumentation (comma-separated; see 'help' for list).
+  -Z | --enable-profiling         Report profiling statistics after execution.
 
 Environment variables:
 
   SPICY_PATH                      Colon-separated list of directories to search for modules. In contrast to --library-paths using this flag overwrites builtin paths.
 
-Inputs can be .hlt, .spicy, *.spicy *.hlt *.hlto.
+Inputs can be .spicy, .hlt, *.spicy *.hlt *.hlto.
 
diff --git a/doc/examples/_usage-spicyc.output b/doc/examples/_usage-spicyc.output
@@ -3,30 +3,31 @@ Usage: spicyc [options] <inputs>
 
 Options controlling code generation:
 
-  -c | --output-c++                Print out all generated C++ code (including linker glue by default).
-  -d | --debug                     Include debug instrumentation into generated code.
-  -e | --output-all-dependencies   Output list of dependencies for all compiled modules.
-  -g | --disable-optimizations     Disable HILTI-side optimizations of the generated code.
-  -j | --jit-code                  Fully compile all code, and then execute it unless --output-to gives a file to store it
-  -l | --output-linker             Print out only generated HILTI linker glue code.
-  -o | --output-to <path>          Path for saving output.
-  -p | --output-hilti              Just output parsed HILTI code again.
-  -v | --version                   Print version information.
-  -x | --output-c++-files <prefix> Output generated C++ code into set of files.
-  -A | --abort-on-exceptions       When executing compiled code, abort() instead of throwing HILTI exceptions.
-  -B | --show-backtraces           Include backtraces when reporting unhandled exceptions.
-  -C | --dump-code                 Dump all generated code to disk for debugging.
-  -D | --compiler-debug <streams>  Activate compile-time debugging output for given debug streams (comma-separated; 'help' for list).
-  -E | --output-code-dependencies  Output list of dependencies for all compiled modules that require separate compilation of their own.
-  -L | --library-path <path>       Add path to list of directories to search when importing modules.
-  -P | --output-prototypes         Output C++ header with prototypes for public functionality.
-  -R | --report-times              Report a break-down of compiler's execution time.
-  -S | --skip-dependencies         Do not automatically compile dependencies during JIT.
-  -T | --keep-tmps                 Do not delete any temporary files created.
-  -V | --skip-validation           Don't validate ASTs (for debugging only).
-  -X | --debug-addl <addl>         Implies -d and adds selected additional instrumentation (comma-separated; see 'help' for list).
-  -Z | --enable-profiling          Report profiling statistics after execution.
-       --cxx-link <lib>            Link specified static archive or shared library during JIT or to produced HLTO file. Can be given multiple times.
+  -c | --output-c++                 Print out C++ code generated for module (for debugging; use -x to generate code for external compilation).
+  -d | --debug                      Include debug instrumentation into generated code.
+  -e | --output-all-dependencies    Output list of dependencies for all compiled modules.
+  -g | --disable-optimizations      Disable HILTI-side optimizations of the generated code.
+  -j | --jit-code                   Fully compile all code, and then execute it unless --output-to gives a file to store it
+  -l | --output-linker              Print out only generated HILTI linker glue code (for debugging; use -x to generate code for external compilation).
+  -o | --output-to <path>           Path for saving output.
+  -p | --output-hilti               Just output parsed HILTI code again.
+  -v | --version                    Print version information.
+  -x | --output-c++-files <prefix>  Output generated all C++ code into set of files for external compilation.
+  -A | --abort-on-exceptions        When executing compiled code, abort() instead of throwing HILTI exceptions.
+  -B | --show-backtraces            Include backtraces when reporting unhandled exceptions.
+  -C | --dump-code                  Dump all generated code to disk for debugging.
+  -D | --compiler-debug <streams>   Activate compile-time debugging output for given debug streams (comma-separated; 'help' for list).
+  -E | --output-code-dependencies   Output list of dependencies for all compiled modules that require separate compilation of their own.
+  -L | --library-path <path>        Add path to list of directories to search when importing modules.
+  -P | --output-prototypes <prefix> Output C++ header with prototypes for public functionality.
+  -R | --report-times               Report a break-down of compiler's execution time.
+  -S | --skip-dependencies          Do not automatically compile dependencies during JIT.
+  -T | --keep-tmps                  Do not delete any temporary files created.
+  -V | --skip-validation            Don't validate ASTs (for debugging only).
+  -X | --debug-addl <addl>          Implies -d and adds selected additional instrumentation (comma-separated; see 'help' for list).
+  -Z | --enable-profiling           Report profiling statistics after execution.
+       --cxx-link <lib>             Link specified static archive or shared library during JIT or to produced HLTO file. Can be given multiple times.
+       --skip-standard-imports      Do not automatically import standard library modules (for debugging only).
 
   -Q | --include-offsets          Include stream offsets of parsed data in output.
 

diff --git a/hilti/toolchain/src/compiler/driver.cc b/hilti/toolchain/src/compiler/driver.cc
@@ -97,40 +97,40 @@ void Driver::usage() {
            "\n"
            "Options controlling code generation:\n"
            "\n"
-           "  -c | --output-c++                Print out C++ code generated for module (for debugging; use -x to "
+           "  -c | --output-c++                 Print out C++ code generated for module (for debugging; use -x to "
            "generate code for external compilation).\n"
-           "  -d | --debug                     Include debug instrumentation into generated code.\n"
-           "  -e | --output-all-dependencies   Output list of dependencies for all compiled modules.\n"
-           "  -g | --disable-optimizations     Disable HILTI-side optimizations of the generated code.\n"
-           "  -j | --jit-code                  Fully compile all code, and then execute it unless --output-to gives a "
+           "  -d | --debug                      Include debug instrumentation into generated code.\n"
+           "  -e | --output-all-dependencies    Output list of dependencies for all compiled modules.\n"
+           "  -g | --disable-optimizations      Disable HILTI-side optimizations of the generated code.\n"
+           "  -j | --jit-code                   Fully compile all code, and then execute it unless --output-to gives a "
            "file to store it\n"
-           "  -l | --output-linker             Print out only generated HILTI linker glue code (for debugging; use -x "
+           "  -l | --output-linker              Print out only generated HILTI linker glue code (for debugging; use -x "
            "to generate code for external compilation).\n"
-           "  -o | --output-to <path>          Path for saving output.\n"
-           "  -p | --output-hilti              Just output parsed HILTI code again.\n"
-           "  -v | --version                   Print version information.\n"
-           "  -x | --output-c++-files <prefix> Output generated all C++ code into set of files for external "
+           "  -o | --output-to <path>           Path for saving output.\n"
+           "  -p | --output-hilti               Just output parsed HILTI code again.\n"
+           "  -v | --version                    Print version information.\n"
+           "  -x | --output-c++-files <prefix>  Output generated all C++ code into set of files for external "
            "compilation.\n"
-           "  -A | --abort-on-exceptions       When executing compiled code, abort() instead of throwing HILTI "
+           "  -A | --abort-on-exceptions        When executing compiled code, abort() instead of throwing HILTI "
            "exceptions.\n"
-           "  -B | --show-backtraces           Include backtraces when reporting unhandled exceptions.\n"
-           "  -C | --dump-code                 Dump all generated code to disk for debugging.\n"
-           "  -D | --compiler-debug <streams>  Activate compile-time debugging output for given debug streams "
+           "  -B | --show-backtraces            Include backtraces when reporting unhandled exceptions.\n"
+           "  -C | --dump-code                  Dump all generated code to disk for debugging.\n"
+           "  -D | --compiler-debug <streams>   Activate compile-time debugging output for given debug streams "
            "(comma-separated; 'help' for list).\n"
-           "  -E | --output-code-dependencies  Output list of dependencies for all compiled modules that require "
+           "  -E | --output-code-dependencies   Output list of dependencies for all compiled modules that require "
            "separate compilation of their own.\n"
-           "  -L | --library-path <path>       Add path to list of directories to search when importing modules.\n"
+           "  -L | --library-path <path>        Add path to list of directories to search when importing modules.\n"
            "  -P | --output-prototypes <prefix> Output C++ header with prototypes for public functionality.\n"
-           "  -R | --report-times              Report a break-down of compiler's execution time.\n"
-           "  -S | --skip-dependencies         Do not automatically compile dependencies during JIT.\n"
-           "  -T | --keep-tmps                 Do not delete any temporary files created.\n"
-           "  -V | --skip-validation           Don't validate ASTs (for debugging only).\n"
-           "  -X | --debug-addl <addl>         Implies -d and adds selected additional instrumentation "
+           "  -R | --report-times               Report a break-down of compiler's execution time.\n"
+           "  -S | --skip-dependencies          Do not automatically compile dependencies during JIT.\n"
+           "  -T | --keep-tmps                  Do not delete any temporary files created.\n"
+           "  -V | --skip-validation            Don't validate ASTs (for debugging only).\n"
+           "  -X | --debug-addl <addl>          Implies -d and adds selected additional instrumentation "
            "(comma-separated; see 'help' for list).\n"
-           "  -Z | --enable-profiling          Report profiling statistics after execution.\n"
-           "       --cxx-link <lib>            Link specified static archive or shared library during JIT or to "
+           "  -Z | --enable-profiling           Report profiling statistics after execution.\n"
+           "       --cxx-link <lib>             Link specified static archive or shared library during JIT or to "
            "produced HLTO file. Can be given multiple times.\n"
-           "       --skip-standard-imports     Do not automatically import standard library modules (for debugging "
+           "       --skip-standard-imports      Do not automatically import standard library modules (for debugging "
            "only).\n"
         << addl_usage
         << "\n"

diff --git a/spicy/toolchain/bin/spicy-driver.cc b/spicy/toolchain/bin/spicy-driver.cc
@@ -116,9 +116,9 @@ void SpicyDriver::usage() {
            "  -R | --report-times                 Report a break-down of compiler's execution time.\n"
            "  -S | --skip-dependencies            Do not automatically compile dependencies during JIT.\n"
            "  -U | --report-resource-usage        Print summary of runtime resource usage.\n"
-           "  -X | --debug-addl <addl>            Implies -d and adds selected additional instrumentation\n"
-           "  -Z | --enable-profiling             Report profiling statistics after execution.\n"
+           "  -X | --debug-addl <addl>            Implies -d and adds selected additional instrumentation "
            "(comma-separated; see 'help' for list).\n"
+           "  -Z | --enable-profiling             Report profiling statistics after execution.\n"
            "\n"
            "Environment variables:\n"
            "\n"