Add sources for the src-trace library instrumentation example

Author: leocreuse

doc/gnatcov/src_traces.rst

@@ -1038,6 +1038,10 @@ For the sake of the example, we will consider that
   by each new test individually or for the current set of tests
   at a given point in time.
 
+The sources for this example can be found under the
+`share/examples/gnatcoverage/doc/library_instr/` directory of the GNATDAS
+distribution.
+
 Setting up the coverage runtime
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

tools/gnatcov/examples/doc/library_instr/Makefile

@@ -0,0 +1,44 @@
+# Project demonstrating how to instrument and get coverage over a library, and
+# distribute the instrumented library independently, leveraging the
+# Externally_Built GPR attribute.
+#
+# See paragraph "Example use cases" of the
+# "Producing source traces with gnatcov instrument" section for more details
+
+RTS_DIR = rts_install
+
+.PHONY: instrument build run coverage
+
+default: coverage
+
+# Only needs to be called once, can be re-used across multiple GNATcov workflows
+$(RTS_DIR)/share/gpr/gnatcov_rts.gpr:
+	gnatcov setup --prefix=$(RTS_DIR)
+
+instrument-lib: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
+instrument-lib: $(RTS_DIR)/share/gpr/gnatcov_rts.gpr
+	@echo 'export GPR_PROJECT_PATH=$$(pwd)/$(RTS_DIR)/share/gpr:$$GPR_PROJECT_PATH'
+	gnatcov instrument -P code.gpr --level=stmt -XCODE_LIBMODE=instrument
+
+build-lib: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
+build-lib: instrument
+	gprbuild -f -p -P code.gpr --src-subdirs=gnatcov-instr --implicit-with=gnatcov_rts.gpr \
+	-XCODE_LIBMODE=build
+
+instrument-test: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
+instrument-test: instrument-lib
+	gnatcov instrument -P tests.gpr --level=stmt --externally-built-projects --dump-trigger=atexit
+
+build-test: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
+build-test: instrument-test build-lib
+	gprbuild -P tests.gpr --src-subdirs=gnatcov-instr --implicit-with=gnatcov_rts.gpr
+
+run: build-test
+	./obj-tests/test_inc
+
+coverage: run
+	gnatcov coverage -P tests.gpr --level=stmt --annotate=xcov test_inc*.srctrace --externally-built-projects
+	cat obj-tests/ops.adb.xcov
+
+clean:
+	rm -rf obj-* $(RTS_DIR) test_inc*.srctrace lib-*

tools/gnatcov/examples/doc/library_instr/code.gpr

@@ -0,0 +1,18 @@
+library project Code is
+  for Source_Dirs use ("code");
+  for Object_Dir use "obj-" & Project'Name;
+
+  for Library_Dir use "lib-" & project'Name;
+  for Library_Kind use "static";
+  for Library_Name use "code";
+
+  type Mode is ("build", "instrument", "use");
+  LIB_MODE : Mode := external ("CODE_LIBMODE", "use");
+
+  case LIB_MODE is
+     when "build"      => for Externally_Built use "False";
+     when "instrument" => for Externally_Built use "False";
+     when "use"        => for Externally_Built use "True";
+  end case;
+
+end Code;

tools/gnatcov/examples/doc/library_instr/code/ops.adb

@@ -0,0 +1,14 @@
+------------------------------------------------------------------------------
+--                              GNATcoverage                                --
+--                     Copyright (C) 2012-2025, AdaCore                     --
+------------------------------------------------------------------------------
+
+package body Ops is
+   procedure Apply (Op : Op_Kind; X : in out Integer) is
+   begin
+      case Op is
+         when Increment => X := X + 1;
+         when Decrement => X := X - 1;
+      end case;
+   end Apply;
+end Ops;

tools/gnatcov/examples/doc/library_instr/code/ops.ads

@@ -0,0 +1,9 @@
+------------------------------------------------------------------------------
+--                              GNATcoverage                                --
+--                     Copyright (C) 2012-2025, AdaCore                     --
+------------------------------------------------------------------------------
+
+package Ops is
+   type Op_Kind is (Increment, Decrement);
+   procedure Apply (Op : Op_Kind; X : in out Integer);
+end Ops;

tools/gnatcov/examples/doc/library_instr/tests.gpr

@@ -0,0 +1,12 @@
+with "code.gpr";
+
+project Tests is
+  for Source_Dirs use ("tests");
+  for Object_Dir use "obj-" & Project'Name;
+
+  for Main use ("test_inc.adb");
+
+  package Coverage is
+    for Units use ();
+  end Coverage;
+end Tests;

tools/gnatcov/examples/doc/library_instr/tests/test_inc.adb

@@ -0,0 +1,13 @@
+------------------------------------------------------------------------------
+--                              GNATcoverage                                --
+--                     Copyright (C) 2012-2025, AdaCore                     --
+------------------------------------------------------------------------------
+
+with Ops;
+
+procedure Test_Inc is
+   X : Integer := 4;
+begin
+   Ops.Apply (Ops.Increment, X);
+   pragma Assert (X = 5);
+end Test_Inc;