Execution environment

For cross configurations, the --target command line option allows specifying the target environment for which the program was built and for which gnatcov run should pick a suitable execution environment. The option states a base target name possibly followed by a board specialization after a separating ‘,’ (--target=powperpc-eabispe,mpc5566 for example). When a simple target name alone is sufficient, it is possible to let gnatcov detect it from the Target attribute from the project file (see Specifying the Target and language Runtime section). Then:

• When GNATemulator for the base target is available on your PATH, as <base-target>-gnatemu, gnatcov uses this to run the program. GNATemulator acts as a wrapper around the real machine emulator in this case, taking care of low-level interfacing details. If an optional board extension is provided in the --target argument, the specified board name is passed as an extra --board= command line option to GNATemulator.

• Otherwise, gnatcov resorts to a builtin low level emulator statically configured for the base target. An unsupported target error is issued and gnatcov exits if no such configuration is found to match.

Program selection and Arguments passing

To facilitate the coverage analysis integration within different kinds of environments, gnatcov run supports several ways of selecting the program to execute:

• If an [EXE] argument is provided on the base command line, before eargs, use it as the candidate program name to execute. Otherwise:

• If eargs are provided and the first item designates an executable file, use this as the program to execute. Otherwise:

• If a root project file is designated with -P, and this project features a single Main attribute, use the corresponding executable name as the program to execute.

The eargs switches not used as the program name are then used differently in cross or native configurations, as differentiated by the use of a --target option.

In cross configurations, eargs switches are passed straight to the low-level emulation engine. They are not interpreted by GNATemulator when it is used. Passing arguments to GNATemulator via gnatcov run can be achieved by way of a GNAT project file, with a Switches attribute in the Emulator package. For example:

-- covemu.gpr
project Covemu is
  package Emulator is
    for Switches use ("--gnatbus=bridge.bar.com:1800");
  end Emulator;
end Covemu;

Then:

gnatcov run --target=<target> -Pcovemu.gpr

In native configurations, the program executes in the host environment and the -eargs switches are passed as command line arguments to the executable program.

This way users can just prefix a regular host command line by “gnatcov run … -eargs” to produce execution traces, as illustrated by the native case in the set of valid gnatcov command line examples below:

gnatcov run --target=powerpc-elf myprog
# Run "myprog" using powerpc-elf-gnatemu as the execution environment.
# Produce myprog.trace in the current directory.

gnatcov run --target=powerpc-elf myprog -o myrun.trace
# Likewise, producing myrun.trace instead, still in the current directory

gnatcov run --target=powerpc-elf myprog -o myrun.trace -eargs --version
# Likewise, also requesting version output from the low level execution
# engine, *not* from gnatemulator if it happens to be involved.

gnatcov run --target=powerpc-elf -o myrun.trace -eargs myprog --version
# Likewise, providing the executable program to run as the first earg

gnatcov run --target=powerpc-elf -o myrun.trace -Pmyprj.gpr -eargs --version
# Likewise, inferring the executable program name from the Main attribute
# in myprj.gpr.

gnatcov run --target=powerpc-elf myprog -T "trace for doc example"
# Providing a trace tag, that can de retrieved with trace dump facilities
# and which is displayed in some output reports.

gnatcov run --target=powerpc-eabispe myprog
# Run "myprog" using powerpc-eabispe-gnatemu as the execution environment.
# Produce myprog.trace in the current directory.

gnatcov run --target=powerpc-eabispe,mpc5566 myprog
# Likewise, instructing gnatemu to select the "mpc5566" board emulation.

gnatcov run -eargs myprog arg1 arg2
# Where supported, run "myprog" in the native environment through an
# instrumentation layer to produce the execution trace. Pass arg1 and arg2
# as command line arguments to "myprog".