Skip to content

Latest commit

 

History

History
108 lines (82 loc) · 4.64 KB

run_control.rst

File metadata and controls

108 lines (82 loc) · 4.64 KB
Raw

Execution environment

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

  • When |gem| for the base target is available on your PATH, as <base-target>-gnatemu, |gcv| uses this to run the program. |gem| 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 :cmd-option:`--target` argument, the specified board name is passed as an extra :cmd-option:`--board=<board-name>` command line option to |gem|.
  • Otherwise, |gcv| resorts to a builtin low level emulator statically configured for the base target. An unsupported target error is issued and |gcv| 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, |gcvrun| supports several ways of selecting the program to execute:

  • If an :ref:`[EXE] <exe>` argument is provided on the base command line, before :cmd-option:`eargs`, use it as the candidate program name to execute. Otherwise:
  • If :ref:`eargs <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 :cmd-option:`-P`, and this project features a single Main attribute, use the corresponding executable name as the program to execute.

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

In cross configurations, :cmd-option:`eargs` switches are passed straight to the low-level emulation engine. They are not interpreted by |gem| when it is used. Passing arguments to |gem| via |gcvrun| 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 :cmd-option:`-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 |gcv| 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".