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
17By default Polly is configured as a shared library plugin that is loaded in
18tools like clang, opt, and bugpoint when they start their execution. By loading
19Polly into clang (or opt) the Polly options become automatically available. You
20can load Polly either by adding the relevant commands to the CPPFLAGS or by
21creating an alias.
22
23.. code-block:: console
24
25  $ export CPPFLAGS="-Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so"
26
27or
28
29.. code-block:: console
30
31  $ alias pollycc clang -Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so
32
33To avoid having to load Polly in the tools, Polly can optionally be configured
34with cmake to be statically linked in the tools:
35
36.. code-block:: console
37
38  $ cmake -D LINK_POLLY_INTO_TOOLS:Bool=ON
39
40Optimizing with Polly
41=====================
42
43Optimizing with Polly is as easy as adding -O3 -mllvm -polly to your compiler
44flags (Polly is only available at -O3).
45
46.. code-block:: console
47
48  pollycc -O3 -mllvm -polly file.c
49
50Automatic OpenMP code generation
51================================
52
53To automatically detect parallel loops and generate OpenMP code for them you
54also need to add -mllvm -polly-parallel -lgomp to your CFLAGS.
55
56.. code-block:: console
57
58  pollycc -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c
59
60Automatic Vector code generation
61================================
62
63Automatic vector code generation can be enabled by adding -mllvm
64-polly-vectorizer=stripmine to your CFLAGS.
65
66.. code-block:: console
67
68  pollycc -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c
69
70Extract a preoptimized LLVM-IR file
71===================================
72
73Often it is useful to derive from a C-file the LLVM-IR code that is actually
74optimized by Polly. Normally the LLVM-IR is automatically generated from the C
75code by first lowering C to LLVM-IR (clang) and by subsequently applying a set
76of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
77preparing transformations have been applied run Polly with '-O0'.
78
79.. code-block:: console
80
81  pollycc -O0 -mllvm -polly -S -emit-llvm file.c
82
83Further options
84===============
85Polly supports further options that are mainly useful for the development or the
86analysis of Polly. The relevant options can be added to clang by appending
87-mllvm -option-name to the CFLAGS or the clang command line.
88
89Limit Polly to a single function
90--------------------------------
91
92To limit the execution of Polly to a single function, use the option
93-polly-only-func=functionname.
94
95Disable LLVM-IR generation
96--------------------------
97
98Polly normally regenerates LLVM-IR from the Polyhedral representation. To only
99see the effects of the preparing transformation, but to disable Polly code
100generation add the option polly-no-codegen.
101
102Graphical view of the SCoPs
103---------------------------
104Polly can use graphviz to show the SCoPs it detects in a program. The relevant
105options are -polly-show, -polly-show-only, -polly-dot and -polly-dot-only. The
106'show' options automatically run dotty or another graphviz viewer to show the
107scops graphically. The 'dot' options store for each function a dot file that
108highlights the detected SCoPs. If 'only' is appended at the end of the option,
109the basic blocks are shown without the statements the contain.
110
111Change/Disable the Optimizer
112----------------------------
113
114Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes
115for data-locality and parallelism using the Pluto algorithm. For research it is
116also possible to run PoCC as external optimizer. PoCC provides access to the
117original Pluto implementation. To use PoCC add -polly-optimizer=pocc to the
118command line (only available if Polly was compiled with scoplib support)
119[removed after LLVM 3.4.2]. To disable the optimizer entirely use the option
120-polly-optimizer=none.
121
122Disable tiling in the optimizer
123-------------------------------
124
125By default both optimizers perform tiling, if possible. In case this is not
126wanted the option -polly-tiling=false can be used to disable it. (This option
127disables tiling for both optimizers).
128
129Ignore possible aliasing
130------------------------
131
132By default we only detect scops, if we can prove that the different array
133bases can not alias. This is correct do if we optimize automatically. However,
134without special user annotations like 'restrict' we can often not prove that
135no aliasing is possible. In case the user knows no aliasing can happen in the
136code the -polly-ignore-aliasing can be used to disable the check for possible
137aliasing.
138
139Import / Export
140---------------
141
142The flags -polly-import and -polly-export allow the export and reimport of the
143polyhedral representation. By exporting, modifying and reimporting the
144polyhedral representation externally calculated transformations can be
145applied. This enables external optimizers or the manual optimization of
146specific SCoPs.
147