1======================
2Using Polly with Clang
3======================
4
5This documentation discusses how Polly can be used in Clang to automatically
6optimize C/C++ code during compilation.
7
8
9.. warning::
10
11  Warning: clang/LLVM/Polly need to be in sync (compiled from the same SVN
12  revision).
13
14Make Polly available from Clang
15===============================
16
17Polly is available through clang, opt, and bugpoint, if Polly was checked out
18into tools/polly before compilation. No further configuration is needed.
19
20Optimizing with Polly
21=====================
22
23Optimizing with Polly is as easy as adding -O3 -mllvm -polly to your compiler
24flags (Polly is only available at -O3).
25
26.. code-block:: console
27
28  clang -O3 -mllvm -polly file.c
29
30Automatic OpenMP code generation
31================================
32
33To automatically detect parallel loops and generate OpenMP code for them you
34also need to add -mllvm -polly-parallel -lgomp to your CFLAGS.
35
36.. code-block:: console
37
38  clang -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c
39
40Automatic Vector code generation
41================================
42
43Automatic vector code generation can be enabled by adding -mllvm
44-polly-vectorizer=stripmine to your CFLAGS.
45
46.. code-block:: console
47
48  clang -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c
49
50Extract a preoptimized LLVM-IR file
51===================================
52
53Often it is useful to derive from a C-file the LLVM-IR code that is actually
54optimized by Polly. Normally the LLVM-IR is automatically generated from the C
55code by first lowering C to LLVM-IR (clang) and by subsequently applying a set
56of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
57preparing transformations have been applied run Polly with '-O0'.
58
59.. code-block:: console
60
61  clang -O0 -mllvm -polly -S -emit-llvm file.c
62
63Further options
64===============
65Polly supports further options that are mainly useful for the development or the
66analysis of Polly. The relevant options can be added to clang by appending
67-mllvm -option-name to the CFLAGS or the clang command line.
68
69Limit Polly to a single function
70--------------------------------
71
72To limit the execution of Polly to a single function, use the option
73-polly-only-func=functionname.
74
75Disable LLVM-IR generation
76--------------------------
77
78Polly normally regenerates LLVM-IR from the Polyhedral representation. To only
79see the effects of the preparing transformation, but to disable Polly code
80generation add the option polly-no-codegen.
81
82Graphical view of the SCoPs
83---------------------------
84Polly can use graphviz to show the SCoPs it detects in a program. The relevant
85options are -polly-show, -polly-show-only, -polly-dot and -polly-dot-only. The
86'show' options automatically run dotty or another graphviz viewer to show the
87scops graphically. The 'dot' options store for each function a dot file that
88highlights the detected SCoPs. If 'only' is appended at the end of the option,
89the basic blocks are shown without the statements the contain.
90
91Change/Disable the Optimizer
92----------------------------
93
94Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes
95for data-locality and parallelism using the Pluto algorithm.
96To disable the optimizer entirely use the option -polly-optimizer=none.
97
98Disable tiling in the optimizer
99-------------------------------
100
101By default both optimizers perform tiling, if possible. In case this is not
102wanted the option -polly-tiling=false can be used to disable it. (This option
103disables tiling for both optimizers).
104
105Import / Export
106---------------
107
108The flags -polly-import and -polly-export allow the export and reimport of the
109polyhedral representation. By exporting, modifying and reimporting the
110polyhedral representation externally calculated transformations can be
111applied. This enables external optimizers or the manual optimization of
112specific SCoPs.
113