Adds support for --help option (#170)

Fixes #165

Author: NanoNabla

scorep/__main__.py

@@ -3,14 +3,48 @@
 
 import scorep.instrumenter
 import scorep.subsystem
-from scorep.helper import print_err
+import scorep.helper
+from scorep.helper import get_scorep_version, print_err
 
 
 def _err_exit(msg):
     print_err("scorep: " + msg)
     sys.exit(1)
 
 
+def print_help():
+    print("""\
+Usage: python -m scorep [options] [--] <script> [args]
+
+Score-P Python instrumentation wrapper. The following options control how the program is instrumented and executed. Any unknown option are passed directly to 'scorep-config'.
+
+  --help                   Show this help message and exit.
+  --keep-files             Keep temporary files after execution.
+  --verbose, -v            Enable verbose output for debugging and tracing.
+  --nopython               Disable instrumentation of Python code.
+                           Instrumentation can still be enabled later from within the application's source code.
+  --noinstrumenter         Same as --nopython.
+  --instrumenter-type=<type>
+                           Specify custom instrumenter type (e.g., cProfile).
+  --instrumenter-file=<file>
+                           Path to a Python script that is executed before the application.
+                           Allows instrumentation of specific modules and functions without modifying their source code.
+  --                       Stop parsing Score-P options; interpret all following arguments verbatim as the program with its arguments.
+
+Other options starting with '-' are passed directly to 'scorep-config'.
+To view all available Score-P configuration options, run: scorep-config --help
+
+Example:
+  scorep --mpi --thread=pthread -- ./your_script.py --arg1 --arg2
+
+Note:
+  If using --noinstrumenter, Score-P will not trace Python code, but it may still collect MPI or threading events
+    if configured.
+  You can enable Python instrumentation manually from within your application's source code,
+     e.g., by calling 'scorep.instrumenter.enable()'.
+""")  # noqa: E501
+
+
 def scorep_main(argv=None):
     if argv is None:
         argv = sys.argv
@@ -19,9 +53,11 @@ def scorep_main(argv=None):
     prog_argv = []
     parse_scorep_commands = True
 
+    show_help = False
     keep_files = False
     verbose = False
     no_instrumenter = False
+
     if scorep.instrumenter.has_c_instrumenter():
         instrumenter_type = "cProfile"
     else:
@@ -32,7 +68,12 @@ def scorep_main(argv=None):
         if parse_scorep_commands:
             if elem == "--":
                 parse_scorep_commands = False
+            if elem == "--help":
+                show_help = True
+                break
             elif elem == "--mpi":
+                print_err(f"scorep: Warning: The option '{elem}' is deprecated "
+                          "and will be removed in future.")
                 scorep_config.append("--mpp=mpi")
             elif elem == "--keep-files":
                 keep_files = True
@@ -42,7 +83,7 @@ def scorep_main(argv=None):
                 no_instrumenter = True
             elif elem == "--noinstrumenter":
                 no_instrumenter = True
-            elif elem in ["--io=runtime:posix", "--io=posix"]:
+            elif elem in ["--io=runtime:posix", "--io=posix"] and get_scorep_version() >= 9.0:
                 print_err(f"scorep: Warning: The option '{elem}' is deprecated.")
                 if "SCOREP_IO_POSIX" in os.environ:
                     print_err("        Will not overwrite existing value for environment variable "
@@ -64,6 +105,10 @@ def scorep_main(argv=None):
         else:
             prog_argv.append(elem)
 
+    # fast exit on "--help"
+    if show_help:
+        print_help()
+        sys.exit(0)
     if len(prog_argv) == 0:
         _err_exit("Did not find a script to run")
 

test/test_scorep.py

@@ -463,3 +463,10 @@ def test_force_finalize(scorep_env, instrumenter):
     trace = OTF2_Trace(trace_path)
     assert OTF2_Region("__main__:foo") in trace
     assert OTF2_Region("__main__:bar") not in trace
+
+
+def test_help():
+    std_out, std_err = utils.call_with_scorep("", ["--help"])
+
+    assert "Usage: python -m scorep" in std_out
+    assert "--help" in std_out