PTC 2.0 C++ API X11 CLASSES Version 2.0.10 (beta)

The X11 classes are Copyright (c) 1998 Christian Nentwich (brn@eleet.mcb.at)
The PTC 2.0 C++ API is (c) 1998 Glenn Fiedler (ptc@gaffer.org)

This package and all included source code is licensed under the GNU LGPL
Please refer to the included file COPYING.LIB for the exact terms
------------------------------------------------------------------------------


This file will tell you how to compile PTC 2.0.9 for X 
(Please read CHANGES first if you're upgrading!!)


  1. Quick installation
     - Turn optimisation ON !!
     - Building HERMES
     - Building PTC
     	    Troubleshooting: Compilers with HERMES
	    Troubleshooting: Compiling HERMES with assembler routines

  2. More useful parameters
     - Configure parameters
	    NEW! Specifying a different make utility
	    Specifying a different compiler (egcs, pgcc, ...)
	    Troubleshooting: 'configure' doesn't work
  	    Troubleshooting: Lots of missing symbols with gcc 2.7.* (do not
	      		     go over -O2 with gcc 2.7.* or lower)
	    Specifying different install paths
	- Different Makefile commands (skipping examples, uninstall, etc.)
	


Quick installation
---------------------

  Above everything else, let me advices you to turn optimisation on when
compiling HERMES and PTC. This is VITAL due to the nature of these
libraries. If you use gcc, then start configure with CXXFLAGS="-O2". If
you use egcs or pgcc, that's even better, pass CXXFLAGS="-O6 -mpentium" to
configure. If you don't know how to pass these flags, read on.

  The installation has changed from PTC X11 2.0.7 on, because the pixel
conversion routines are a library on their own now (HERMES). Thus, the
installation is a two-stage process now.
      
	a) Build HERMES
	b) Build PTC
	in this order.

  Installing HERMES is easy. Just go to the Hermes-1.0.0 subdir and run
'./configure' and 'make'. Read the INSTALL file in the subdirectory for
options. You can also pass a different compiler and different flags to use,
more below.

  Now it's time to build PTC. Go to the directory this file is in again.
Type './configure' or if your shell is quite old 'sh ./configure' or 
'csh ./configure'.

  Then type 'make'. 

  What you get from this is:
    - A static library in library/
    - If you chose to build one, a dynamic library in library/
    - Example programs

  Optionally, install the library. Type 'make install'. This will put the
library and its headers under '/usr/local' by default. See README on how to
use it for your own applications then.

  Now, READ THE HTML documentation, it's going to tell you what is required
to initialise DGA mode (you have to be root, etc. etc.), what's required for
MIT Shm, etc.

TROUBLESHOOTING
  If you want to build the assembler files, you need Nasm, a freely available,
portable, and extremely nice (to the programmer) assembler. You can get it
at http://www.cryogen.com/Nasm. (The latest version is already a year old I
think).




More useful parameters
-------------------------

  You do have some influence on how 'configure' will work. For instance, you
can change the make utility that will be used, by using '--with-altermake=':

   ./configure --with-altermake=

  Or, you can change the compiler you want to use or the flags to pass to 
the compiler:
  
   'CXX=/usr/local/bin/g++ CXXFLAGS="-mpentium -O6" ./configure'

  This will use the compiler and flags specified above (on my system, that is
pgcc 1.0.3a). If this does not seem to change the compiler, try using the 'env'
command:

   'env CXX=/usr/local/bin/g++ CXXFLAGS="-mpentium -O6" ./configure

  The third method is to set the environment variables CXX and CXXFLAGS and
then start configure:
  
  setenv CXX '/usr/local/bin/g++'      or for bash
  export CXX="/usr/local/bin/g++"

  Please note that the whole tree will have to be remade now or otherwise
you might get missing symbols. It would be a wise idea to do a 'make distclean'
before running configure this way. Also, make sure HERMES has been compiled
with the same compiler.


TROUBLESHOOTING  
  If your './configure' does not want to run, try and type 'sh configure' or
'csh configure'. If that does not help you, you might want to try and rebuild
the configure script using automake (if you have it). Simply type 'automake'
in the main directory.
  If it still does not work, please send a bug report and you will hear from
me within a day's time.


TROUBLESHOOTING
  gcc 2.7.* really does NOT like exception handling very much. On my system
and on one SGI I tried it on, it messed up the code when I used optimisation
flags >-O2. Therefore: -O2 is the MAXIMUM on gcc. Of course there is no reason
not to use -O6 on pgcc ;)


  If you want to specify a different install path for the headers / library,
use the following when starting configure:
	
	'--prefix=PREFIX'	Headers and library will be installed under
				prefix/lib and prefix/include, respectively.
				The default for this is /usr/local
	'--exec-prefix=PREFIX'	The library will be installed in
				exec-prefix/lib.
 

  Now for the top level Makefile. You can type 'make command' where command is
any one of the following:

	'all'			Same as typing 'make', builds everything
	'ptclib'	        Build just the library, no examples
	'ptcexamples'	        Build only the examples (library has to exist
			        for this!)
	'clean'			Delete all object (*.o) files
	'distclean'		Delete all object files, executables, libraries
				Makefiles, i.e. restore a sane state :)
	'install'		Installs the headers and release library
	'uninstall'		Removes the headers and release library (use 
				only with the same version and configuration!)



That's it for now :)
brn

-----
Last modified 17/8/1998
