COMPILING SOURCE CODE DOCUMENTATION FOR POV-Ray 3.1
1.0
INTRODUCTION AND DISCLAIMERS
This documentation is to help you compile the portable C source code into
a
working executable version of POV-Ray. This is only for those people who
want to compile a custom version of POV-Ray or to port it to an
unsupported
platform or compiler.
This documentation DOES NOT tell you how to use POV-Ray. User
documentation, sample scenes and scene "include" files are in the
archives
which contain the pre-compiled executable versions or as a separate
archive
for Unix users who have no official executable versions. You MUST HAVE
the
user documentation and sample scenes to use POV-Ray. See the file
POVWHERE.GET for details on what to get and where to get it.
The first question you should ask yourself before proceeding is "Do I
really need to compile POV-Ray at all?" Official POV-Ray Team executable
versions are available for MS-Dos, Windows 3.1x/95/NT, Mac 68k, Mac Power
PC, Amiga, and Linux for Intel x86. Other unofficial compiles may soon
be available for other platforms. If you do not intend to add any custom
or experimental features to the program, and if an executable already
exists for your platform then you need not compile this program yourself.
If you do want to proceed, you should be aware that you are very nearly
on
your own. This documentation and other related compiling documentation
assumes you know what you are doing. It assumes you have an adequate C
compiler installed and working. It assumes you know how to compile and
link large, multi-part programs using a "make" utility or an IDE project
file if your compiler supports them. Because makefiles and project files
often specify drive, directory or path information, we cannot promise our
makefiles or projects will work on your system. We assume you know how
to
make changes to makefiles and projects to specify where your system
libraries and other necessary files are located.
In general you should not expect any technical support from the POV-Ray
Team on how to compile the program. Everything is provided here "as is".
All we can say with any certainty is that we were able to compile it on
our
systems. If it doesn't work for you, we probably cannot tell you why.
There is no technical documentation for the source code itself except for
the comments in the source files. We try our best to write clear, wellcommented code but some sections are barely commented at all and some
comments may be out dated. We do not provide any technical support to
help
you to add features. We do not explain how a particular feature works.
In
some instances, the person who wrote a part of the program is no longer
active in the Team and we don't know exactly how it works.
When making any custom version of POV-Ray or any unofficial compile,
please
make sure you read and follow all provisions of our license in the file
POVLEGAL.DOC. In general you can modify and use POV-Ray on your own
however you want but if you distribute your unofficial version you must
follow our rules. You may not under any circumstances use portions of
POVRay source code in other programs.
2.0
DIRECTORY STRUCTURE
POV-Ray source code is distributed in archives with files arranged in a
particular hierarchy of directories or folders. When extracting the
archives, you should do so in a way that keeps the directory structure
intact. In general we suggest you create a directory called \povray3 and
extract the files from there. The extraction will create a directory
called "source" with many files and sub-directories from it.
In general, there are separate archives for each hardware platform and
operating system but each of these archives may support more than one
compiler. For example here is the directory structure for the Unix
archive.
source
source/libpng
source/zlib
source/unix
The source directory contains source files for the generic parts of POVRay
that are the same on all platforms. The source/libpng contains files for
compiling a library of routines used in reading and writing PNG (Portable
Network Graphics) image files. The source/zlib contains files for
compiling a library of routines used by libPNG to compress and uncompress
data streams. All of these files are used by all platforms and
compilers.
They are in every version of the source archives.
The source/unix directory contains source files for the Unix version
that are common to all supported Unix systems. POV-Ray was developed
on Linux and SunOS systems using the GNU ANSI C compiler (gcc), but has
also been compiled and tested using the IBM xlc compiler under AIX. It
should also compile with the older K&R style compilers, but this hasn't
been extensively tested.
The source/unix directory is only in the Unix archive. The DOS archive
contains SOURCE\MSDOS. Similarly the Windows archive contains a
SOURCE\WINDOWS directory, etc.
The source/unix directory contains a file CMPL_Unix.doc which contains
compiling information specific to the Unix version. There is also the
README.unix which contains other important information specific to the
Unix versions. Other platform specific directories contain similar
CMPL_xxx.DOC files. Be sure to read all pertinent CMPL_xxx.doc files
for your platform and compiler.
3.0
CONFIGURING POV-Ray SOURCE
Every platform has a header file "config.h" that is generally in the
platform specific directory but may be in the compiler specific
directory.
Some platforms have multiple versions of this file and you may need to
copy
or rename it as config.h. This file is #included in every module of POVRay. It contains any prototypes, macros or other definitions that may be
needed in the generic parts of POV-Ray but must be customized for a
particular platform or compiler.
For example different operating systems use different characters as a
separator between directories and file names. MS-Dos uses a back slash,
Unix a front slash, or Mac a colon. The config.h file for all MS-DOS
versions contains the following:
#define FILENAME_SEPARATOR '\'
which tells the generic part of POV-Ray to use a '\' to denote a
directory.
Every customization that the generic part of the code needs has a default
setting in the file source/frame.h which is also included in every module
after config.h. The frame.h header contains many groups of defines such
as
this:
#ifndef FILENAME_SEPARATOR
#define FILENAME_SEPARATOR '/'
#endif
which basically says "if we didn't define this previously in config.h
then
here's a default value." See frame.h to see what other values you might
wish to configure.
If any of the definitions are used to specify platform specific
functions,
you should also include a prototype for that function. For example the
file source/unix/xwinconf.h not only contains the macro:
#define POV_DISPLAY_INIT(w,h) XWIN_display_init (w, h);
to define the name of the graphics display initialization function, it
contains the prototype:
void XWIN_Display_Init (int w, int h);
If you plan to port POV-Ray to an unsupported platform, you should
probably
start with the simplest, non-display generic Unix version. Then add new
custom pieces via the config.h file.
4.0
CONCLUSION
We understand that this file is only the most trivial first steps but
half
the fun of working on POV-Ray source is digging in and figuring it out on
your own. That's how the POV-Ray Team members got started. We've tried
to
make the code as clear as we can.
Be sure to read the CMPL_xxx.doc files in your platform specific and
compiler specific directories for some more minor help if you are working
on a supported platform or compiler.
Good luck!