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