<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
          "http://www.w3.org/TR/html4/strict.dtd">
<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
<html>
<head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Polly - Load Polly into clang</title>
  <link type="text/css" rel="stylesheet" href="menu.css">
  <link type="text/css" rel="stylesheet" href="content.css">
</head>
<body>
<div id="box">
<!--#include virtual="menu.html.incl"-->
<div id="content">
<!--=====================================================================-->
<h1>Load Polly into clang and automatically run it at -O3</h1>
<!--=====================================================================-->

<p><b>Warning:</b> Even though this example makes it very easy to use Polly,
you should be aware that Polly is a young research project. It is expected
to crash, produce invalid code or to hang in complex calculations even for
simple examples. In case you see such a problem, please check the <a
href="bugs.html">Bug database</a> and consider reporting a bug.
<p>
<b>Warning II:</b> clang/LLVM/Polly need to be in sync. This means
            you need to compile them yourself from a recent svn/git checkout</b>
<h2>Load Polly into clang</h2>

By default Polly is configured as a shared library plugin that is loaded in
tools like clang, opt, and bugpoint when they start their execution.

By loading Polly into clang (or opt) the Polly options become automatically
available. You can load Polly either by adding the relevant commands to
the CPPFLAGS or by creating an alias.

<pre class="code">
$ export CPPFLAGS="-Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so"
</pre>

or
<pre class="code">
$ alias pollycc clang -Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so
</pre>

To avoid having to load Polly in the tools, Polly can optionally be configured
with cmake to be statically linked in the tools:

<pre class="code">
$ cmake -D LINK_POLLY_INTO_TOOLS:Bool=ON
</pre>

<h2>Optimizing with Polly</h2>

Optimizing with Polly is as easy as adding <b>-O3 -mllvm -polly</b> to your
compiler flags (Polly is only available at -O3).

<pre class="code">pollycc -O3 -mllvm -polly file.c</pre>

<h2>Automatic OpenMP code generation</h2>

To automatically detect parallel loops and generate OpenMP code for them you
also need to add <b>-mllvm -polly-parallel -lgomp</b> to your CFLAGS.

<pre class="code">pollycc -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c</pre>

<h2>Automatic Vector code generation</h2>

Automatic vector code generation can be enabled by adding <b>-mllvm
-polly-vectorizer=stripmine</b> to your CFLAGS.

<pre class="code">pollycc -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c</pre>

<h2>Extract a preoptimized LLVM-IR file</h2>

Often it is useful to derive from a C-file the LLVM-IR code that is actually
optimized by Polly. Normally the LLVM-IR is automatically generated from
the C code by first lowering C to LLVM-IR (clang) and by subsequently applying a
set of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
preparing transformations have been applied run Polly with '-O0'.

<pre class="code">pollycc -O0 -mllvm -polly -S -emit-llvm file.c</pre>

<h2>Further options</h2>

Polly supports further options that are mainly useful for the development or
the
analysis of Polly. The relevant options can be added to clang by appending
<b>-mllvm -option-name</b> to the CFLAGS or the clang
command line.

<h3>Limit Polly to a single function</h3>
To limit the execution of Polly to a single function, use the option
<b>-polly-only-func=functionname</b>.

<h3>Disable LLVM-IR generation</h3>
Polly normally regenerates LLVM-IR from the Polyhedral representation. To only
see the effects of the preparing transformation, but to disable Polly code
generation add the option <b>polly-no-codegen</b>.

<h3>Graphical view of the SCoPs</h3>

Polly can use graphviz to show the SCoPs it detects in a program. The relevant
options are <b>-polly-show</b>, <b>-polly-show-only</b>, <b>-polly-dot</b> and
<b>-polly-dot-only</b>. The 'show' options automatically run dotty or another
graphviz viewer to show the scops graphically. The 'dot' options store for each
function a dot file that highlights the detected SCoPs. If 'only' is appended at
the end of the option, the basic blocks are shown without the statements the
contain.

<h3>Change/Disable the Optimizer</h3>
Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes
for data-locality and parallelism using the <a
href="http://pluto-compiler.sf.net">Pluto</a> algorithm. For research it is also
possible to run <a
href="http://www-rocq.inria.fr/~pouchet/software/pocc/">PoCC</a> as external
optimizer. PoCC provides access to the original Pluto implementation. To use
PoCC add <b>-polly-optimizer=pocc</b> to the command line (only available if
Polly was compiled with scoplib support) [removed after <a href="http://llvm.org/releases/download.html#3.4.2">LLVM 3.4.2</a>].
To disable the optimizer entirely use the option <b>-polly-optimizer=none</b>.

<h3>Disable tiling in the optimizer</h3>
By default both optimizers perform tiling, if possible. In case this is not
wanted the option <b>-polly-tiling=false</b> can be used to disable it. (This
option disables tiling for both optimizers).

<h3>Ignore possible aliasing</h3>
By default we only detect scops, if we can prove that the different array bases
can not alias. This is correct do if we optimize automatically.  However,
without special user annotations like 'restrict' we can often not prove that
no aliasing is possible. In case the user knows no aliasing can happen in the
code the <b>-polly-ignore-aliasing</b> can be used to disable the check for
possible aliasing.

<h3>Import / Export</h3>
The flags <b>-polly-import</b> and <b>-polly-export</b> allow the export and
reimport of the polyhedral representation. By exporting, modifying and
reimporting the polyhedral representation externally calculated transformations
can be applied. This enables external optimizers or the manual optimization of
specific SCoPs.
</div>
</div>
</body>
</html>