CLooG 0.18.4
[cloog.git] / README
blob7003a2b3e9a01c9d42378d8074f3c96ce73a3162
2 #  /**-------------------------------------------------------------------**
3 #   **                              CLooG                                **
4 #   **-------------------------------------------------------------------**
5 #   **                     The Chunky Loop Generator                     **
6 #   **-------------------------------------------------------------------**
7 #   **           First version of this file: january 22th 2002           **
8 #   **-------------------------------------------------------------------**/
11 For complete informations about this software, how to build and use it,
12 please see the postscript file in the ./doc subdirectory (a pdf version
13 is available in the web site).
15 Overview :
16 I.   Description 
17 II.  Building CLooG
18 III. Options
19 IV.  Running CLooG
20 V.   General Questions
22 #   **-------------------------------------------------------------------**
23 #   **                        I. Description                             **
24 #   **-------------------------------------------------------------------**/
26 CLooG is a software which generates loops for scanning Z-polyhedra. That is,
27 CLooG finds the code or pseudo-code where each integral point of one or more
28 parametrized polyhedron or parametrized polyhedra union is reached. CLooG is
29 designed to avoid control overhead and to produce a very efficient code.
31 Its input is some data on the polyhedra to scan, basically the system of
32 affine inequalities that define them, and a context that defines some
33 properties known on the parameters if any. The output is the pseudo scanning
34 code. Many facilities are provided to generate a near-to-be-compileable code,
35 and every useful functions to generate the code may be called from the CLooG
36 library.
38             INPUT                   |                 OUTPUT
39 (fortunately not exactly the input, |   (the real one, with default options)
40  check test/readme.cloog for the    |
41  real input for that problem !)     |
42                                     |
43         j^ i>=2                     |
44          | | j<=n+2-i               |
45          | |\     | i<=n            |
46          | | \    |                 |
47        m-+-****---+-j<=m            |    for (i=2;i<=n;i++) {
48          | *****  |                 |      for (j=2;j<=min(m,-i+n+2);j++) {    
49          | ****** |                ==>       S1 ;
50          | *******|                 |      }
51        2-+-********-j>=2            |    }
52          | |      |\                |
53        0-+-+------+--->i            |
54          | |      |                 |
55          0 2      n                 |
56                                     |
57        Context : n>=2               |
58                  m>=2               |
59        System  : 2<=i<=n            |
60                  2<=j<=m            |
61                  j<=n+2-i           |
63 #   **-------------------------------------------------------------------**
64 #   **                      II. Building CLooG                           **
65 #   **-------------------------------------------------------------------**/
67 If you obtained CLooG from the git repository, then you first
68 need to obtain the submodules and create a configure script.
70   ./get_submodules.sh
71   ./autogen.sh
73 The first step is only needed if you plan on using the isl backend.
75 The configure shell script attempts to guess correct values for various
76 system-dependent variables used during compilation. It uses those values to
77 create a Makefile. The file configure.ac is used to create configure by a
78 program called autoconf.  You only need configure.ac if you want to change
79 it or regenerate configure using a newer version of autoconf.
81 The simplest way to compile this package is:
82 cd to the directory containing the package's source code and type 
84   ./configure
86 to configure the package for your system (while running, configure prints
87 some messages telling which features it is checking for). To compile the
88 package, type
90   make
91   
93 to install the program and/or the library, type
95   make install
97 you can remove the program binaries and object files from the source code
98 directory by typing
99   
100   make clean
101   
102 To also remove the files that configure created (so you can compile the
103 package for a different kind of computer) type
104   
105   make distclean
107 #   **-------------------------------------------------------------------**
108 #   **                           III. Options                            **
109 #   **-------------------------------------------------------------------**/
111 By default,  make will install the package's files in /usr/local/bin,
112 /usr/local/lib, etc. You can specify an installation prefix other than 
113 /usr/local by giving onfigure the option --prefix=PATH.
115 By default, configure will use the isl that comes bundled with CLooG.
116 Using the --with-isl option of configure the user can specify that "no" isl,
117 a previously installed ("system") isl or a "build" isl should be used.
118 In the latter case, the user should also specify the build location
119 using --with-isl-builddir=PATH.  In case of an installed isl,
120 the installation location can be specified using the
121 --with-isl-prefix=PATH and --with-isl-exec-prefix=PATH options of configure.
123 By default, configure will seek the PolyLib in standard locations.
124 If necessary, you can specify the PolyLib's path by giving configure the
125 option --with-polylib-prefix=PATH and/or --with-polylib-exec-prefix=PATH.
127 By default, configure will seek the GMP library in standard locations.
128 If necessary, you can specify the GMP's path by giving configure the
129 option --with-gmp-prefix=PATH and/or --with-gmp-exec-prefix=PATH.
131 By default, when using the PolyLib backend,
132 CLooG and its library are built using 64 bits integer
133 representation. You can choose to specify explicitly others integer
134 representations by using:
135 --with-bits=32  for 32 bits integers,
136 --with-bits=64  for 64 bits integers (default),
137 --with-bits=gmp for multiple precision integers.
139 #   **-------------------------------------------------------------------**
140 #   **                         IV. Running CLooG                         **
141 #   **-------------------------------------------------------------------**/
143 To run CLooG, simply type 'cloog', optionally followed by the name of an
144 input file. You can type 'cloog -h' or 'cloog --help' for some help.
145 For more informations, please check the ./doc subdirectory.
147 #   **-------------------------------------------------------------------**
148 #   **                        V. General Questions                       **
149 #   **-------------------------------------------------------------------**/
151 1. What does CLooG means ?
153 CLooG is the Chunky LOOp Generator, Chunky is an automatic loop optimizer for
154 data locality. CLooG is a completely independent part of the Chunky project.
155 Pronounce 'CLooG' as 'klug', which means 'sly' in german :-).
157 2. CLooG do not compile, what should I do ?
159 CLooG should compile everywhere (assuming that PolyLib is still there), thus
160 there is a problem or the documentation is not clear, in both case it is
161 necessary to ask the author(s) !
163 3. I need a feature that CLooG do not implement, what should I do ?
165 There are two ways. First, CLooG is a LGPL software and library. So you
166 are welcome to improve it yourself ;-) ! Many project have been successful, it
167 is -maybe- a sign that this is not too hard to put your hands inside the
168 source. Second, just ask the author(s) :-) ! Maybe a lot of people would be
169 interessed by such feature, maybe many people asked for it before, maybe it's
170 trivial to implement (and even)... Please just never hesitate to ask the
171 author(s) !
173 4. I implemented a cool feature, can I submit it ?
175 Obviously you are welcome to send the author(s) any improvement. But obviously
176 we are quite careful with readability, correctness and stability, and the
177 author(s) will read, check and check again any contribution before including it.
178 Thus, it can take time... There are few basic rules to write contributions:
179 - (1) Do never change the indentation of any part of the code that is not yours.
180 - (2) Do never send codes that use more than 80 columns.
181 - (3) Do never send codes without a lot of comments in (bad or good) english.
182 - (4) Do never send codes with obscure and/or non-english variable names.
183 - (5) Use C89, just C, only C (note: "//" comments are not C89,
184   variable declaration elsewhere than at the beginning of a block, is not C89).
185 - (6) Read doc/SubmittingPatches
186 Please understand that in order to live for a long time, and to be used in many
187 projects the very first priority for CLooG is to be readable and documented.
189 5. Is CLooG bug free ?
191 No, who can ? ClooG is a complex program, and we do not pretend it to be bug
192 free. Nevertheless because it has been tested and tested, we are fairly sure
193 that CLooG results with default options have good chances to be satisfactory.
194 If you find a result that looks strange, inadequate or incorrect, please send:
195 - (1) The input file to the author(s).
196 - (2) The output.
197 - (3) The first line given by typing 'cloog -v'.
198 - (4) All your command line options to achieve the result.
199 We will try to explain the result or to fix the problem as soon as possible.
201 6. How can I contact the author(s) ?
203 Just send a mail to cloog-development@googlegroups.com