// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-coco.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Measure and check code coverage

    With Coco, you can measure and the code coverage of tests. The Coco plugin
    supports the setup of a project for code coverage and the display of the
    coverage inside Qt Creator.

    To use the plugin, you must download and install Coco version 6.0 or later.

    \note Enable the Coco plugin to use it.

    \section1 Configuring the plugin

    There is a settings page at \preferences > \uicontrol Coco with which you
    can set the directory in which Coco is installed. But in most cases, the default
    settings need not to be changed.

    \section1 Measure code coverage

    With the Coco plugin, it is possible to set up code coverage easily for Qt Creator
    projects that are built with QMake or CMake.

    The general idea is that you take an existing build configuration, like "Debug",
    clone it with a new name (like "DebugCoverage") and then use the plugin to
    configure it for the use with Coco. Switching back and forth between coverage
    and normal builds on the same build configuration is not recommended.

    \section2 Components of the plugin

    With the plugin enabled, C/C++ projects get
    \list
        \li A project settings menu at \uicontrol Projects > \uicontrol {Project settings}
            > \uicontrol {Coco Code Coverage} with which you can enable and configure
            code coverage.
        \li In the Build Settings, an additional pseudo build step that shows whether
            code coverage was enabled. There is also a button to directly disable or
            enable code coverage from this build step.

            \image qtcreator-coco-buildstep.png {Ficticious build step for code coverage}
    \endlist

    If code coverage is enabled, the plugin generates a \e {settings} file that is read
    by the build tool before the other configuration files and which changes the
    build process so that the Coco compiler wrappers are used instead of the original
    compiler. The settings file is always located in the root directory of the
    project sources. It also contains the coverage flags and possible overrides and
    can be checked in into version control to preserve the settings.

    \section2 The Project settings page

    \image qtcreator-coco-configpage.png {Settings page}

    The pages for QMake and CMake projects do not differ very much. They contain:
    \list
        \li A checkbox to enable and disable code coverage.
        \li A field to enter code coverage options. There are no settings that are
            needed to enable code coverage. Below the field are buttons:
            \list
                \li \uicontrol {Exclude file...} to exclude a file from instrumentation
                    more easily.
                \li \uicontrol {Exclude directory...} to exclude a directory from
                    instrumentation more easily.
                \li \uicontrol Override to open another entry field in which you can
                    enter additional commands at the end of the settings file. It is
                    meant for special cases in which the usual configuration flags are
                    not enough.
            \endlist
        \li A button \uicontrol Revert to reload the coverage settings from the current
            settings file.
        \li A button \uicontrol Save or \uicontrol {Save & Re-configure} to write
            the settings to the settings file and reconfigure the project, if
            necessary.
        \li A list with the project build settings that were changed by the plugin.
    \endlist

    \section2 QMake projects

    The settings file is \c {cocoplugin.prf}. It is a QMake "feature file".

    For a command line build, \c {qmake} must be run with the additional options
    \tt {CONFIG+=cocoplugin COCOPATH=\e{<Coco directory>}}. It is also necessary
    to set the environment variable \c {QMAKEFEATURES} to the directory in which
    \c {cocoplugin.prf} is located.

    \section2 CMake projects

    The settings file is \c {cocoplugin.cmake}. It is a CMake cache preload script.
    Apart from this file, the "compiler files" \c {cocoplugin-gcc.cmake},
    \c {cocoplugin-clang.cmake} and  \c {cocoplugin-visualstudio.cmake} are created
    in the same directory. They are needed for a command line build.

    In a command-line build, run CMake in the form
    "\tt {cmake \e{<other options>} -C\e{<project dir>}/cocoplugin-gcc.cmake}"
    (if you are compiling with GCC). The file \c {cocoplugin-gcc.cmake} includes
    then \c {cocoplugin.cmake}.

    If you use a compiler different from GCC, clang or Visual Studio, one of the
    compiler files must be modified for the new compiler.

    \section1 Check code coverage

    With the help of Coco CoverageBrowser, you can analyze the test coverage by
    loading an instrumentation database (a \c .csmes file), which was generated by
    Coco CoverageScanner.

    \section2 Configure Coco

    \list 1
        \li Go to \uicontrol Analyze > \uicontrol {Squish Coco}.
            \image qtcreator-coco.png {Coco CoverageBrowser and CSMes file}
        \li In \uicontrol CSMes, select the instrumentation database to load.
        \li Select \uicontrol Open to start CoverageBrowser.
        \li In CoverageBrowser, go to \uicontrol File >
            \uicontrol {Load Execution Report} and select the \c .csexe file for the
            coverage scan.
            \image coco-coveragebrowser-load-execution-report.png {Load Execution Report dialog}
        \li To keep the execution report, clear
            \uicontrol {Delete execution report after loading}.
    \endlist

    Open the analyzed files in \QC. You can see the results of the analysis
    after the code in \uicontrol Edit mode. You can change the fonts and colors
    used for different types of results.

    \section2 Changing Fonts and Colors

    To change the default fonts and colors, go to \preferences >
    \uicontrol {Text Editor} > \uicontrol {Font & Colors}.
    Create your own color scheme and select new fonts and colors for the
    following results:

    \list
        \li Code Coverage Added Code
        \li Partially Covered Code
        \li Uncovered Code
        \li Fully Covered Code
        \li Manually Validated Code
        \li Code Coverage Dead Code
        \li Code Coverage Execution Count too Low
        \li Implicitly Not Covered Code
        \li Implicitly Covered Code
        \li Implicit Manual Coverage Validation
    \endlist

    \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, {Analyzers},
    {Font & Colors}, {Analyzing Code}
*/
