llvm/docs/CommandGuide/llvm-reduce.rst

   1 llvm-reduce - LLVM automatic testcase reducer.
   2 ==============================================
   3
   4 .. program:: llvm-reduce
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-reduce` [*options*] [*input...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-reduce` tool project that can be used for reducing the size of LLVM test cases.
  15 It works by removing redundant or unnecessary code from LLVM test cases while still preserving
  16 their ability to detect bugs.
  17
  18 If ``input`` is "``-``", :program:`llvm-reduce` reads from standard
  19 input. Otherwise, it will read from the specified ``filenames``.
  20
  21 LLVM-Reduce is a useful tool for reducing the size and
  22 complexity of LLVM test cases, making it easier to identify and debug issues in
  23 the LLVM compiler infrastructure.
  24
  25 GENERIC OPTIONS
  26 ---------------
  27
  28
  29 .. option:: --help
  30
  31  Display available options (--help-hidden for more).
  32
  33 .. option:: --abort-on-invalid-reduction
  34
  35  Abort if any reduction results in invalid IR
  36
  37 .. option::--delta-passes=<string>
  38
  39  Delta passes to run, separated by commas. By default, run all delta passes.
  40
  41
  42 .. option:: --in-place
  43
  44  WARNING: This option will replace your input file with the reduced version!
  45
  46 .. option:: --ir-passes=<string>
  47
  48  A textual description of the pass pipeline, same as what's passed to `opt -passes`.
  49
  50 .. option:: -j <uint>
  51
  52  Maximum number of threads to use to process chunks. Set to 1 to disable parallelism.
  53
  54 .. option::  --max-pass-iterations=<int>
  55
  56   Maximum number of times to run the full set of delta passes (default=5).
  57
  58 .. option:: --mtriple=<string>
  59
  60  Set the target triple.
  61
  62 .. option:: --preserve-debug-environment
  63
  64  Don't disable features used for crash debugging (crash reports, llvm-symbolizer and core dumps)
  65
  66 .. option:: --print-delta-passes
  67
  68  Print list of delta passes, passable to --delta-passes as a comma separated liste.
  69
  70 .. option:: --skip-delta-passes=<string>
  71
  72  Delta passes to not run, separated by commas. By default, run all delta passes.
  73
  74 .. option:: --starting-granularity-level=<uint>
  75
  76   Number of times to divide chunks prior to first test.
  77
  78   Note : Granularity refers to the level of detail at which the reduction process operates.
  79   A lower granularity means that the reduction process operates at a more coarse-grained level,
  80   while a higher granularity means that it operates at a more fine-grained level.
  81
  82 .. option::  --test=<string>
  83
  84  Name of the interesting-ness test to be run.
  85
  86 .. option:: --test-arg=<string>
  87
  88  Arguments passed onto the interesting-ness test.
  89
  90 .. option:: --verbose
  91
  92  Print extra debugging information.
  93
  94 .. option::  --write-tmp-files-as-bitcode
  95
  96  Always write temporary files as bitcode instead of textual IR.
  97
  98 .. option:: -x={ir|mir}
  99
 100  Input language as ir or mir.
 101
 102 EXIT STATUS
 103 ------------
 104
 105 :program:`llvm-reduce` returns 0 under normal operation. It returns a non-zero
 106 exit code if there were any errors.
 107
 108 EXAMPLE
 109 -------
 110
 111 :program:`llvm-reduce` can be used to simplify a test that causes a
 112 compiler crash.
 113
 114 For example, let's assume that `opt` is crashing on the IR file
 115 `test.ll` with error message `Assertion failed at line 1234 of
 116 WhateverFile.cpp`, when running at `-O2`.
 117
 118 The test case of `test.ll` can be reduced by invoking the following
 119 command:
 120
 121 .. code-block:: bash
 122
 123    $(LLVM_BUILD_FOLDER)/bin/llvm-reduce --test=script.sh <path to>/test.ll
 124
 125 The shell script passed to the option `test` consists of the
 126 following:
 127
 128 .. code-block:: bash
 129
 130    $(LLVM_BUILD_FOLDER)/bin/opt -O2 -disable-output $1 \
 131      |& grep "Assertion failed at line 1234 of WhateverFile.cpp"
 132
 133 (In this script, `grep` exits with 0 if it finds the string and that
 134 becomes the whole script's status.)
 135
 136 This example can be generalized to other tools that process IR files,
 137 for example `llc`.