[llvm] [llvm][docs] Add example use of `llvm-reduce`. (PR #73237)

[Francesco Petrogalli via llvm-commits]

https://github.com/fpetrogalli updated https://github.com/llvm/llvm-project/pull/73237

>From 46bcaa3d59067368e41bbb2debaadea0b4e29ffd Mon Sep 17 00:00:00 2001
From: Francesco Petrogalli <francesco.petrogalli at apple.com>
Date: Thu, 23 Nov 2023 13:41:53 +0100
Subject: [PATCH 1/2] [llvm][docs] Add example use of `llvm-reduce`.

The script is based on an example provided by Tim
Northover (https://github.com/TNorthover).
---
 llvm/docs/CommandGuide/llvm-reduce.rst | 29 ++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/llvm/docs/CommandGuide/llvm-reduce.rst b/llvm/docs/CommandGuide/llvm-reduce.rst
index cd49ceba2d6b6e8..b03784696d55786 100644
--- a/llvm/docs/CommandGuide/llvm-reduce.rst
+++ b/llvm/docs/CommandGuide/llvm-reduce.rst
@@ -105,4 +105,33 @@ EXIT STATUS
 :program:`llvm-reduce` returns 0 under normal operation. It returns a non-zero
 exit code if there were any errors.
 
+EXAMPLE
+-------
 
+`llvm-reduce` can be used to simplify a test that causes a compiler
+crash.
+
+For example, let's assume that `opt` is crashing on the IR file
+`test.ll` with error message `Assertion failed at line 1234 of
+WhateverFile.cpp`, when running at `-O2`.
+
+The test case of `test.ll` can be reduced by invoking the following
+command:
+
+.. code-block:: bash
+
+   $(LLVM_BUILD_FOLDER)/bin/llvm-reduce --test=script.sh <path to>/test.ll
+
+The shell script passed to the option `test` consists of the
+following:
+
+.. code-block:: bash
+
+   $(LLVM_BUILD_FOLDER)/bin/opt -O2 -S $1 -o /dev/null \
+     |& grep "Assertion failed at line 1234 of WhateverFile.cpp"
+
+(In this script, `grep` exits with 0 if it finds the string and that
+becomes the whole script's status.)
+
+This example can be generalized to other tools that process IR files,
+for example `llc`.

>From b2596fab41e86d63191c95b2bec7fbabff0e59ca Mon Sep 17 00:00:00 2001
From: Francesco Petrogalli <francesco.petrogalli at apple.com>
Date: Thu, 23 Nov 2023 14:37:20 +0100
Subject: [PATCH 2/2] Wrap `llvm-reduce` into `:program:`.

---
 llvm/docs/CommandGuide/llvm-reduce.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/CommandGuide/llvm-reduce.rst b/llvm/docs/CommandGuide/llvm-reduce.rst
index b03784696d55786..e23f7c73fb976b4 100644
--- a/llvm/docs/CommandGuide/llvm-reduce.rst
+++ b/llvm/docs/CommandGuide/llvm-reduce.rst
@@ -108,8 +108,8 @@ exit code if there were any errors.
 EXAMPLE
 -------
 
-`llvm-reduce` can be used to simplify a test that causes a compiler
-crash.
+:program:`llvm-reduce` can be used to simplify a test that causes a
+compiler crash.
 
 For example, let's assume that `opt` is crashing on the IR file
 `test.ll` with error message `Assertion failed at line 1234 of