docs/TipsAndTricks.rst

   1 ==================================================
   2 Tips and Tricks on using and contributing to Polly
   3 ==================================================
   4
   5 Commiting to polly trunk
   6 ------------------------
   7     - `General reference to git-svn workflow <https://stackoverflow.com/questions/190431/is-git-svn-dcommit-after-merging-in-git-dangerous>`_
   8
   9
  10 Using bugpoint to track down errors in large files
  11 --------------------------------------------------
  12
  13     If you know the ``opt`` invocation and have a large ``.ll`` file that causes
  14     an error, ``bugpoint`` allows one to reduce the size of test cases.
  15
  16     The general calling pattern is:
  17
  18     - ``$ bugpoint <file.ll> <pass that causes the crash> -opt-args <opt option flags>``
  19
  20     An example invocation is:
  21
  22     - ``$ bugpoint crash.ll -polly-codegen -opt-args  -polly-canonicalize -polly-process-unprofitable``
  23
  24     For more documentation on bugpoint, `Visit the LLVM manual <http://llvm.org/docs/Bugpoint.html>`_
  25
  26
  27 Understanding which pass makes a particular change
  28 --------------------------------------------------
  29
  30     If you know that something like `opt -O3 -polly` makes a change, but you wish to
  31     isolate which pass makes a change, the steps are as follows:
  32
  33     - ``$ bugpoint -O3 file.ll -opt-args -polly``  will allow bugpoint to track down the pass which causes the crash.
  34
  35     To do this manually:
  36
  37     - ``$ opt -O3 -polly -debug-pass=Arguments`` to get all passes that are run by default. ``-debug-pass=Arguments`` will list all passes that have run.
  38     - Bisect down to the pass that changes it.
  39
  40
  41 Debugging regressions introduced at some unknown earlier point
  42 --------------------------------------------------------------
  43
  44 In case of a regression in performance or correctness (e.g., an earlier version
  45 of Polly behaved as expected and a later version does not), bisecting over the
  46 version history is the standard approach to identify the commit that introduced
  47 the regression.
  48
  49 LLVM has a single repository that contains all projects. It can be cloned at:
  50 `<https://github.com/llvm-project/llvm-project-20170507>`_. How to bisect on a
  51 git repository is explained here
  52 `<https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination`_.
  53 The bisect process can also be automated as explained here:
  54 `<https://www.metaltoad.com/blog/mechanizing-git-bisect-bug-hunting-lazy>`_.
  55 An LLVM specific run script is available here:
  56 `<https://gist.github.com/dcci/891cd98d80b1b95352a407d80914f7cf>`_.