README

   1 #
   2 #  /**-------------------------------------------------------------------**
   3 #   **                              CLooG                                **
   4 #   **-------------------------------------------------------------------**
   5 #   **                     The Chunky Loop Generator                     **
   6 #   **-------------------------------------------------------------------**
   7 #   **           First version of this file: january 22th 2002           **
   8 #   **-------------------------------------------------------------------**/
   9 #
  10
  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).
  14
  15 Overview :
  16 I.   Description
  17 II.  Building CLooG
  18 III. Options
  19 IV.  Running CLooG
  20 V.   General Questions
  21
  22 #   **-------------------------------------------------------------------**
  23 #   **                        I. Description                             **
  24 #   **-------------------------------------------------------------------**/
  25
  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.
  30
  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.
  37
  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           |
  62
  63 #   **-------------------------------------------------------------------**
  64 #   **                      II. Building CLooG                           **
  65 #   **-------------------------------------------------------------------**/
  66
  67 The configure shell script attempts to guess correct values for various
  68 system-dependent variables used during compilation. It uses those values to
  69 create a Makefile. The file configure.in is used to create configure by a
  70 program called autoconf.  You only need configure.in if you want to change
  71 it or regenerate configure using a newer version of autoconf.
  72
  73 The simplest way to compile this package is:
  74 cd to the directory containing the package's source code and type
  75
  76   ./configure
  77
  78 to configure the package for your system (while running, configure prints
  79 some messages telling which features it is checking for) (in the strange case
  80 where ./configure do not exists, you can build it by typing
  81 "autoconf -l autoconf autoconf/configure.in > configure"). To compile the
  82 package, type
  83
  84   make
  85
  86
  87 to install the program and/or the library, type
  88
  89   make install
  90
  91 you can remove the program binaries and object files from the source code
  92 directory by typing
  93
  94   make clean
  95
  96 To also remove the files that configure created (so you can compile the
  97 package for a different kind of computer) type
  98
  99   make distclean
 100
 101 #   **-------------------------------------------------------------------**
 102 #   **                           III. Options                            **
 103 #   **-------------------------------------------------------------------**/
 104
 105 By default,  make will install the package's files in /usr/local/bin,
 106 /usr/local/lib, etc. You can specify an installation prefix other than
 107 /usr/local by giving onfigure the option --prefix=PATH.
 108
 109 By default, configure will seek the PolyLib in standard locations.
 110 If necessary, you can specify the PolyLib's path by giving configure the
 111 option --with-polylib=PATH.
 112
 113 By default, configure will seek the GMP library in standard locations.
 114 If necessary, you can specify the GMP's path by giving configure the
 115 option --with-gmp=PATH.
 116
 117 By default, both CLooG and the CloogLib are compiled and installed.
 118 By giving configure the option --without-cloog you disable the
 119 compilation and installation of CLooG. By giving configure the option
 120 --without-lib you disable the compilation and installation of the CloogLib.
 121
 122 By default, CLooG and it's library are builded using 64 bits integer
 123 representation. You can choose to specify explicitly others integer
 124 representations by using:
 125 --with-bits=32  for 32 bits integers,
 126 --with-bits=64  for 64 bits integers (default),
 127 --with-bits=gmp for multiple precision integers.
 128
 129 #   **-------------------------------------------------------------------**
 130 #   **                         IV. Running CLooG                         **
 131 #   **-------------------------------------------------------------------**/
 132
 133 To run CLooG, simply type 'cloog', optionally followed by the name of an
 134 input file. You can type 'cloog -h' or 'cloog --help' for some help.
 135 For more informations, please check the ./doc subdirectory.
 136
 137 #   **-------------------------------------------------------------------**
 138 #   **                        V. General Questions                       **
 139 #   **-------------------------------------------------------------------**/
 140
 141 1. What does CLooG means ?
 142
 143 CLooG is the Chunky LOOp Generator, Chunky is an automatic loop optimizer for
 144 data locality. CLooG is a completely independent part of the Chunky project.
 145 Pronounce 'CLooG' as 'klug', which means 'sly' in german :-).
 146
 147 2. CLooG do not compile, what should I do ?
 148
 149 CLooG should compile everywhere (assuming that PolyLib is still there), thus
 150 there is a problem or the documentation is not clear, in both case it is
 151 necessary to ask the author(s) !
 152
 153 3. I need a feature that CLooG do not implement, what should I do ?
 154
 155 There are two ways. First, CLooG is a GPL software and library. So you
 156 are welcome to improve it yourself ;-) ! Many project have been successful, it
 157 is -maybe- a sign that this is not too hard to put your hands inside the
 158 source. Second, just ask the author(s) :-) ! Maybe a lot of people would be
 159 interessed by such feature, maybe many people asked for it before, maybe it's
 160 trivial to implement (and even)... Please just never hesitate to ask the
 161 author(s) !
 162
 163 4. I implemented a cool feature, can I commit it ?
 164
 165 Obviously you are welcome to send the author(s) any improvement. But obviously
 166 we are quite careful with readability, correctness and stability, and the
 167 author(s) will read, check and check again any contribution before including it.
 168 Thus, it can take time... There are few basic rules to write contributions:
 169 - (1) Do never change the indentation of any part of the code that is not yours.
 170 - (2) Do never send codes that use more than 80 columns.
 171 - (3) Do never send codes without a lot of comments in (bad or good) english.
 172 - (4) Do never send codes with obscure and/or non-english variable names.
 173 - (5) Use C, just C, only C (note: "//" comments are not C, variable declaration
 174   elsewhere than at the beginning of a block -better: a function-, is not C).
 175 Please understand that in order to live for a long time, and to be used in many
 176 projects the very first priority for CLooG is to be readable and documented.
 177
 178 5. Is CLooG bug free ?
 179
 180 No, who can ? ClooG is a complex program, and we do not pretend it to be bug
 181 free. Nevertheless because it has been tested and tested, we are fairly sure
 182 that CLooG results with default options have good chances to be satisfactory.
 183 If you find a result that looks strange, inadequate or incorrect, please send:
 184 - (1) The input file to the author(s).
 185 - (2) The output.
 186 - (3) The first line given by typing 'cloog -v'.
 187 - (4) All your command line options to achieve the result.
 188 We will try to explain the result or to fix the problem as soon as possible.
 189
 190 6. How can I ask the author(s) ?
 191
 192 Just send a mail to cedric.bastoul@inria.fr ! Or better, leave a message in the
 193 forum of http://www.CLooG.org
 194