doc/package/readme/index.xml

   1 <?xml version="1.0"?>
   2
   3 <!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
   4         "file:///usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">
   5
   6 <article>
   7
   8
   9 <articleinfo xmlns:xi="http://www.w3.org/2001/XInclude">
  10   <title>Installation Guide</title>
  11   <abstract>This article includes download, build, and installation
  12   instructions.</abstract>
  13 </articleinfo>
  14
  15 <edit by="David Hilvert" in-year="2007"/>
  16 <edit by="David Hilvert" in-year="2006"/>
  17 <edit by="David Hilvert" in-year="2005"/>
  18 <edit by="David Hilvert" in-year="2004"/>
  19 <edit by="David Hilvert" in-year="2003"/>
  20 <edit by="David Hilvert" in-year="2002"/>
  21
  22 <!--
  23 <s><t>Binaries</t>
  24
  25 <p>Official binaries are not available for this alpha release.</p>
  26
  27 <s><t>URLs</t>
  28
  29 <ul><li><winurl/>
  30 </li></ul>
  31 </s>
  32
  33 <s><t>Extraction and Use</t>
  34
  35 <p> The zip file available at the above URL is an archive containing the ALE
  36 executable; a zip archival utility can be used to extract the executable from
  37 the archive.  </p>
  38
  39 <p> Once extracted, since ALE is a command-line program, it may be necessary to
  40 open a command prompt window to use ALE successfully.  For more information
  41 about command-line usage and options, see the User Manual.  </p>
  42 </s>
  43
  44 </s>
  45 -->
  46
  47 <s><t>Compiling from source</t>
  48
  49 <s><t>URLs</t>
  50
  51 <ul><li><sourceurl/>
  52 </li></ul>
  53
  54 </s>
  55
  56 <s><t>Build prerequisites</t>
  57
  58 <s><t>GCC C++ compiler</t>
  59
  60 <p> GCC version 3.2.3 with C++ support is known to build ALE successfully.  Older
  61 versions of GCC may fail to compile some versions of ALE.</p>
  62
  63 </s>
  64
  65 <s><t>Prerequisites for building on Windows</t>
  66
  67 <p> Successfully running the configuration script on Windows (e.g., for native
  68 builds) may require installation of Cygwin.  For more information on Cygwin,
  69 see:</p>
  70
  71 <ul><li><ulink url="http://www.cygwin.com/"/>
  72 </li></ul>
  73
  74 <p>Alternatively, this package can be cross-compiled for Windows on a non-Windows
  75 architecture, provided that the appropriate cross-compilers and libraries are
  76 available.</p>
  77
  78 </s>
  79
  80 </s>
  81
  82 <s><t>Extraction</t>
  83
  84 <p>Download the source archive file from the URL indicated in the section
  85 'URLs', and invoke:</p>
  86
  87 <ll>tar xzf <sourcepacktargz/>
  88 cd <sourcepack/>
  89 </ll>
  90
  91 <p>Invoking 'ls configure' afterward should reveal an executable script
  92 'configure'.  This script is used to determine the capabilities of the system
  93 that will run the software.</p>
  94
  95 </s>
  96
  97 <s><t>Running configure</t>
  98
  99 <p>This package uses a configuration script, 'configure', generated by the GNU
 100 project build tools ("autotools").  For most cases, it should be sufficient to
 101 invoke:</p>
 102
 103 <ll>./configure
 104 make
 105 make install
 106 </ll>
 107
 108 <p>In cases where the defaults are not adequate, configuration options can be
 109 passed to the configuration script.</p>
 110 </s>
 111
 112 <s><t>Configuration options</t>
 113
 114 <p>Configuration options can be passed to the 'configure' script prior to build
 115 and installation, as:</p>
 116
 117 <ll>./configure --config-option1 --config-option2 ...
 118 make
 119 make install
 120 </ll>
 121
 122 <p>Options specific to this package are described in the following subsections.
 123 General configuration options are described in the file 'INSTALL' included in
 124 the source package.</p>
 125
 126 <s><t>ImageMagick Support</t>
 127
 128 <p>Enabling ImageMagick support allows ALE to make use of the file-handling
 129 capabilities of ImageMagick ( <ulink url="http://imagemagick.org/"/> ).  This
 130 includes reading and writing a variety of file formats, including, among many
 131 others, PNG and JPEG (two formats commonly used in web publishing) as well as
 132 common interchange formats such as PPM and TIFF.  ImageMagick 6.0.6 is known to
 133 work with this version of ALE; certain older versions of ImageMagick may cause
 134 compile, link, or runtime errors.  By default, support is automatically
 135 detected.</p>
 136
 137 <ll>--with-imagemagick=auto  Auto-detect ImageMagick support [default]
 138 --with-imagemagick=yes   Enable ImageMagick support
 139 --with-imagemagick=no    Disable ImageMagick support
 140 </ll>
 141 </s>
 142
 143 <s><t>Color Data Precision</t>
 144
 145 <p>ALE's internal data structures store each color channel within a pixel as
 146 floating-point data; similarly, arithmetic operations on color channels are
 147 performed in floating point.  The available data-type configurations are
 148 listed below, with typical data sizes indicated in parentheses.  </p>
 149
 150 <ll>--with-colors=single   Use C++ 'float' data type (32-bit)  [default]
 151 --with-colors=double   Use C++ 'double' data type (64-bit)
 152 </ll>
 153 </s>
 154
 155 <s><t>
 156 Coordinate Data Precision
 157 </t>
 158
 159 <p>In general, coordinate transformations used by ALE produce results outside of
 160 the set of integers; hence, coordinates are treated as floating-point data.
 161 The two available data-type configurations are listed below, with typical data
 162 sizes indicated in parentheses.</p>
 163
 164 <ll>--with-coords=single   Use C++ 'float' data type (32-bit)  [default]
 165 --with-coords=double   Use C++ 'double' data type (64-bit)
 166 </ll>
 167 </s>
 168
 169 <s><t>
 170 Thread support
 171 </t>
 172
 173 <p>
 174 Threads can improve performance on multiprocessor machines.  POSIX threads are
 175 currently supported.
 176 </p>
 177
 178 <ll>--enable-threads=auto  Auto-detect thread support.  [default]
 179 --enable-threads=yes   Enable thread support.
 180 --enable-threads=no    Disable thread support.
 181 </ll>
 182 </s>
 183
 184 <s><t>
 185 FFTW Support
 186 </t>
 187
 188 <p>
 189 This feature is required in order to use the --fl option; it also determines
 190 the approach to calculation of discrete Fourier transforms used by the
 191 Irani-Peleg renderer.  For more information on FFTW, see http://fftw.org/.
 192 </p>
 193
 194 <ll>--with-fftw3=auto      Auto-detect FFTW3.  [default]
 195 --with-fftw3=yes       Use FFTW3 discrete Fourier transform.
 196 --with-fftw3=no        Use built-in discrete Fourier transform.
 197 </ll>
 198 </s>
 199
 200
 201 <s><t>
 202 Enable --wmx
 203 </t>
 204
 205 <p>
 206 This build option is required in order to use the --wmx option.  If
 207 --enable-wmx is specified, it is expected that fork() and execlp() calls
 208 are available.
 209 </p>
 210
 211 <ll>--enable-wmx=auto      Automatically detect whether to enable --wmx
 212 --enable-wmx=yes       Enable --wmx
 213 --enable-wmx=no        Do not enable --wmx
 214 </ll>
 215 </s>
 216
 217 <s>
 218 <t>Getsize</t>
 219
 220 <p>This build option is required to obtain additional output from --ui=tty.  If
 221 TIOCGWINSZ is not defined in &lt;sys/ioctl.h>, however, additional output will not
 222 be provided even if --enable-getsize is specified at build time.
 223 </p>
 224
 225 <ll>--enable-getsize=auto   Check for TIOCGWINSZ at build time.  [default]
 226 --enable-getsize=yes    Configure to attempt to use TIOCGWINSZ
 227 --enable-getsize=no     Do not attempt to use TIOCGWINSZ
 228 </ll>
 229
 230 </s>
 231
 232 <s><t>
 233 Assertions
 234 </t>
 235
 236 <p>
 237 Finding bugs within ALE, or within custom modifications to ALE, can be
 238 simplified by enabling run-time assertions.  These checks enforce conditions
 239 believed to be necessary or desirable for correct program operation.  If a
 240 condition is not satisfied, ALE will abort and display a message indicating the
 241 failed assertion.
 242 </p>
 243
 244 <ll>--enable-assertions    Enable assertions.  [default]
 245 --disable-assertions   Disable assertions.
 246 </ll>
 247 </s>
 248
 249 </s>
 250
 251 <s><t>Cross-compilation</t>
 252
 253 <p>For cross-compilation, it may be necessary to specify both host and build
 254 machine types, using the configure --host and --build options.  For more
 255 information on these options, see the file 'INSTALL' in the source package.</p>
 256 </s>
 257
 258 <s><t>Further details</t>
 259
 260 <p>General operation of the configure script is described in more detail in the
 261 file 'INSTALL' in the source package.</p>
 262
 263 </s>
 264 </s>
 265
 266 <!--
 267 <s><t>Further Documentation</t>
 268
 269 <p>This alpha release only includes standard package documentation files.</p>
 270
 271 </s>
 272 -->
 273
 274 <s><t>On-line resources</t>
 275
 276 <ll>Home Page               http://auricle.dyndns.org/ALE/
 277 darcs repository        http://auricle.dyndns.org/darcs/ale/
 278 Mailing list archive    http://ventricle.dyndns.org/pipermail/ale/
 279 </ll>
 280
 281 <s><t>Mailing list</t>
 282
 283 <p>Bug reports, feature requests, patch and release announcements, and related
 284 discussion can be sent to ale@ventricle.dyndns.org.  Archives of past postings
 285 and subscription information are available at the URLs indicated below.</p>
 286
 287 <ll>Posting address         ale@ventricle.dyndns.org
 288 Subscription info       http://ventricle.dyndns.org/cgi-bin/mailman/listinfo/ale
 289 Archives                http://ventricle.dyndns.org/pipermail/ale/
 290 </ll>
 291
 292 </s>
 293 </s>
 294 </article>