.. _starterkit_validation:

StarterKit Validation Workflow
******************************

Overview
========

The StarterKit validation workflow lets you evaluate RTA-SQF against an
RTA-CAR StarterKit installed on your machine, producing a Sarif result that
you can inspect with any Sarif viewer.

The workflow automates the steps needed to run the |os_command_name| command
on a StarterKit:

1. it discovers the RTA-CAR versions installed on the local Windows machine;
2. it lets you select the version to validate;
3. it generates a ``compile_commands.json`` for the selected StarterKit
   (see the compilation database description in
   :doc:`compile_command_and_compilers`);
4. it runs the |os_command_name| command against that StarterKit;
5. it collects the Sarif result in a dedicated output folder.

The result serves two purposes: it lets you **evaluate the RTA-SQF product**
on a real project, and it gives you a **safety-qualification result for the
StarterKit code** that you can review with a Sarif viewer.

.. note:: Platform

    The validation script relies on the Windows registry to discover installed
    RTA-CAR versions, so it runs on Windows only.

Prerequisites
=============

Before running the workflow, make sure the following tools are available:

.. list-table:: Required tools
    :widths: 30 70
    :header-rows: 1

    * - Tool
      - Purpose
    * - Python 3.7+
      - Runs the validation script.
    * - CMake 3.20+
      - Runs the configure step that produces ``compile_commands.json``.
    * - MinGW Make
      - Build-system generator used by CMake to export ``compile_commands.json``.
    * - RTA-SQF
      - The ``rta-sqf`` executable used to run the |os_command_name| command.
    * - RTA-CAR StarterKit
      - An installed RTA-CAR version providing the StarterKit to validate.

Running the Workflow
====================

The simplest way to validate a StarterKit is to run the orchestration script
without arguments. It guides you through the selection interactively:

.. code:: bash

    python validate_starterkit.py

The script lists the installed RTA-CAR versions and asks you to choose one:

.. code:: text

    Found 2 RTA-CAR installations:
      [1] RTA-CAR 12.9.0
          Path: C:\ETAS\RTA-CAR_12.9.0\
      [2] RTA-CAR 12.12.0pr2
          Path: C:\ETAS\RTA-CAR_12.12.0pr2\

    Select installation [1-2, or 0 to cancel]:

After you select a version, the script generates the compilation database,
locates the ``rta-sqf`` executable, and runs the |os_command_name| command.

Choosing the output folder
--------------------------

By default the results are written to a ``rta_sqf_validation`` folder created
in the current working directory. Use the ``--outdir`` option to choose a
different location:

.. code:: bash

    python validate_starterkit.py --outdir="C:\Validation"

Selecting the RTA-SQF executable
--------------------------------

The script auto-detects the ``rta-sqf`` executable. If auto-detection fails,
or to validate with a specific build, pass its path explicitly:

.. code:: bash

    python validate_starterkit.py --rtasqf-exe="C:\Tools\rta-sqf.exe"

Output Structure
================

All artifacts are isolated under the output folder (``--outdir``):

.. code:: text

    <outdir>/
    |-- compile_commands/
    |   \-- compile_commands.json     # generated compilation database
    \-- rta_sqf_result/
        |-- rta-sqf-result.sarif      # Sarif validation result
        \-- rta-sqf.log               # internal log file

The generated ``compile_commands.json`` is the input passed to the
|os_command_name| command through the ``--os-compile-db`` option; the
``rta_sqf_result`` folder is passed as the ``--out-dir`` value. For the meaning
of these options see :doc:`command_os`, and for the structure of the
compilation database see :doc:`compile_command_and_compilers`.

Reviewing the Result
====================

Open the ``rta-sqf-result.sarif`` file with a Sarif viewer (for example the
Visual Studio Code Sarif Viewer extension) to inspect the results for each AoU.
The interpretation of the ``Kind`` and ``Level`` properties, and the iterative
review process, are described in :ref:`Working with RTA-SQF <Chapter-Working-With-RTA-SQF>`.

.. note:: StarterKit is not modified

    The workflow runs only the CMake *configure* step and redirects the CMake
    binary directory outside the StarterKit. No file inside the StarterKit
    installation is created or modified.

Equivalent Manual Invocation
============================

The orchestration script is a convenience wrapper. If you already have a
``compile_commands.json`` for your project, you can run the |os_command_name|
command directly, as described in :doc:`command_os`:

.. code:: bash

    rta-sqf os --os-compile-db="C:\path\to\compile_commands.json" --out-dir=".\rta_sqf_result"