% Allegro 4.9.x readme

Thanks for trying this development release of Allegro. This is currently work
in progress and only intended for developers. Here are some short notes.



Windows
=======

Allegro5 implements two graphics drivers for Windows: one using DirectX 9 and
another one using OpenGL. You can force using OpenGL by calling
al_set_new_display_flags(ALLEGRO_OPENGL) prior to creating a display, while
DirectX is the default driver.
You can also select the driver using the `allegro5.cfg` file.

Here are some files you may need regarding DirectX:

<http://trent.gamblin.ca/dx/>

Some of those are originally from:

<http://www.g-productions.net/list.php?c=files_devpak>

This is an experimental driver and more work still needs to be done
on compatibility. It works for many people, and doesn't work for others.
If you have problems, send and email to the alleg-developers list or
directly to Trent Gamblin @ trent2@gamblin.ca, and we may be able to
debug it further.



Linux / X Windows
=================

The only graphics driver implemented for Linux so far uses OpenGL on the X
Window System.  It has been tested with GLX 1.2 and above.  This driver isn't
Linux-specific so may work with other Unix-like systems but hasn't been
tested as such.



Mac OS X
========

We have an OpenGL graphics driver on Mac OS X as well.
The only sound driver we have on OS X at the moment uses OpenAL, so this is
required to get any sound at all on OS X. This should not normally be a
problem since OpenAL should be installed by default.



IPhone
======

This uses OpenGL ES for graphics. The touch screen is implemented as a mouse,
with multi-touch triggering different mouse buttons.



Compilation
===========

You will need CMake 2.6 or later.



Dependencies
------------

Many of the addons make use of additional libraries.  They are not required to
build Allegro, but a lot of functionality may be disabled if they are not
present.  We strongly suggest you install: libpng, zlib, FreeType, libogg,
libvorbis, libvorbisfile, libFLAC.

Windows users may find some precompiled binaries from
<http://gnuwin32.sourceforge.net/>.  You need to get the `bin` and `lib`
packages.  The `bin` packages contain DLLs, and the `lib` packages contain the
headers and import libraries.

Mac users may find some dependencies in Fink or MacPorts.
<http://www.finkproject.org/> and <http://www.macports.org/>

Linux users likely have all the dependencies already, except PhysicsFS
and DUMB. If your distribution uses separate development packages, they
will need to be installed.  The packages are probably named *-dev or *-devel.

- libpng and zlib, for PNG image support.
  Home page: <http://www.libpng.org/pub/png/>
  Windows binaries: <http://gnuwin32.sourceforge.net/packages/libpng.htm>

- libjpeg, for JPEG image support.
  Home page: <http://www.ijg.org/>
  Windows binaries: <http://gnuwin32.sourceforge.net/packages/jpeg.htm>

- FreeType, for TrueType font support.
  Home page: <http://freetype.sourceforge.net/>
  Window binaries: <http://gnuwin32.sourceforge.net/packages/freetype.htm>

- Ogg Vorbis, a free lossy audio format. (libogg, libvorbis, libvorbisfile)
  Home page: <http://www.vorbis.com/>

- FLAC, a free lossless audio codec. (libFLAC, libogg)
  Home page: <http://flac.sourceforge.net/>

- DUMB, an IT, XM, S3M and MOD player library. (libdumb)
  Home page: <http://dumb.sourceforge.net/>

- OpenAL, a 3D audio API.  The audio addon of Allegro can use OpenAL, although
  the 3D capabilities aren't used.
  <http://kcat.strangesoft.net/openal.html>

  On Mac OS X, OpenAL is *required* but should come with the OS anyway.

  On Linux and Windows, OpenAL will only be used if you request it, hence there
  is no reason to install it specifically.

- PhysicsFS, provides access to archives, e.g. .zip files.
  Home page: <http://icculus.org/physfs/>

- OpenGL.  This is optional on Windows, but mandatory everywhere else.

- One unimportant example program uses libcurl.  Don't bother to install
  libcurl just for this.



CMake & Unix or MinGW or Mac OS X
---------------------------------

Unpack Allegro into a directory *without spaces or other "weird" characters in
the path*.  This is a known problem.

CMake works by first creating a makefile, which then can be used to compile.

To use it:

First create a directory for the build to take place in.
(This is not strictly necessary but keeps things cleaner.)

	$ mkdir Build
	$ cd Build

Run `cmake` with whatever options you want.  See below for examples.
If you're not sure about any option, just leave it at the default.

*Note:* MinGW users: if you have `sh.exe` in your PATH you should call CMake
with the options `-G "MSYS Makefiles"`.  Otherwise, use `-G "MinGW Makefiles"`.
If you do have `sh` but it isn't from MSYS (e.g. it's from Unixutils) then
you might need to modify your PATH so `sh` isn't in it and use "MinGW
Makefiles" instead.

The option `CMAKE_BUILD_TYPE` selects release, debug or profiling
configurations.  Valid values are: Release, Debug, RelWithDebInfo, MinSizeRel,
Profile.

The option `SHARED` controls whether libraries are built as shared libraries
or static libraries.  Shared libraries are built by default.

*Note:* For MinGW with gcc < 4, you cannot build a static library because
TLS (thread local storage, using __thread) support was not introduced
until version 4.

Examples: (you only need one)

	$ cmake ..

	$ cmake .. -G "MinGW Makefiles" -DSHARED=off

	$ cmake .. -DCMAKE_BUILD_TYPE=Debug

Alternatively, you can use `ccmake` (Unix) or `cmake-gui` (Windows) to bring up
an interactive option selector. e.g. `ccmake ..` or `cmake-gui ..`.

*Note:* At least one user has had no luck with `cmake-gui` on Windows. If you
run into problems, please try again with `cmake`.

Now run `make` (or `mingw32-make`) and, optionally, `make install`.
(For MinGW users, you may have to set `MINGDIR` to point to your MinGW
directory before you do `mingw32-make install`):

	$ make
	$ make install



CMake & MSVC
------------

Unpack Allegro into a directory *without spaces or other "weird" characters in
the path*.  This is a known problem.

First open up a console and make sure that cmake.exe is in your %PATH%. You
ensure than by typing "SET PATH=C:\cmake\bin\;%PATH%" or similar. Typing
"cmake" should display the help message. It is also a good idea to have MSVC
compiler cl.exe in your path, and you must have lib.exe in your path.
You can do that by running vcvars32.bat script found in the directory where
MSVC is installed, or you can start the IDE then click "Tools > Visual Studio
20xx Command Prompt".

CMake works by first creating a project solution, which can then be opened
with MSVC IDE and built.

You may have to set your path to your DirectX SDK's Include and Lib directories,
	set INCLUDE=c:\program files\microsoft directx x.xx\include;%INCLUDE%
	set LIB=c:\program files\microsoft directx x.xx\lib\x86;%LIB%

You can use the same options from the CMake section above.

Examples:

	$ cmake -G "Visual Studio 8 2005" -DCMAKE_BUILD_TYPE=Debug

	$ cmake -G "Visual Studio 9 2008"

Or use the cmake-gui tool.

Now that the project solution has been generated, open it with the MSVC IDE
and start the building process.

*Note:*
As of the time this is written, CMake has a bug that causes the DLLs in
MSVC 10 to be named incorrectly. To work around this, generate MSVC 9 projects
instead.

*Note:*
The demo is currently excluded from the build if MSVC8 is detected, due to
some problems with IntelliSense.
Please give it a try and report problems.



Hints on setting up Visual C++ 2005 Express Edition
---------------------------------------------------

After installing Visual C++, you need to install the Platform SDK (or Windows
SDK), otherwise CMake will fail at a linking step.  You can do a web install to
avoid downloading a massive file.  For me, installation seemed to take an
inordinately long (half an hour or more), but eventually it completed.
Don't be too quick to hit Cancel.

You also need to install the DirectX SDK.  This is a big download, which I
don't know how to avoid.

Next, you'll need to tell VC++ about the Platform SDK.  Start the IDE.  Under
"Tools > Options > Projects and Solutions > VC++ Directories", add the Platform
SDK executable (bin), include and lib directories to the respective lists.
The DirectX SDK seems to add itself when it's installed.

Now you can open a command prompt with the correct environment by going to
"Tools > Visual Studio 2005 command prompt".  Change to the Allegro directory
and run CMake as before.

For debugging, use the DirectX control panel applet to switch to the debugging
runtime.  It's really useful.



Using the Clang compiler (OS X 10.6+)
-------------------------------------

It is possible to build Allegro using the Clang compiler that ships with OS
X 10.6 (Snow Leopard). Clang is installed in /Developer/usr/bin. 
To use it, you have to tell Cmake to use Clang instead of gcc. From the
terminal, this is most easily accomplished by the commands

	$ export PATH=/Developer/usr/bin:$PATH
   $ export CC=clang

before you run Cmake. If you use the graphical version of Cmake, you will
be given the option of selecting the C compiler to use. Simply select
/Developer/usr/bin/clang.
The installation otherwise continues as indicated above.



Running the examples
====================

Remember that some examples look for data files in the current directory, so if
you used an external build directory you will need to make sure the examples
can find the data files.  The CMake build has been set up to copy the data files
from the source directory to the build directory.



API documentation
=================

To build the documentation you will need Pandoc, and to run the build in a
POSIXy environment, i.e. containing sh, awk, sed, etc.  MSYS works on Windows.

Pandoc's home page is <http://johnmacfarlane.net/pandoc/>

HTML and man page documentation will be built by default, but Info and PDF
(through pdfLaTeX) can also be selected from the CMake options.

Online documentation is available on the Allegro web site:
<http://docs.liballeg.org/>

