1==================================================
2Tips and Tricks on using and contributing to Polly
3==================================================
4
5Commiting 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
10Using 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 <https://llvm.org/docs/Bugpoint.html>`_
25
26
27Understanding 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
41Debugging regressions introduced at some unknown earlier point
42--------------------------------------------------------------
43
44In case of a regression in performance or correctness (e.g., an earlier version
45of Polly behaved as expected and a later version does not), bisecting over the
46version history is the standard approach to identify the commit that introduced
47the regression.
48
49LLVM has a single repository that contains all projects. It can be cloned at:
50`<https://github.com/llvm/llvm-project>`_. How to bisect on a
51git repository is explained here
52`<https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination>`_.
53The bisect process can also be automated as explained here:
54`<https://www.metaltoad.com/blog/mechanizing-git-bisect-bug-hunting-lazy>`_.
55An LLVM specific run script is available here:
56`<https://gist.github.com/dcci/891cd98d80b1b95352a407d80914f7cf>`_.
57