.. Copyright 2023 Lawrence Livermore National Security, LLC and other
   Benchpark Project Developers. See the top-level COPYRIGHT file for details.

   SPDX-License-Identifier: Apache-2.0

====================
Compare System Specs
====================
``lib/scripts/diffSystemSpecs.py``

Compare two system specs `.yaml` files generated by ``benchpark system init``.
This script enables the user to compare changes to a ``system.py`` between commits
by comparing ``.yaml`` files generated from ``benchpark system init ...``.
This script is helpful when it is unclear if changes made to ``system.py`` will affect the resulting system configuration.

Stages that occur during this script:
   - ``benchpark system init``

Example: Identical System
~~~~~~~~~~~~~~~~~~~~~~~~~

In this example, we compare the ``llnl-sierra/system.py`` on the ``develop`` branch against the ``develop`` branch.
As we expect, the generated system configuration files are identical, since no changes were made to the system.py

.. code-block:: console

   $ benchpark-python diffSystemSpecs.py -n develop -s llnl-sierra

   llnl-sierra
        llnl-sierra/system_id.yaml
                The YAML files benchpark-old/llnl-sierra/system_id.yaml and benchpark-new/llnl-sierra/system_id.yaml are identical.
        llnl-sierra/software.yaml
                The YAML files benchpark-old/llnl-sierra/software.yaml and benchpark-new/llnl-sierra/software.yaml are identical.
        llnl-sierra/variables.yaml
                The YAML files benchpark-old/llnl-sierra/variables.yaml and benchpark-new/llnl-sierra/variables.yaml are identical.
        llnl-sierra/auxiliary_software_files/packages.yaml
                The YAML files benchpark-old/llnl-sierra/auxiliary_software_files/packages.yaml and benchpark-new/llnl-sierra/auxiliary_software_files/packages.yaml are identical.
        llnl-sierra/auxiliary_software_files/compilers.yaml
                The YAML files benchpark-old/llnl-sierra/auxiliary_software_files/compilers.yaml and benchpark-new/llnl-sierra/auxiliary_software_files/compilers.yaml are identical.

Example: Different CMake Version 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In another example, we have modified the ``cmake`` package version from ``3.29.2`` to ``3.23.1``. 

.. code-block:: python
   
   # llnl-sierra/system.py
   "cmake": {
      "externals": [
         {
               "spec": "cmake@3.23.1",
               "prefix": "/usr/tce/packages/cmake/cmake-3.23.1",
         }
      ],
      "buildable": False,
   },

The script will appropriately identify the change to the package version:

.. code-block:: console

   $ benchpark-python diffSystemSpecs.py -n changeCMakeBranch -s llnl-sierra

   llnl-sierra
        llnl-sierra/system_id.yaml
                The YAML files benchpark-old/llnl-sierra/system_id.yaml and benchpark-new/llnl-sierra/system_id.yaml are identical.
        llnl-sierra/software.yaml
                The YAML files benchpark-old/llnl-sierra/software.yaml and benchpark-new/llnl-sierra/software.yaml are identical.
        llnl-sierra/variables.yaml
                The YAML files benchpark-old/llnl-sierra/variables.yaml and benchpark-new/llnl-sierra/variables.yaml are identical.
        llnl-sierra/auxiliary_software_files/packages.yaml
                The YAML files benchpark-old/llnl-sierra/auxiliary_software_files/packages.yaml and benchpark-new/llnl-sierra/auxiliary_software_files/packages.yaml are different. Here are the differences:
                  {'values_changed': {"root['packages']['cmake']['externals'][0]['prefix']": {'new_value': '/usr/tce/packages/cmake/cmake-3.23.1',
                                                                                             'old_value': '/usr/tce/packages/cmake/cmake-3.29.2'},
                                    "root['packages']['cmake']['externals'][0]['spec']": {'new_value': 'cmake@3.23.1',
                                                                                          'old_value': 'cmake@3.29.2'}}}
        llnl-sierra/auxiliary_software_files/compilers.yaml
                The YAML files benchpark-old/llnl-sierra/auxiliary_software_files/compilers.yaml and benchpark-new/llnl-sierra/auxiliary_software_files/compilers.yaml are identical.

.. note::
   This script *does not* need to be ran on the target system to work correctly, e.g. the above example for ``llnl-sierra`` can be ran from your local machine.