1====================================================
2         Building and Installing Cal3D
3====================================================
4
5      The Cal3D Team  (February 22, 2003)
6
7----------------------------------------------------
8
9Table of Contents
10
11  - Win32 Installation
12  - Build System Dependencies
13  - Basic Installation
14  - Some Useful Configuration Options
15  - Configuration Examples
16  - Installation Locations
17  - Important Note for IRIX Users
18
19----------------------------------------------------
20
21
22
23--------------------
24Win32 Installation
25--------------------
26
27   Those wishing to build the Cal3D library on Win32 platforms can use
28the included Visual Studio project files. Cal3D is known to work properly
29with Visual Studio 6 and Visual Studio .NET.
30
31
32-------------------------
33Build System Dependencies
34-------------------------
35
36   To configure and build the Cal3D library, you need the following tools:
37
38   GNU Autoconf 2.50 or newer
39   GNU Automake 1.9 or newer
40
41   The source packages can be found at:
42
43   ftp://ftp.gnu.org/gnu/autoconf
44   ftp://ftp.gnu.org/gnu/automake
45
46
47------------------
48Basic Installation
49------------------
50
51   Cal3D uses GNU's autobuild tools in order to allow users to build
52the library from source using the same methods on a wide variety of
53platforms.
54
55The simplest way to compile this package is:
56
57  1. In the top-level directory of the cal3d package, run `autoreconf --install --force'
58     to automatically generate the configuration scripting files.
59
60  2. Type `./configure' to configure the package for your system.
61
62     Running `configure' takes a while.  While running, it prints some
63     messages telling which features it is checking for. See below for
64     more info on configuring Cal3D.
65
66  3. Type `make' to compile the package.
67
68  4. Type `make install' to install the library and header files into
69     the appropriate location.
70
71  5. You can remove the program binaries and object files from the
72     source code directory by typing `make clean'.
73
74
75   The `autoreconf' script will run the autotools for you and create
76the configure script and Makefile.in files, which will be used during
77the build process.
78   The `configure' shell script attempts to guess correct values for
79various system-dependent variables used during compilation.  It uses
80those values to create a `Makefile' in each directory of the package.
81It may also create one or more `.h' files containing system-dependent
82definitions.  Finally, it creates a shell script `config.status' that
83you can run in the future to recreate the current configuration, a file
84`config.cache' that saves the results of its tests to speed up
85reconfiguring, and a file `config.log' containing compiler output
86(useful mainly for debugging `configure').
87
88
89---------------------------------
90Some Useful Configuration Options
91---------------------------------
92
93   When using the `configure' script, you might want to use some of the
94optional flags to change various aspects of the build and installation.
95Below are some of the most commonly-used options.
96
97
98   --prefix=<DIR>          Sets the package to be installed in a particular
99                           location. By default, Cal3D is installed to
100                           /usr/local
101
102   --with-cxx=<COMPILER>   Forces the use of a particular compiler. By default,
103                           the CXX environment variable is used.
104
105
106   --enable-16bit-indices  Tells Cal3D to use 16-bit unsigned short indices
107                           instead of the default 32-bit integer. This could
108                           result in a slight performance boost.
109
110   --enable-rtti           Enables runtime type identification. By default,
111                           it is disabled.
112
113   --enable-static         Allow a static Cal3D library to be built. By
114                           default, only the shared library is built.
115
116   --disable-shared        Prevent the shared library from being built. By
117                           default, it will be created.
118
119
120   To get a list of all configuration options that the script supports, type
121`./configure --help'.
122
123
124----------------------
125Configuration Examples
126----------------------
127
128* Example: a RedHat 7.2 system with gcc3 support
129
130      ./configure --with-cxx=g++3
131
132
133* Example: a user performing a local installation
134
135      ./configure --prefix=/home/users/jahare/software
136
137
138* Example: an Irix user wanting to build only static libraries
139
140      ./configure --with-cxx=CC --enable-static --disable-shared
141
142
143* Example: a user integrating Cal3D with his own app that requires RTTI
144
145      ./configure --prefix=/home/users/jahare/software --enable-rtti
146
147
148----------------------
149Installation Locations
150----------------------
151
152   By default, `make install' will install the package's files in
153`/usr/local/lib', `/usr/local/include', etc.  You can specify an
154installation prefix other than `/usr/local' by giving `configure' the
155option `--prefix=PATH'.
156
157   You can specify separate installation prefixes for
158architecture-specific files and architecture-independent files.  If you
159give `configure' the option `--exec-prefix=PATH', the package will use
160PATH as the prefix for installing programs and libraries.
161Documentation and other data files will still use the regular prefix.
162
163   If the package supports it, you can cause programs to be installed
164with an extra prefix or suffix on their names by giving `configure' the
165option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
166
167-----------------------------
168Important Note for IRIX Users
169-----------------------------
170
171   Cal3D uses GNU libtool to build the programming library. Some versions
172of libtool have a problem building dynamic libraries on Irix with the
173CC compiler, due to the necessity of the -LANG:std flag. As a result,
174you may experience runtime linking problems in your applications that
175use Cal3D's shared library (libcal3d.so).
176   A solution to this problem is to build a static Cal3D library (libcal3d.a)
177instead of a shared library. This can be accomplished by adding the flags
178`--enable-static' and `--disable-shared' to your configure script. An
179example configure command would then be:
180
181   ./configure --with-cxx=CC --enable-static --disable-shared
182
183This problem should NOT affect Irix developers using the gcc compiler.
184