[docs] Replace `opt -analyze` with better alternatives.

[aeubanks]

Summary

opt -analyze is legacy PM-specific. Show better ways of doing the same
thing, generally with some sort of -passes=print<foo>.

[asbirlea]

lgtm.

llvm/utils/update_analyze_test_checks.py

17

nit: unnecessary -S with -disable-output?
Perhaps update to:
; RUN: opt < %s -passes='print<cost-model>' -disable-output 2>&1 | FileCheck %s"

llvm/docs/CommandGuide/opt.rst

 opt - LLVM optimizer
 ====================
 
 .. program:: opt
 
 SYNOPSIS
 --------
 
 :program:`opt` [*options*] [*filename*]
 
 DESCRIPTION
 -----------
 
-The :program:`opt` command is the modular LLVM optimizer and analyzer.  It
-takes LLVM source files as input, runs the specified optimizations or analyses
-on it, and then outputs the optimized file or the analysis results.  The
-function of :program:`opt` depends on whether the `-analyze` option is
-given.
-
-When `-analyze` is specified, :program:`opt` performs various analyses
-of the input source.  It will usually print the results on standard output, but
-in a few cases, it will print output to standard error or generate a file with
-the analysis output, which is usually done when the output is meant for another
-program.
-
-While `-analyze` is *not* given, :program:`opt` attempts to produce an
-optimized output file.  The optimizations available via :program:`opt` depend
-upon what libraries were linked into it as well as any additional libraries
-that have been loaded with the :option:`-load` option.  Use the :option:`-help`
-option to determine what optimizations you can use.
+The :program:`opt` command is the modular LLVM optimizer and analyzer.  It takes
+LLVM source files as input, runs the specified optimizations or analyses on it,
+and then outputs the optimized file. The optimizations available via
+:program:`opt` depend upon what libraries were linked into it as well as any
+additional libraries that have been loaded with the :option:`-load` option.  Use
+the :option:`-help` option to determine what optimizations you can use.
 
 If ``filename`` is omitted from the command line or is "``-``", :program:`opt`
 reads its input from standard input.  Inputs can be in either the LLVM assembly
 language format (``.ll``) or the LLVM bitcode format (``.bc``).
 
 If an output filename is not specified with the :option:`-o` option,
 :program:`opt` writes its output to the standard output.
 

llvm/docs/LoopTerminology.rst

 
 Loops are an important concept for a code optimizer. In LLVM, detection
 of loops in a control-flow graph is done by :ref:`loopinfo`. It is based
 on the following definition.
 
 A loop is a subset of nodes from the control-flow graph (CFG; where
 nodes represent basic blocks) with the following properties:
 
-1. The induced subgraph (which is the subgraph that contains all the
+1. The induced subgraph (which is the subgraph that contains all the
    edges from the CFG within the loop) is strongly connected
    (every node is reachable from all others).
 
-2. All edges from outside the subset into the subset point to the same
+2. All edges from outside the subset into the subset point to the same
    node, called the **header**. As a consequence, the header dominates
    all nodes in the loop (i.e. every execution path to any of the loop's
    node will have to pass through the header).
 
-3. The loop is the maximum subset with these properties. That is, no
+3. The loop is the maximum subset with these properties. That is, no
    additional nodes from the CFG can be added such that the induced
    subgraph would still be strongly connected and the header would
    remain the same.
 
 In computer science literature, this is often called a *natural loop*.
 In LLVM, this is the only definition of a loop.
 
 
 Terminology
 -----------
 
 The definition of a loop comes with some additional terminology:
 
-* An **entering block** (or **loop predecessor**) is a non-loop node
+* An **entering block** (or **loop predecessor**) is a non-loop node
   that has an edge into the loop (necessarily the header). If there is
   only one entering block entering block, and its only edge is to the
   header, it is also called the loop's **preheader**. The preheader
   dominates the loop without itself being part of the loop.
 
 * A **latch** is a loop node that has an edge to the header.
 
 * A **backedge** is an edge from a latch to the header.
 
-* An **exiting edge** is an edge from inside the loop to a node outside
+* An **exiting edge** is an edge from inside the loop to a node outside
   of the loop. The source of such an edge is called an **exiting block**, its
   target is an **exit block**.
 
 .. image:: ./loop-terminology.svg
    :width: 400 px
 
 
 Important Notes
 ---------------
 
 This loop definition has some noteworthy consequences:
 
-* A node can be the header of at most one loop. As such, a loop can be
+* A node can be the header of at most one loop. As such, a loop can be
   identified by its header. Due to the header being the only entry into
   a loop, it can be called a Single-Entry-Multiple-Exits (SEME) region.
 
 
-* For basic blocks that are not reachable from the function's entry, the
+* For basic blocks that are not reachable from the function's entry, the
   concept of loops is undefined. This follows from the concept of
   dominance being undefined as well.
 
 
-* The smallest loop consists of a single basic block that branches to
+* The smallest loop consists of a single basic block that branches to
   itself. In this case that block is the header, latch (and exiting
   block if it has another edge to a different block) at the same time.
   A single block that has no branch to itself is not considered a loop,
   even though it is trivially strongly connected.
 
 .. image:: ./loop-single.svg
    :width: 300 px
 
 In this case, the role of header, exiting block and latch fall to the
 same node. :ref:`loopinfo` reports this as:
 
 .. code-block:: console
 
-  $ opt input.ll -loops -analyze
+  $ opt input.ll -passes='print<loops>'
   Loop at depth 1 containing: %for.body<header><latch><exiting>
 
 
-* Loops can be nested inside each other. That is, a loop's node set can
+* Loops can be nested inside each other. That is, a loop's node set can
   be a subset of another loop with a different loop header. The loop
   hierarchy in a function forms a forest: Each top-level loop is the
   root of the tree of the loops nested inside it.
 
 .. image:: ./loop-nested.svg
    :width: 350 px
 
 
-* It is not possible that two loops share only a few of their nodes.
+* It is not possible that two loops share only a few of their nodes.
   Two loops are either disjoint or one is nested inside the other. In
   the example below the left and right subsets both violate the
   maximality condition. Only the merge of both sets is considered a loop.
 
 .. image:: ./loop-nonmaximal.svg
    :width: 250 px
 
 
-* It is also possible that two logical loops share a header, but are
+* It is also possible that two logical loops share a header, but are
   considered a single loop by LLVM:
 
 .. code-block:: C
 
   for (int i = 0; i < 128; ++i)
     for (int j = 0; j < 128; ++j)
       body(i,j);
 
 which might be represented in LLVM-IR as follows. Note that there is
 only a single header and hence just a single loop.
 
 .. image:: ./loop-merge.svg
    :width: 400 px
 
 The :ref:`LoopSimplify <loop-terminology-loop-simplify>` pass will
 detect the loop and ensure separate headers for the outer and inner loop.
 
 .. image:: ./loop-separate.svg
    :width: 400 px
 
-* A cycle in the CFG does not imply there is a loop. The example below
+* A cycle in the CFG does not imply there is a loop. The example below
   shows such a CFG, where there is no header node that dominates all
   other nodes in the cycle. This is called **irreducible control-flow**.
 
 .. image:: ./loop-irreducible.svg
    :width: 150 px
 
 The term reducible results from the ability to collapse the CFG into a
 single node by successively replacing one of three base structures with
 a single node: A sequential execution of basic blocks, a conditional
 branching (or switch) with re-joining, and a basic block looping on itself.
 `Wikipedia <https://en.wikipedia.org/wiki/Control-flow_graph#Reducibility>`_
 has a more formal definition, which basically says that every cycle has
 a dominating header.
 
 
-* Irreducible control-flow can occur at any level of the loop nesting.
+* Irreducible control-flow can occur at any level of the loop nesting.
   That is, a loop that itself does not contain any loops can still have
   cyclic control flow in its body; a loop that is not nested inside
   another loop can still be part of an outer cycle; and there can be
   additional cycles between any two loops where one is contained in the other.
 
 
-* Exiting edges are not the only way to break out of a loop. Other
+* Exiting edges are not the only way to break out of a loop. Other
   possibilities are unreachable terminators, [[noreturn]] functions,
   exceptions, signals, and your computer's power button.
 
 
-* A basic block "inside" the loop that does not have a path back to the
+* A basic block "inside" the loop that does not have a path back to the
   loop (i.e. to a latch or header) is not considered part of the loop.
   This is illustrated by the following code.
 
 .. code-block:: C
 
   for (unsigned i = 0; i <= n; ++i) {
     if (c1) {
       // When reaching this block, we will have exited the loop.
if (c4) {
       // This statically infinite loop is not nested because control-flow will not continue with the for-loop.
       while(true) {
         do_something();
       }
     }
   }
 
 
-* There is no requirement for the control flow to eventually leave the
+* There is no requirement for the control flow to eventually leave the
   loop, i.e. a loop can be infinite. A **statically infinite loop** is a
   loop that has no exiting edges. A **dynamically infinite loop** has
   exiting edges, but it is possible to be never taken. This may happen
   only under some circumstances, such as when n == UINT_MAX in the code
   below.
 
 .. code-block:: C
 

 eventually terminate without proving it. For instance, it may remove a loop
 that does not do anything in its body. If the loop was infinite, this
 optimization resulted in an "infinite" performance speed-up. A call
 to the intrinsic :ref:`llvm.sideeffect<llvm_sideeffect>` can be added
 into the loop to ensure that the optimizer does not make this assumption
 without proof.
 
 
-* The number of executions of the loop header before leaving the loop is
+* The number of executions of the loop header before leaving the loop is
   the **loop trip count** (or **iteration count**). If the loop should
   not be executed at all, a **loop guard** must skip the entire loop:
 
 .. image:: ./loop-guard.svg
    :width: 500 px
 
 Since the first thing a loop header might do is to check whether there
 is another execution and if not, immediately exit without doing any work

llvm/docs/TestingGuide.rst

 which first check the ``NOTE:`` line exists and matches the script name.
 
 These are the most common scripts and their purposes/applications in generating
 assertions:
 
 .. code-block:: none
 
   update_analyze_test_checks.py
-  opt --analyze --costmodel
+  opt -passes='print<cost-model>'
 
   update_cc_test_checks.py
   C/C++, or clang/clang++ (IR checks)
 
   update_llc_test_checks.py
   llc (assembly checks)
 
   update_mca_test_checks.py

llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl05.rst

.. code-block:: llvm
 
     ifcont:     ; preds = %else, %then
       %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
       ret double %iftmp
     }
 
 To visualize the control flow graph, you can use a nifty feature of the
 LLVM '`opt <https://llvm.org/cmds/opt.html>`_' tool. If you put this LLVM
-IR into "t.ll" and run "``llvm-as < t.ll | opt -analyze -view-cfg``", `a
+IR into "t.ll" and run "``llvm-as < t.ll | opt -passes=view-cfg``", `a
 window will pop up <../../ProgrammersManual.html#viewing-graphs-while-debugging-code>`_ and you'll
 see this graph:
 
 .. figure:: LangImpl05-cfg.png
    :align: center
    :alt: Example CFG
 
    Example CFG

llvm/include/llvm/Analysis/RegionInfo.h

 ///    6   7  8
 ///     \  | /
 ///      \ |/       Region A: 1 -> 9 {1,2,3,4,5,6,7,8}
 ///        9        Region B: 2 -> 9 {2,4,5,6,7}
 /// \endverbatim
 ///
 /// You can obtain more examples by either calling
 ///
-/// <tt> "opt -regions -analyze anyprogram.ll" </tt>
+/// <tt> "opt -passes='print<regions>' anyprogram.ll" </tt>
 /// or
 /// <tt> "opt -view-regions-only anyprogram.ll" </tt>
 ///
 /// on any LLVM file you are interested in.
 ///
 /// The first call returns a textual representation of the program structure
 /// tree, the second one creates a graphical representation using graphviz.
 template <class Tr>

llvm/utils/update_analyze_test_checks.py

 #!/usr/bin/env python3
 
 """A script to generate FileCheck statements for 'opt' analysis tests.
 
 This script is a utility to update LLVM opt analysis test cases with new
 FileCheck patterns. It can either update all of the tests in the file or
 a single test function.
 
 Example usage:
 $ update_analyze_test_checks.py --opt=../bin/opt test/foo.ll
 
 Workflow:
 1. Make a compiler patch that requires updating some number of FileCheck lines
    in regression test files.
 2. Save the patch and revert it from your local work area.
 3. Update the RUN-lines in the affected regression tests to look canonical.
-   Example: "; RUN: opt < %s -analyze -cost-model -S | FileCheck %s"
+   Example: "; RUN: opt < %s -passes='print<cost-model>' -disable-output 2>&1 | FileCheck %s"
 4. Refresh the FileCheck lines for either the entire file or select functions by
    running this script.
 5. Commit the fresh baseline of checks.
 6. Apply your patch from step 1 and rebuild your local binaries.
 7. Re-run this script on affected regression tests.
 8. Check the diffs to ensure the script has done something reasonable.
 9. Submit a patch including the regression test diffs for review.