README

   1 ========================
   2 ALE version 0.8.4 README
   3 ========================
   4
   5 This file includes download, build, and installation instructions specific to
   6 this software package.  For additional instructions on using 'autotools' build
   7 and installation scripts, see the 'INSTALL' file.  Documentation regarding use
   8 of the software is provided in the 'doc' directory of this package, and may
   9 also be available from the project web site.  See the end of this file for
  10 relevant URLs.
  11
  12 Subsections:
  13
  14         + Package URLs
  15         + Build prerequisites
  16                 - GCC C++ compiler
  17                 - Prerequisites for native Windows builds
  18                 - Cross compilation
  19         + Extraction
  20         + Running configure
  21         + Configuration options
  22                 - ImageMagick Support
  23                 - Color Data Precision
  24                 - Coordinate Data Precision
  25                 - FFTW Support
  26                 - Enable --wmx
  27                 - Getsize
  28                 - Assertions
  29         + Further Documentation
  30         + URLs
  31         + Mailing List
  32
  33
  34 Package URLs
  35 ============
  36
  37 http://auricle.dyndns.org/ALE/download/ale-0.8.4.tar.gz
  38
  39
  40 Build prerequisites
  41 ===================
  42
  43
  44 GCC C++ compiler
  45 ----------------
  46
  47 GCC version 3.2.3 with C++ support is known to build ALE successfully.  Older
  48 versions of GCC may fail to compile some versions of ALE.
  49
  50
  51 Prerequisites for native Windows builds
  52 ---------------------------------------
  53
  54 Successfully running the configuration script on Windows (e.g., for native
  55 builds) may require installation of Cygwin.  For more information on Cygwin,
  56 see:
  57
  58 http://www.cygwin.com/
  59
  60 Alternatively, this package can be cross-compiled for Windows on a non-Windows
  61 architecture, provided that the appropriate cross-compilers and libraries are
  62 available.
  63
  64
  65 Cross-compilation
  66 -----------------
  67
  68 For cross-compilation, it may be necessary to specify both host and build
  69 machine types, using the configure --host and --build options.  For more
  70 information on these options, see the 'INSTALL' file.
  71
  72
  73 Extraction
  74 ==========
  75
  76 Download the source archive file from the URL indicated in the section 'Package
  77 URLs', and invoke:
  78
  79         tar xzf ale-0.8.4.tar.gz
  80         cd ale-0.8.4
  81
  82 Invoking 'ls configure' afterward should reveal an executable script
  83 'configure'.  This script is used to determine the capabilities of the system
  84 that will run the software.
  85
  86
  87 Running configure
  88 =================
  89
  90 This package uses a configuration script, 'configure', generated by the GNU
  91 project build tools ("autotools").  For most cases, it should be sufficient to
  92 invoke:
  93
  94         ./configure
  95         make
  96         make install
  97
  98 Configuration options specific to this software package are described in the
  99 following section.  General operation of the script is described in more detail
 100 in the INSTALL file.
 101
 102
 103 Configuration options
 104 =====================
 105
 106 Configuration options should be passed to the 'configure' script prior to build
 107 and installation, as:
 108
 109         ./configure --config-option1 --config-option2 ...
 110         make
 111         make install
 112
 113 Options specific to this package are described in the following subsections.
 114 General configuration options are described in the INSTALL file.
 115
 116
 117 ImageMagick Support
 118 -------------------
 119
 120 Enabling ImageMagick support allows ALE to make use of the file-handling
 121 capabilities of ImageMagick ( http://imagemagick.org/ ).  This includes reading
 122 and writing a variety of file formats, including, among many others, PNG and
 123 JPEG (two formats commonly used in web publishing) as well as common
 124 interchange formats such as PPM and TIFF.  ImageMagick 6.0.6 is known to work
 125 with this version of ALE; certain older versions of ImageMagick may cause
 126 compile, link, or runtime errors.  By default, support is automatically
 127 detected.
 128
 129 --with-imagemagick=auto  Auto-detect ImageMagick support [default]
 130 --with-imagemagick=yes   Enable ImageMagick support
 131 --with-imagemagick=no    Disable ImageMagick support
 132
 133
 134 Color Data Precision
 135 --------------------
 136
 137 ALE's internal data structures store each color channel within a pixel as
 138 floating-point data; similarly, arithmetic operations on color channels are
 139 performed in floating point.  The available data-type configurations are
 140 listed below, with typical data sizes indicated in parentheses.
 141
 142 --with-colors=single   Use C++ 'float' data type (32-bit)  [default]
 143 --with-colors=double   Use C++ 'double' data type (64-bit)
 144
 145
 146 Coordinate Data Precision
 147 -------------------------
 148
 149 In general, coordinate transformations used by ALE produce results outside of
 150 the set of integers; hence, coordinates are treated as floating-point data.
 151 The two available data-type configurations are listed below, with typical data
 152 sizes indicated in parentheses.
 153
 154 --with-coords=single   Use C++ 'float' data type (32-bit)  [default]
 155 --with-coords=double   Use C++ 'double' data type (64-bit)
 156
 157
 158 FFTW Support
 159 ------------
 160
 161 This feature is required in order to use the --fl option; it also determines
 162 the approach to calculation of discrete Fourier transforms used by the
 163 Irani-Peleg renderer.  For more information on FFTW, see http://fftw.org/.
 164
 165 --with-fftw3=auto      Auto-detect FFTW3.  [default]
 166 --with-fftw3=yes       Use FFTW3 discrete Fourier transform.
 167 --with-fftw3=no        Use built-in discrete Fourier transform.
 168
 169
 170 Enable --wmx
 171 ------------
 172
 173 This build option is required in order to use the --wmx option.  If
 174 --enable-wmx is specified, it is expected that fork() and execlp() calls
 175 are available.
 176
 177 --enable-wmx=auto      Automatically detect whether to enable --wmx
 178 --enable-wmx=yes       Enable --wmx
 179 --enable-wmx=no        Do not enable --wmx
 180
 181
 182 Getsize
 183 -------
 184
 185 This build option is required to obtain additional output from --ui=tty.  If
 186 TIOCGWINSZ is not defined in <sys/ioctl.h>, however, additional output will not
 187 be provided even if --enable-getsize is specified at build time.
 188
 189 --enable-getsize=auto   Check for TIOCGWINSZ at build time.  [default]
 190 --enable-getsize=yes    Configure to attempt to use TIOCGWINSZ
 191 --enable-getsize=no     Do not attempt to use TIOCGWINSZ
 192
 193
 194 Assertions
 195 ----------
 196
 197 Finding bugs within ALE, or within custom modifications to ALE, can be
 198 simplified by enabling run-time assertions.  These checks enforce conditions
 199 believed to be necessary or desirable for correct program operation.  If a
 200 condition is not satisfied, ALE will abort and display a message indicating the
 201 failed assertion.
 202
 203 --enable-assertions    Enable assertions.  [default]
 204 --disable-assertions   Disable assertions.
 205
 206
 207 Further Documentation
 208 =====================
 209
 210 For information about command-line usage, program options, and program
 211 operation, see the manual included with this package.  The manual may also be
 212 available on-line at the URL listed in the following section.
 213
 214
 215 URLs
 216 ====
 217
 218 Home Page               http://auricle.dyndns.org/ALE/
 219 Manuals                 http://auricle.dyndns.org/ALE/manuals/
 220 Mailing list archive    http://ventricle.dyndns.org/pipermail/ale/
 221
 222
 223 Mailing List
 224 ============
 225
 226 Bug reports, feature requests, patch and release announcements, and related
 227 discussion can be sent to ale@ventricle.dyndns.org.  Archives of past postings
 228 and subscription information are available at the URLs indicated below.
 229
 230 Posting address         ale@ventricle.dyndns.org
 231 Subscription info       http://ventricle.dyndns.org/cgi-bin/mailman/listinfo/ale
 232 Archives                http://ventricle.dyndns.org/pipermail/ale/