INSTALL [17. Mar 2004]

Compilation Instructions for Ayam
---------------------------------

There are two major ways to compile Ayam, "shared" and "wrapped standalone"
( using Wrap0.3 ).
The binaries you get with the binary distribution of Ayam are "wrapped
standalone". This means Tcl/Tk and the main Tcl-scripts of Ayam are all
statically combined in the binary. This means no hassle with Tcl/Tk
versions. You do not need an installed Tcl/Tk at all! However, the creation
of "wrapped standalone" executables of Ayam is a bit tricky. Therefore,
if you really want to or have to compile Ayam:
_Please compile a "shared" version of Ayam!_


Contents:
1. Compiling a Shared Version of Ayam
2. Compiling a Wrapped Standalone Version of Ayam
3. Additional Targets (Compiling Plugins)


1. Compiling a Shared Version of Ayam
-------------------------------------

1.1 Step 1 - Requirements
-------------------------

The following requirements _must_ be met to compile a shared
version of Ayam:

- ANSI-C-compiler
- Tcl/Tk sources ( atleast V8.0 )
  ftp://ftp.scriptics.com/pub/tcl/
  ( May move to SourceForge in the future, see:
    http://tcl.sourceforge.net/ ) 
  Note that a complete installation of Tcl/Tk is required.
  However:
   On most systems, there should be an installed Tcl/Tk 8.x nowadays.
   If this is the case
   ( check it by typing "wish" in a shell, then type "puts $tcl_patchLevel" )
   you then just have to download the sources of the installed
   version ( see output of the puts command! ), unpack them,
   and run configure.
   No compiling of this Tcl/Tk is necessary!
  Note also that Ayam uses Togl, a Tk-Widget that needs internal
  Tk-headers to be compiled. It is _not sufficient_ to just have
  an installed Tcl/Tk on your system, please
  _get the source distribution_ of Tcl/Tk and get the right
  version, as Togl is known to crash if Tcl/Tk versions mismatch!
- OpenGL ( gl.h, glu.h, libGL.so, libGLU.so )
  Version of GL is uncritical ( 1.1 should do, see also Note 1 ),
  Version of GLU should be atleast 1.2 ( due to the use of the GLU
  tesselation facility in the PolyMesh and SubdivisionMesh objects ),
  ( Mesa may be used as replacement for a real OpenGL. Since
    version 3.5, Mesa uses the GLU from the free OpenGL sample
    implementation from SGI and is therefore able to display
    trimmed NURBS. Either install this version of Mesa, or the GLU
    from the SGI sample implementation. )
  http://www.mesa3d.org/
- BMRT ( ri.h, slc.h, libribout.a, libslcargs.a )
  http://www.exluna.com/
  Note that BMRT's libribout.a and libslcargs.a come as binary only,
  they might not be available on your platform!
  If BMRT is not available on your platform, you can still
  compile Ayam with the Affine Toolkit with reduced functionality,
  read: no parsing of slc-compiled shaders.
  You can also use libslxargs from Aqsis ( http://www.aqsis.com/ )
  as libslcargs replacement.
- TIFF ( tiffio.h, libtiff.so )
  http://www.libtiff.org/
- The Affine Toolkit
  http://www.affine.com/
  Source code of Affines Simple RIB writer is distributed with Ayam
  ( see subdir "affine/" ).
  No download necessary, unless you want to compile the RRIB (RIB import)
  plugin!
- BWidgets
  http://tcllib.sourceforge.net/
  Ayam has just been tested with BWidgetsV1.2.1 so far.
  BWidgetsV1.2.1 are distributed with Ayam ( see subdir "tcl/BWidget-1.2.1/" ).
  No download necessary!

Tip:
If you unpack Tcl/Tk and BMRT as sister directories to the Ayam
directory, editing of the Makefile will be easier.

Note 1:
If OpenGL 1.1 is not available to you, you can still compile Ayam, if your
OpenGL is supporting the polygon offset extension (e.g. on IRIX 6.2).


1.2 Step 2 - Compiling
----------------------

You have all required software and installed/compiled it successfully?

Since Ayam1.7, a Tcl script is provided, that helps to create a basic
Makefile. Just run it by typing:
>wish ayamConf.tcl
and select your RIB-writer, shader-parser, and operating system.
Now you can make additional adjustments, e.g. determine where the
Tcl/Tk sources are, and where BMRT or Aqsis are installed.
Then press the "Create Makefile!" button.

If you do not use ayamConf.tcl you will need to execute the following
two steps:
- copy Makefile.shared to Makefile:
>cp Makefile.shared Makefile

- edit the Makefile, until it tells you to stop, all necessary
  information should be in the Makefile ( yes, this _is_ a lot of work ):
>emacs Makefile

- if you are done editing the Makefile just enter:
>make

Now ayamsh should be compiled and ready for a test run.
- try it:
>./ayamsh tcl/ayam.tcl


1.3 Step 3 - Installation
-------------------------

If all went fine, you can now install Ayam:
>make install

By default, Ayam will install into /usr/local/ayam.
It will create some sub-directories there, namely:
/usr/local/ayam/bin for the executable,
/usr/local/ayam/lib for the plugins and accompanying Tcl files, and
/usr/local/ayam/doc for the documentation.

You may want to add "/usr/local/ayam/bin" to your PATH environment variable.
Be sure to also add "." or "/usr/local/ayam/lib" to your LD_LIBRARY_PATH
environment variable, otherwise Ayam might not be able to load the plugins.

The installation procedure will also install the current Makefile,
that may be used to uninstall Ayam again, e.g. using:
>make -f /usr/local/ayam/lib/Makefile uninstall

The installation procedure also creates a shell script named "ayam",
that calls "ayamsh" the right way, so that after installation you can
start Ayam by typing:
>ayam



2. Compiling a Wrapped Standalone Version of Ayam
-------------------------------------------------

2.1 Step 1 - Requirements
-------------------------

The following requirements _must_ be met to compile a wrapped standalone
version of Ayam:

- ANSI-C-compiler
- Tcl/Tk sources ( V8.2.x )
  ftp://ftp.scriptics.com/pub/tcl/
  ( May move to SourceForge in the future, see:
    http://tcl.sourceforge.net/ )
  Note that you do not need to _install_ Tcl/Tk to compile and use
  the wrapped standalone version of Ayam. But compiling this Tcl/Tk
  is still necessary. Compile static versions of Tcl/TK using:
  >cd tcl8.2.x/unix
  >./configure --disable-shared; make
  >cd tk8.2.x/unix
  >./configure --disable-shared; make
  Also note that Wrap0.3 currently only works with Tcl/Tk 8.2.x, not
  8.3.x, and not 8.4.x!
- A zip utility that understands the -A option ( zip2.2 does ).
- Wrap0.3
  http://purl.oclc.org/net/nijtmans/wrap.html
  Please compile a static "libz":
  >make z
  and a wrapped "wish" using wrap:
  >make
  and do not "make clean" afterwards. Note that Makefile.wrapped
  is tuned to be used with Wrap0.3. If you use newer versions you
  will likely have to adapt the ayam: and ayamwrap: targets.
- OpenGL ( gl.h, glu.h, libGL.so, libGLU.so )
  Version of GL is uncritical ( 1.1 should do ),
  Version of GLU should be atleast 1.2 ( due to the use of the GLU
  tesselation facility in the PolyMesh and SubdivisionMesh objects ),
  ( Mesa may be used as replacement for a real OpenGL. Since
    version 3.5, Mesa uses the GLU from the free OpenGL sample
    implementation from SGI and is therefore able to display
    trimmed NURBS. Either install this version of Mesa, or the GLU
    from the SGI sample implementation. )
  http://www.mesa3d.org/
- BMRT ( ri.h, slc.h, libribout.a, libslcargs.a )
  http://www.exluna.com/
  Note that BMRT's libribout.a and libslcargs.a come as binary only,
  they might not be available on your platform!
  If BMRT is not available on your platform, you can still
  compile Ayam with the Affine Toolkit with reduced functionality,
  read: no parsing of slc-compiled shaders.
  You can also use libslxargs from Aqsis ( http://www.aqsis.com/ )
  as libslcargs replacement.
- TIFF ( tiffio.h, libtiff.so )
  http://www.libtiff.org/
- The Affine Toolkit
  http://www.affine.com/
  Source code of Affines Simple RIB writer is distributed with Ayam
  ( see subdir "affine/" ).
  No download necessary, unless you want to compile the RRIB (RIB import)
  plugin!
- BWidgets
  http://tcllib.sourceforge.net/
  Ayam has just been tested with BWidgetsV1.2.1 so far.
  BWidgetsV1.2.1 are distributed with Ayam ( see subdir "tcl/BWidget-1.2.1/" ).
  No download necessary!


Tip:
If you unpack Tcl/Tk, Wrap, and BMRT as sister directories
to the Ayam directory, editing of the Makefile will be easier.


2.2 Step 2 - Compiling
----------------------

You have all required software and installed/compiled it successfully?

- copy Makefile.wrapped to Makefile:
>cp Makefile.wrapped Makefile

- edit the Makefile, until it tells you to stop, all necessary
  information should be in the Makefile ( yes, this _is_ a lot of work ):
>emacs Makefile

- issue a
>make

Now Ayam should be compiled and ready for a test run.
-try it:
>./ayam


2.3 Step 3 - Installation
-------------------------

If all went fine, you can now install Ayam:
>make install

By default, Ayam will install into /usr/local/ayam.
It will create some sub-directories there, namely:
/usr/local/ayam/bin for the executable,
/usr/local/ayam/lib for the plugins and accompanying Tcl files, and
/usr/local/ayam/doc for the documentation.

You may want to add "/usr/local/ayam/bin" to your PATH environment variable.
Be sure to also add "." or "/usr/local/ayam/lib" to your LD_LIBRARY_PATH
environment variable, otherwise Ayam might not be able to load the plugins.

The installation procedure will also install the current Makefile,
that may be used to uninstall Ayam again, e.g. using:
>make -f /usr/local/ayam/lib/Makefile uninstall


3. Additional Targets (Compiling Plugins)
-----------------------------------------

Independent from the build type of Ayam, the Makefiles contain
additional targets to build plugins and manage the installation.

3.1 MF3D Import/Export Plugin
-----------------------------

To compile the MF3D Import/Export plugin two steps are required:
>make mf3d
( to compile the MF3D code from Apple (Duet) )
and
>make mfio.so
( to compile the plugin )

Load the plugin via menu entry "File/Load Custom".
Use it via menu entry "Custom/3DMF/Import" and "Custom/3DMF/Export"
respectively.


3.2 RIB Import Plugin (RRIB)
----------------------------

Additional prerequisites for the RIB import plugin:
You need the full Affine distribution
( download it from http://www.affine.com/ )!

Compile libribrdr.a, libribhash.a and libribnop.a.
This is done using 
>cd affine

>make setup<your platform>
( use "sun" as platform on Linux )

If you are using Affine0008 you need to tune Affine to _not_
use libz by editing "config.mak":
remove "-DRIB_ZLIB" from COPTS and do not link with libz.

If you are using Affine0008 and gcc you, additionally, need to change
"readrib/declare.c":
o change all occurences of the variable "inline" to "myinline"
( gcc does not like variables named "inline" without -ansi, but fails
to compile other parts of Affine if -ansi is enabled )

now compile Affine:
>make World

go back to Ayam:
>cd ayam/src
Point your Ayam Makefile to the Affine libraries,
see the variable RRIBLIBS.
Watch out for possible version clashes of header files
( ayam/src/affine/include vs. affine/include ).
The version of the Affine headers currently distributed with Ayam
is 0008. If needed, just copy the headers from the Affine distribution
to the Ayam distribution.

Now compile the plugin:
>make rrib.so

Load it via menu entry "File/Load Custom".
Use it via menu entry "Custom/RRIB/Import RIB"


3.3 Importance Driven Rendering Plugin (IDR)
--------------------------------------------

Additional prerequisites to compile IDR are:
libtiff library and libtiff headers have to be installed.

>make idr.so

Load it via menu entry "File/Load Custom".
Use it via menu entry "Custom/Open IDR".


3.4 Shader Parsing Plugins
--------------------------

Ayam supports the following shader parsing plugins:
"ayslb" for Air, "ayso" for RDC, "ayslo" for PRMan, "ayslx" for Aqsis,
"ayslo3d" for 3Delight, and "aysdr" for Pixie.
Additional prerequisites:
The respective renderer has to be installed to compile a shader parsing
plugin.

In order to compile those plugins, adapt the following variables
in the Makefile:
for Aqsis: AQSISDIR, AYSLXINCDIR, AYSLXLIBS,
for RenderDotC: RDCDIR, AYSOINCDIR, AYSOLIBS,
for PRMan: PRMANDIR, AYSLOINCDIR, AYSLOLIBS,
for 3Delight: 3DLDIR, AYSLO3INCDIR, AYSLO3DLIBS,
for Pixie: SDRDIR, AYSDRINCDIR, PIXIESRC, AYSDRLIBS

then type:
>make ayslb.so
>make ayslo.so
>make ayslo3d.so
>make ayso.so
>make ayslx.so
>make aysdr.so

After loading of one of these plugins the internal shader scanning code
of Ayam will be disabled, and Ayam will from that moment on just scan
shaders of the type supported by the plugin loaded.


3.5 Installing/Uninstalling Ayam
--------------------------------

Use
>make install
to install Ayam into the system.

By default, Ayam will install into /usr/local/ayam.
It will create some sub-directories there, namely:
/usr/local/ayam/bin for the executable,
/usr/local/ayam/lib for the plugins and accompanying Tcl files, and
/usr/local/ayam/doc for the documentation.

You may want to add "/usr/local/ayam/bin" to your PATH environment variable.
Be sure to also add "." or "/usr/local/ayam/lib" to your LD_LIBRARY_PATH
environment variable, otherwise Ayam might not be able to load the plugins.

The installation procedure will also install the current Makefile,
that may be used to uninstall Ayam again, e.g. using:
>make -f /usr/local/ayam/lib/Makefile uninstall

Use
>make clean
to remove all objects; this step is necessary if you switch build types
( shared <-> wrapped )!

>make mostlyclean
to make clean but not remove the objects that never change,
like Apples mf3d code and Affines sribw code.

End of Compilation Instructions,
-- 
http://www.ayam3d.org/    Reconstruct the World!

