Document setup and build steps when building insturmented code with CCG

This includes the modifications to be done to the coverage runtime,
as well as the additionnal switches to be passed to GPRbuild.

Author: leocreuse

doc/gnatcov/src_traces.rst

@@ -972,6 +972,7 @@ the default coverage runtime library, in practice only one use case is
 supported currently: changing the behavior of the
 ``--dump-channel=base64-stdout`` instrumentation option.
 
+.. _custom_base_64:
 
 Customize the ``base64-stdout`` dump channel
 --------------------------------------------
@@ -1037,3 +1038,71 @@ file so that it implements the interface described in the (unmodified)
      const char *str;
      size_t length;
    };
+
+Building instrumented programs with CCG
+=======================================
+
+Programs instrumented with |gcvins| can be built using the
+`GNAT Pro Common Code Generator <https://docs.adacore.com/live/wave/gnat-ccg/html/gnatccg_ug/gnat_ccg.html>`_
+provided a few modifications are made to the coverage runtime, and
+respecting some limitations in terms of dump-trigger and dump-channel choice.
+
+Customizing the runtime
+-----------------------
+
+Given the workflow associated with CCG, it is not possible to use the |gcvstp|
+command to setup the coverage runtime. Instead, it must be prepared manually.
+
+The coverage runtime contains both Ada and C sources. When using CCG through
+GPRbuild, projects containing C sources are not well handled and some steps of
+the build procedure won't be executed. There thus is an external variable to
+remove all C sources from the project. This means that C sources must be
+manually managed during the executable compilation later on.
+
+The first step is to copy the runtime sources in a dedicated directory. For the
+remainder of this section, it will be denoted by ``ccg_gnatcov_rts``.
+
+.. code-block:: sh
+
+   mkdir ccg_gnatcov_rts
+   cp -r <gnatdas_install_dir>/share/gnatcoverage/gnatcov_rts ccg_gnatcov_rts
+
+Then, C sources not relevant to the coverage runtime for the CCG configuration
+must be deleted:
+
+.. code-block:: sh
+
+   rm ccg_gnatcov_rts/gnatcov_rts_c-base-io.c
+   rm ccg_gnatcov_rts/gnatcov_rts_c-trace-output-files.*
+   rm ccg_gnatcov_rts/gnatcov_rts_c-os_interface.*
+
+Finally, it is necessary to modify the contents of
+``ccg_gnatcov_rts/gnatcov_rts-base_io.adb`` to use an alternate medium on which
+the execution trace will be output. By default this relies on ``GNAT.IO``,
+which is not available in the CCG runtime. It is possible to replace occurrences
+of this unit by ``Ada.Text_IO``, which is supported by CCG, but which relies on
+the C standard function ``putchar``. Otherwise, see :ref:`custom_base_64` for
+more details on the expected interface to dump the coverage trace information.
+
+Building an instrumented program with CCG
+-----------------------------------------
+
+Building an instrumented program with CCG is done in the same manner as with
+any other target, with the exception that GPRbuild must be instructed to use
+the custom coverage runtime prepared in the previous step, and by setting an
+external variable to configure the coverage runtime project for a build with
+CCG:
+
+.. code-block:: sh
+
+   gprbuild -P <user_project.gpr> --src-subdirs=gnatcov-instr \
+     --implicit-with=ccg_gnatcov_rts/gnatcov_rts.gpr \
+     -XGNATCOV_RTS_FOR_CCG=true \
+     <relevant target cargs>
+
+After the generation of C sources is complete, all the coverage runtime C sources
+must be included in the build process of the executable. These can be found
+under ``ccg_gnatcov_rts/`` for the sources already present before the gprbuild
+invocation, and under ``ccg_gnatcov_rts/obj-gnatcov_rts.static`` for the sources
+generated by CCG. The C sources generated from the instrumented Ada sources will
+be available in the object directory of their corresponding project.