Skip to content

Commit 370a2e6

Browse files
leocreuseleocreuse
committed
Merge branch 'topic/387-doc-examples' into 'master'
Add sources for various documentation examples in the examples directory See merge request eng/das/cov/gnatcoverage!786 This adds examples sources and projects matching those in the `getting_started` section, as well as those in the instrumentation example. Examples for subsequent sections have not yet been added, they will come as part of a subsequent MR. Part of eng/das/cov/gnatcoverage#387
2 parents 507c8dc + 8f5a832 commit 370a2e6

38 files changed

+549
-38
lines changed

‎doc/gnatcov/examples/Makefile

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
TARGET=powerpc-elf
2-
RTS=zfp-prep
3-
41
XCOVLEVEL=stmt
52
ANNOTATE=xcov
63

74
# unit test name and gpr file
85

9-
UT=
6+
UT= #test_...
107
GPR=ut.gpr
118
TDIR=_$(UT:test_%=%)
129
OSUBDIR=obj
@@ -20,14 +17,12 @@ build:
2017
@echo ' for Source_Dirs use ("../src");' >> $(GPR)
2118
@echo ' for Object_Dir use "$(OSUBDIR)";' >> $(GPR)
2219
@echo 'end UT;' >> $(GPR)
23-
gprbuild -p -f --target=$(TARGET) --RTS=$(TARGET)/$(RTS) -P$(GPR) $(UT).adb \
24-
-cargs:Ada -gnateS -gnaty -gnatwe -cargs -g -fpreserve-control-flow \
25-
-bargs -A=$(UT).alis
20+
gnatcov instrument -P$(GPR) --level=$(XCOVLEVEL) --dump-filename-simple \
21+
--units=$(UT) $(UT).adb
22+
gprbuild -p -f -P$(GPR) $(UT).adb --src-subdirs=gnatcov-instr \
23+
--implicit-with=gnatcov_rts.gpr
2624

2725
run:
28-
gnatcov run $(OSUBDIR)/$(UT)
29-
grep -v xxsupport.ali $(OSUBDIR)/$(UT).alis > alis
30-
gnatcov coverage --level=$(XCOVLEVEL) --scos=@alis \
31-
--annotate=$(ANNOTATE) $(UT).trace
32-
33-
26+
$(OSUBDIR)/$(UT)
27+
gnatcov coverage --level=$(XCOVLEVEL) -P$(GPR) \
28+
--annotate=$(ANNOTATE) --units=$(UT) $(UT).srctrace

‎doc/gnatcov/examples/starter/ops.gpr

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎doc/gnatcov/getting_started.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,10 @@ time.
114114
Sample project
115115
--------------
116116

117+
The sources for this examples are provided under the
118+
`share/examples/gnatcoverage/doc/getting_started/` directory of the GNATDAS
119+
distribution.
120+
117121
We consider an Ada package providing a set of elementary operations
118122
over ``Integer`` objects, with a spec and body in source files named
119123
``ops.ads`` and ``ops.adb``:

‎doc/gnatcov/integrated_instr.rst

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,10 @@ generated compiler wrapper instead of the original compiler.
6262
A simple Makefile example
6363
=========================
6464

65+
The sources for the following example can be found under the
66+
``share/examples/gnatcoverage/doc/integrated`` directory of the GNATDAS
67+
distribution.
68+
6569
The following considers that the instrumentation runtime was previously
6670
installed with ``gnatcov setup``, and that the ``GPR_PROJECT_PATH`` variable
6771
contains its installed location. See :ref:`instr-rts`.
@@ -111,6 +115,12 @@ when run, that can be analyzed with ``gnatcov coverage``.
111115
A simple CMake example
112116
======================
113117

118+
The sources for the following example can be found under the
119+
``share/examples/gnatcoverage/doc/integrated`` directory of the GNATDAS
120+
distribution. To ensure that the Makefile provided with the example sources
121+
uses CMake as a build system, specify ``BUILD_SYSTEM=CMake`` on the `make`
122+
invocation.
123+
114124
The following considers that the instrumentation runtime was installed through
115125
the use of ``gnatcov setup``.
116126

@@ -129,8 +139,8 @@ The CMakeLists.txt file to be used to compile the main.cpp file is :
129139

130140
.. code-block:: cmake
131141
142+
cmake_minimum_required(VERSION 3.5)
132143
project(HelloWorld)
133-
cmake_minimum_required(VERSION 3.0)
134144
135145
add_executable(hello_world main.cpp)
136146

‎doc/gnatcov/src_traces.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -844,6 +844,10 @@ Its contents are:
844844
pragma Ignore_Pragma (Refined_Global);
845845
pragma Ignore_Pragma (Refined_Depends);
846846
847+
The source for the following example can be found under the
848+
`share/examples/gnatcoverage/spark_instrumentation/` directory of the GNATDAS
849+
distribution.
850+
847851
The configuration pragma file can be passed to the compiler either by
848852
specifying it on the gprbuild command line with the ``-gnatec`` switch::
849853

@@ -908,6 +912,10 @@ Here we will consider examining the coverage achieved by the execution of the
908912
very basic sample program below, assuming the existence of a ``Sensors``
909913
source unit providing access to some sensor values.
910914

915+
The sources for this example can be found under the
916+
`share/examples/gnatcoverage/doc/cross_example` directory of the GNATDAS
917+
disctribution.
918+
911919
.. code-block:: ada
912920
913921
with Sensors; use Sensors;
@@ -1030,6 +1038,10 @@ For the sake of the example, we will consider that
10301038
by each new test individually or for the current set of tests
10311039
at a given point in time.
10321040

1041+
The sources for this example can be found under the
1042+
`share/examples/gnatcoverage/doc/library_instr/` directory of the GNATDAS
1043+
distribution.
1044+
10331045
Setting up the coverage runtime
10341046
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
10351047

‎doc/gnatcov/units_of_interest.rst

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,10 @@ unit of interest encompass some of its testing sources, for example
266266
when parts of the testing code is implemented with ``separate``
267267
subunits in Ada.
268268

269+
The sources for the following example can be found under the
270+
`share/examples/gnatcoverage/doc/subunits/` directory of the GNATDAS
271+
distribution.
272+
269273
The dummy example below shows a possible organization of this kind,
270274
with a ``Data_Processing`` package to be tested which contains a ``Test``
271275
procedure declared as a ``separate`` entity::
@@ -312,10 +316,23 @@ one or the other based on a scenario variable::
312316
pragma Assert (Internal_Data < 0);
313317
end;
314318

319+
-- run_all.adb; main file to run the test
320+
321+
with Data_Processing;
322+
procedure Run_All is
323+
begin
324+
Data_Processing.Test;
325+
end;
326+
315327
-- Project file with a Body source file name selection in a
316328
-- Naming project package:
317329

318330
project P is
331+
332+
for Object_Dir use "obj";
333+
for Source_Dirs use ("src");
334+
for Main use ("run_all.adb");
335+
319336
TEST := external ("TEST");
320337
package Naming is
321338
for Body ("data_processing.test") use "data_processing-" & TEST & ".adb";
@@ -324,16 +341,8 @@ one or the other based on a scenario variable::
324341

325342
Then we can build one variant or the other with::
326343

327-
-- run_all.adb
328-
329-
with Data_Processing;
330-
procedure Run_All is
331-
begin
332-
Data_Processing.Test;
333-
end;
334-
335-
$ gprbuild -Pp.gpr -XTEST=test1 run_all.adb
336-
$ gprbuild -Pp.gpr -XTEST=test2 run_all.adb
344+
$ gprbuild -Pp.gpr -XTEST=test1
345+
$ gprbuild -Pp.gpr -XTEST=test2
337346
...
338347

339348
As any testing code, such subunits usually need to be excluded from

‎tools/gnatcov/examples/README.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
This directory contains a few examples illustrating possible ways to build, run
22
and do coverage analysis with GNAT Pro and GNATcoverage
33

4-
Except `support`, each subdirectory hosts an example and features a Makefile
5-
that allows launching a complete build/run/analyze sequence for a variety of
6-
targets, assuming you have the corresponding GNAT & GNATemulator products
7-
installed.
4+
Except `support` and `doc`, each subdirectory hosts an example and features a
5+
Makefile that allows launching a complete build/run/analyze sequence for a
6+
variety of targets, assuming you have the corresponding GNAT & GNATemulator
7+
products installed.
8+
9+
The `doc` subdirectory holds the sources used in the various examples in the
10+
user's manual. Each one also features a Makefile that replicates the commands
11+
demonstrated in the user's manual relevant section. These examples only work
12+
for native targets.
813

914
The `support` subdirectory is common to all the other ones, and additional
1015
information about the general Makefile and project files structure is available
@@ -16,7 +21,7 @@ to use by setting the `TARGET` and `RTS` variables explicitly:
1621

1722
```shell
1823
make TARGET=powerpc-elf RTS=light-mpc8641 runs on bare PowerPC
19-
make TARGET=leon3-elf RTS=light-leon3 runs on bare LEON2
24+
make TARGET=leon3-elf RTS=light-leon3 runs on bare LEON3
2025
```
2126

2227
as well as:

‎tools/gnatcov/examples/doc/README.examples

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Documentation examples
2+
----------------------
3+
4+
This directory contains the sources of the examples used throughout the
5+
GNATcoverage user's manual, Each directory contains the sources and project for
6+
a single example, as well as a Makefile that reproduces (in a linux or cygwin
7+
environment) the commands described in the relevant documentation section.
8+
9+
The Makefiles start with a comment briefly describing the example, the
10+
demonstrated feature, and referencing the corresponding section in the user's
11+
manual. It is best to go through these examples by following the indications
12+
in the user's manual, as they will be much more detailed, and may provide
13+
additional context.
14+
15+
When a section name is referenced, either in this document, or in the Makefile
16+
comments, this is always a section within the GNATcoverage manual, which is
17+
itself a subset of the GNATDAS user's manual.
18+
19+
20+
- getting_started: A simple project on which the general GNATcoverage workflow
21+
is demonstrated. See section "Getting Started" of the manual for more
22+
information.

‎tools/gnatcov/examples/doc/cross_example/Makefile

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Example demonstrating how to instrument a project for a cross configuration,
2+
# with a restricted runtime. By default the example runs on a native target, as
3+
# the binary execution step differs for each target.
4+
5+
RTS?=light
6+
TARGET?=
7+
8+
# target & runtime options to be passed to all gnatcov & gprbuild commands
9+
GPR_ARGS=
10+
11+
ifneq ($(TARGET),)
12+
GPR_ARGS = --target=$(TARGET)
13+
endif
14+
15+
ifneq ($(RTS),)
16+
GPR_ARGS := $(GPR_ARGS) --RTS=$(RTS)
17+
endif
18+
19+
RTS_DIR = rts_install
20+
21+
.PHONY: instrument build run coverage
22+
23+
default: coverage
24+
25+
# Only needs to be called once, can be re-used across multiple GNATcov workflows
26+
$(RTS_DIR)/share/gpr/gnatcov_rts.gpr:
27+
gnatcov setup $(GPR_ARGS) --prefix=$(RTS_DIR)
28+
29+
insturment: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
30+
instrument: $(RTS_DIR)/share/gpr/gnatcov_rts.gpr
31+
@echo 'export GPR_PROJECT_PATH=$$(pwd)/$(RTS_DIR)/share/gpr:$$GPR_PROJECT_PATH'
32+
gnatcov instrument -P monitor.gpr $(GPR_ARGS) --level=stmt+decision \
33+
--dump-channel=base64-stdout --dump-trigger=main-end
34+
35+
build: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
36+
build: instrument
37+
gprbuild -f -p -P monitor.gpr $(GPR_ARGS) --src-subdirs=gnatcov-instr --implicit-with=gnatcov_rts.gpr
38+
39+
ifeq ($(TARGET),)
40+
run: build
41+
./obj/monitor > monitor.stdout
42+
@cat monitor.stdout
43+
else
44+
run: build
45+
@echo I don't know how to execute a binary for $(TARGET), please modify line 40 of the Makefile,\n\
46+
the output of the program should be captured in the monitor.stdout file. && false
47+
endif
48+
49+
coverage: run
50+
gnatcov extract-base64-trace monitor.stdout monitor.srctrace
51+
gnatcov coverage -P monitor.gpr $(GPR_ARGS) --level=stmt+decision --annotate=xcov monitor.srctrace
52+
cat obj/monitor.adb.xcov
53+
54+
clean:
55+
rm -rf obj $(RTS_DIR) monitor.srctrace monitor.stdout

‎tools/gnatcov/examples/doc/cross_example/monitor.gpr

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
project Monitor is
2+
for Object_Dir use "obj";
3+
for Source_Dirs use ("src");
4+
for Main use ("monitor.adb");
5+
end Monitor;

‎tools/gnatcov/examples/doc/cross_example/src/monitor.adb

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
------------------------------------------------------------------------------
2+
-- GNATcoverage --
3+
-- Copyright (C) 2012-2025, AdaCore --
4+
------------------------------------------------------------------------------
5+
6+
with Sensors; use Sensors;
7+
with Ada.Text_IO; use Ada.Text_IO;
8+
9+
procedure Monitor is
10+
Sensor_Value : Integer;
11+
begin
12+
for Sensor_Index in Sensor_Index_Range loop
13+
Sensor_Value := Sensors.Value (Sensor_Index);
14+
Put ("Sensor(" & Sensor_Index'Img & ") = " & Sensor_Value'Img & " ");
15+
if (Sensor_Value > 1000) then
16+
Put_Line ("!Alarm!");
17+
else
18+
Put_Line ("!Ok!");
19+
end if;
20+
end loop;
21+
end;

‎tools/gnatcov/examples/doc/cross_example/src/sensors.adb

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
------------------------------------------------------------------------------
2+
-- GNATcoverage --
3+
-- Copyright (C) 2012-2025, AdaCore --
4+
------------------------------------------------------------------------------
5+
6+
package body Sensors is
7+
8+
function Value (Index : Sensor_Index_Range) return Integer is
9+
begin
10+
-- Dummy implementation, for demonstration purposes
11+
12+
case Index is
13+
when 1 => return 1;
14+
when 2 => return 5;
15+
when 3 => return 3;
16+
when 4 => return 7;
17+
end case;
18+
end Value;
19+
20+
end Sensors;

‎tools/gnatcov/examples/doc/cross_example/src/sensors.ads

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
------------------------------------------------------------------------------
2+
-- GNATcoverage --
3+
-- Copyright (C) 2012-2025, AdaCore --
4+
------------------------------------------------------------------------------
5+
6+
package Sensors is
7+
8+
type Sensor_Index_Range is range 1 .. 4;
9+
10+
function Value (Index : Sensor_Index_Range) return Integer;
11+
12+
end Sensors;

‎tools/gnatcov/examples/doc/getting_started/Makefile

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Simple project demonstrating the usual GNATcoverage workflow.
2+
# See section "Getting Started" in GNATcoverage's user manual for more
3+
# details.
4+
5+
RTS_DIR = rts_install
6+
7+
.PHONY: instrument build run coverage
8+
9+
default: coverage
10+
11+
# Only needs to be called once, can be re-used across multiple GNATcov workflows
12+
$(RTS_DIR)/share/gpr/gnatcov_rts.gpr:
13+
gnatcov setup --prefix=$(RTS_DIR)
14+
15+
instrument: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
16+
instrument: $(RTS_DIR)/share/gpr/gnatcov_rts.gpr
17+
@echo 'export GPR_PROJECT_PATH=$$(pwd)/$(RTS_DIR)/share/gpr:$$GPR_PROJECT_PATH'
18+
gnatcov instrument -P tests.gpr --level=stmt
19+
20+
build: export GPR_PROJECT_PATH := $(shell pwd)/$(RTS_DIR)/share/gpr:$(GPR_PROJECT_PATH)
21+
build: instrument
22+
gprbuild -f -p -P tests.gpr --src-subdirs=gnatcov-instr --implicit-with=gnatcov_rts.gpr
23+
24+
run: build
25+
./obj-tests/test_inc
26+
27+
coverage: run
28+
gnatcov coverage -P tests.gpr --level=stmt --annotate=xcov test_inc*.srctrace
29+
cat obj-tests/ops.adb.xcov
30+
31+
clean:
32+
rm -rf obj-* $(RTS_DIR) test_inc*.srctrace

‎tools/gnatcov/examples/doc/getting_started/code.gpr

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
project Code is
2+
for Source_Dirs use ("opslib");
3+
for Object_Dir use "obj-" & Project'Name;
4+
end Code;

‎doc/gnatcov/examples/starter/src/ops.adb renamed to ‎tools/gnatcov/examples/doc/getting_started/opslib/ops.adb

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
------------------------------------------------------------------------------
22
-- GNATcoverage --
3-
-- Copyright (C) 2012-2021, AdaCore --
3+
-- Copyright (C) 2012-2025, AdaCore --
44
------------------------------------------------------------------------------
55

66
package body Ops is

‎doc/gnatcov/examples/starter/src/ops.ads renamed to ‎tools/gnatcov/examples/doc/getting_started/opslib/ops.ads

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
------------------------------------------------------------------------------
22
-- GNATcoverage --
3-
-- Copyright (C) 2012-2021, AdaCore --
3+
-- Copyright (C) 2012-2025, AdaCore --
44
------------------------------------------------------------------------------
55

66
package Ops is

0 commit comments

Comments
 (0)