.. _unstableWarningAnonymizer:

.. default-domain:: chpl

----------------------------------
Unstable Warning Anonymizer Script
----------------------------------
A chapel script to anonymize, count, and report unstable warnings in Chapel code.
---------------------------------------------------------------------------------

The Unstable Warnings Anonymizer Script takes in your program's output,
and produces a detailed summary of various warnings that arise from the use of
unstable features. These warnings are generated by the Chapel compiler when the
``--warn-unstable`` flag is used.

Crucially, this script refrains from exposing any implementation details
in your code. You can still share these important metrics with us even if your
code is not public.

This analysis aids in understanding the distribution of unstable warnings,
facilitating the identification and prioritization of common unstable features
without compromising program confidentiality.

For example, given the following output from a Chapel program:

.. code-block:: sh

  ra-unordered-atomics.chpl:75: warning: 'dmapped' keyword is unstable, instead please use factory functions when available
  ra-unordered-atomics.chpl:76: warning: 'dmapped' keyword is unstable, instead please use factory functions when available
  ../HPCCProblemSize.chpl:9: warning: The 'MemDiagnostics' module is unstable

The script will generate output similar to:

.. code-block:: sh

  2 instances of "warning: 'dmapped' keyword is unstable, instead please use factory functions when available"
  1 instance of "warning: The 'MemDiagnostics' module is unstable"

The script can also generate csv output, include file counts, and more.
See the help message for more details.

Prerequisites
-------------

This tool has the following prerequisites:

- A Unix-like environment (something with commands like `cd`, `mkdir`, `rm`, etc.)
- Chapel built with Regular Expression support (see how to enable it below)

Enabling Regular Expression Support
-----------------------------------

Setting the environment variable ``CHPL_RE2`` to ``bundled`` will enable
regular expression support with the RE2 library:

.. code-block:: sh

   export CHPL_RE2=bundled

Then, rebuild Chapel. The RE2 library will be built with Chapel.

Building
--------

The script can be found under
``$CHPL_HOME/tools/unstableWarningAnonymizer/unstableAnonScript.chpl``
Compile the script with the following command:

.. code-block:: sh

  chpl unstableAnonScript.chpl

This should create an executable named `unstableAnonScript`.

Usage
-----

The usage of the script is split into two stages:

  1. Collecting output from your program's compilation and execution
  2. Using the script to anonymize this output.


Collecting the Output
~~~~~~~~~~~~~~~~~~~~~

Once the script is built, compile and run your program as you would normally,
with the addition of the compilation flag ``--warn-unstable`` and save the full
output into a file.
``--warn-unstable`` will cause any use of unstable features to trigger a
warning, which will then be saved in the output file specified above.

.. code-block:: sh

  chpl --warn-unstable myProgram.chpl &> myUnstableOutput.txt && ./myProgram &>> myUnstableOutput.txt

After these commands, `myUnstableOutput.txt` (or whatever you've named
it) should contain any unstable warnings you may trigger in your code,
as well as any other potential output that occurs when compiling and
running your program.


Running the Script
~~~~~~~~~~~~~~~~~~

Next, run the built script over your output file. For our convenience, it
would be helpful to run with the ``--csv`` and ``--sorted`` flags, or ``-c``
and ``-d`` if you want to use the shorter version of those flags.

.. code-block:: sh

  ./unstableAnonScript --csv --sorted --inputFiles myUnstableOutput.txt --outputFile mySummary.csv

or

.. code-block:: sh

  ./unstableAnonScript -c -d -i myUnstableOutput.txt -o mySummary.csv

Note that ``--inputFiles``/ ``-i`` can take multiple files, so if you have
multiple Chapel programs you'd like to share the results for, you
can combine the results together by specifying the unstable warnings from
all of those programs at the same time:

.. code-block:: sh

  ./unstableAnonScript -c -d -i myUnstableOutput1.txt myUnstableOutput2.txt myUnstableOutput3.txt -o mySummary.csv

After any of these commands, `mySummary.csv` (or whatever you've named
it) should contain a comma-separated list of the unstable warnings
generated by your program(s) and their counts, sorted from most common
to least. There should be no identifying information in this file, so
at this point, it should be safe to send the file to us.

You could also additionally run with the ``--numFiles`` flag (``-n`` for
short), which will include the number of different files where each
unstable warning was generated:


.. code-block:: sh

 ./unstableAnonScript --csv --sorted --numFiles --inputFiles myUnstableOutput.txt --outputFile mySummary.csv

or

.. code-block:: sh

  ./unstableAnonScript -c -d -n -i myUnstableOutput.txt -o mySummary.csv

This information would be helpful for our metrics, but is not essential.


For a full list of options, check the description at the top of the script
or run the script with the ``--help`` flag.

Future Work
-----------

We want this script to stay current with the unstable features in Chapel
alongside each Chapel release. If you find that the script is not working with
the latest version of Chapel, please let us know.

Contributors
------------
| Shreyas Khandekar [HPE]
|
