Improve the usability of manual dump trigger

When using the manual dump trigger option, one dump helper unit per
project is generated containing everything needed to perform a call to
its buffers dumping procedure anywhere in the code.  gnatcov will look
for the pragma statement 'pragma Annotate (Xcov, Dump_Buffers)' (for
Ada) or the comment '/* GNATCOV_DUMP_BUFFERS */ (for C) in all sources
and replace it with the actual call.

Author: Viviane Garèse

doc/gnatcov/src_traces.rst

@@ -273,12 +273,20 @@ For more restricted environments where, say, there is limited file IO available
 to the program, a ``--dump-channel=base64-stdout`` kind of output is needed in
 association with the restricted coverage runtime.
 
-If none of the available automatic triggering option works out well, full
+If none of the available automatic triggering option work out well, full
 control is offered by the ``--dump-trigger=manual`` policy where the
 instrumenter doesn't actually add any code to main units for emitting the
-collected coverage data. You will have to emit this data somehow to allow
-analysing coverage afterwards, still, and can of course experiment with other
-possibilities just to get examples of possible ways to proceed.
+collected coverage data. You will have to indicate the point at which you wish
+to emit this data by inserting:
+
+- a ``pragma Annotate (Xcov, Dump_Buffers);`` pragma statement in Ada code;
+- a ``/* GNATCOV_DUMP_BUFFERS */`` comment on its own line in C code
+
+where necessary in your code. During instrumentation, |gcv| will replace them
+with a call to the procedure responsible for dumping the coverage buffers,
+at which point the source traces will be created during the execution of the
+program. Therefore, the pragma or comment should be placed at a location at
+which such a function call would be appropriate.
 
 .. _instr-tracename:
 

testsuite/SCOV/minicheck.py

@@ -37,7 +37,7 @@ def build_and_run(gprsw, covlevel, mains, extra_coverage_args, scos=None,
                   gprsw_for_coverage=None, scos_for_run=True,
                   register_failure=True, program_env=None,
                   tolerate_instrument_messages=None, exec_args=None,
-                  auto_languages=True):
+                  auto_languages=True, manual_prj_name=None):
     """
     Prepare a project to run a coverage analysis on it.
 
@@ -108,6 +108,10 @@ def build_and_run(gprsw, covlevel, mains, extra_coverage_args, scos=None,
     :param None|list[str] exec_args: List of arguments to pass to the
         executable. This will only work for native configurations.
     :param bool auto_languages: See SUITE.tutils.xcov.
+    :param None|str manual_proj_name: when the dump trigger is manual, several
+        traces files (one per project) can be emitted if there are dump buffers
+        procedure calls in at least two distinct projects. This is the name of
+        the project which trace we want to consider.
 
     :rtype: list[str]
     :return: Incomplete list of arguments to pass to `xcov` in order to run
@@ -283,7 +287,9 @@ def gprbuild_wrapper(root_project):
             # Remove potential existing source trace files: the name is
             # non-deterministic by default, so we want to avoid getting
             # multiple traces in the current directory.
-            rm(srctrace_pattern_for(m))
+            rm(srctrace_pattern_for(m,
+                                    dump_trigger == "manual",
+                                    manual_prj_name))
 
             out_file = out_file_.format(m)
             run_cov_program(exepath(m), out=out_file, env=program_env,
@@ -307,14 +313,20 @@ def gprbuild_wrapper(root_project):
             trace_file = None
 
             if known_channel in [None, "bin-file"]:
-                trace_file = srctracename_for(m, register_failure=False)
+                trace_file = srctracename_for(m,
+                                              register_failure=False,
+                                              manual=dump_trigger == "manual",
+                                              manual_prj_name=manual_prj_name)
 
             if (not trace_file
                 and (known_channel == "base64-stdout"
-                     or "source trace file ==" in contents_of(out_file))
-            ):
+                     or "source trace file ==" in contents_of(out_file))):
+
                 # Pick a trace name that is compatible with srctracename_for
-                trace_file = srctrace_pattern_for(m).replace("*", "unique")
+                src_pattern = srctrace_pattern_for(m,
+                                                   dump_trigger == "manual",
+                                                   manual_prj_name)
+                trace_file = src_pattern.replace("*", "unique")
 
                 # Here we're really supposed to have a trace in the output
                 # so we can be a tad stricter on the conversion outcome.

testsuite/SUITE/tutils.py

@@ -453,12 +453,21 @@ def tracename_for(pgmname):
     return exename_for(pgmname) + ".trace"
 
 
-def srctrace_pattern_for(pgmname):
-    """Glob pattern for the source trace file for the given program name"""
-    return exename_for(pgmname) + "*.srctrace"
+def srctrace_pattern_for(pgmname, manual=False, manual_prj_name=None):
+    """
+    Glob pattern for the source trace file for the given program name.
+
+    :param bool manual: Indicates if the trace file was created as a result of
+        a manual dump buffers procedure call.
+    :param None|str manual_prj_name: Trace files emitted in manual dump trigger
+        mode contain the name of the relevant project in their name.
+        manual_prj_name is the name of the project which trace we want to find.
+    """
+    return (manual_prj_name if manual else exename_for(pgmname)) + "*.srctrace"
 
 
-def srctracename_for(pgmname, register_failure=True):
+def srctracename_for(pgmname, register_failure=True, manual=False,
+                     manual_prj_name=None):
     """
     Name for the source trace file for the given program name.
 
@@ -470,7 +479,7 @@ def srctracename_for(pgmname, register_failure=True):
     stops the testcase. If "register_failure" is False, we just return None in
     that case.
     """
-    pattern = srctrace_pattern_for(pgmname)
+    pattern = srctrace_pattern_for(pgmname, manual, manual_prj_name)
     trace_files = glob.glob(pattern)
 
     if len(trace_files) == 1:

testsuite/tests/instr-cov/ada_manual_dump/src-lib1/lib1.adb

@@ -0,0 +1,9 @@
+package body Lib1 is
+   function Foo return Integer
+   is
+      Res : constant Integer := 1;
+   begin
+      pragma Annotate (Xcov, Dump_Buffers);
+      return Res;
+   end Foo;
+end Lib1;

testsuite/tests/instr-cov/ada_manual_dump/src-lib1/lib1.ads

@@ -0,0 +1,3 @@
+package Lib1 is
+   function Foo return Integer;
+end Lib1;

testsuite/tests/instr-cov/ada_manual_dump/src-lib2/lib2.adb

@@ -0,0 +1,9 @@
+package body Lib2 is
+   function Bar return Integer
+   is
+      Res : constant Integer := 1;
+   begin
+      pragma Annotate (Xcov, Dump_Buffers);
+      return Res;
+   end Bar;
+end Lib2;

testsuite/tests/instr-cov/ada_manual_dump/src-lib2/lib2.ads

@@ -0,0 +1,3 @@
+package Lib2 is
+   function Bar return Integer;
+end Lib2;

testsuite/tests/instr-cov/ada_manual_dump/src/main.adb

@@ -0,0 +1,30 @@
+pragma Ada_2012;
+
+with Lib1;
+with Lib2;
+with Manual_Dump;
+
+procedure Main is
+
+   procedure Increment (J : in out Integer)
+   is
+   begin
+      J := J + 1;
+   end Increment;
+
+   I : Integer := 1;
+begin
+    -- The only call that should not count as a violation when never executed
+    -- is that of the dump buffers procedure.
+   if 1 = I + 1 then
+      pragma Annotate (Xcov, Dump_Buffers);
+      I := I+ 1;
+   end if;
+
+   Increment (I);
+   pragma Annotate (Xcov, Dump_Buffers);
+   I := I + Lib1.Foo;
+   I := I + Lib2.Bar;
+   Manual_Dump.Dump;
+   Increment (I);
+end Main;

testsuite/tests/instr-cov/ada_manual_dump/src/manual_dump.adb

@@ -0,0 +1,6 @@
+package body Manual_Dump is
+   procedure Dump is
+   begin
+      pragma Annotate (Xcov, Dump_Buffers);
+   end Dump;
+end Manual_Dump;

testsuite/tests/instr-cov/ada_manual_dump/src/manual_dump.ads

@@ -0,0 +1,3 @@
+package Manual_Dump is
+   procedure Dump;
+end Manual_Dump;