COMPILER AND SOURCE CODE DOCUMENTATION
FOR MS-DOS SPECIFIC PARTS OF POV-Ray 3.00
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 for MS-Dos. Before proceeding any
farther, you should first read the file COMPILE.DOC in the root directory
of the source archive. It provides important information about the generic
parts of POV-Ray.
This documentation DOES NOT tell you how to use POV-Ray for MS-Dos. It is
assumed you already have obtained the official executable archive compiled
for MS-Dos and that you are familiar with using it. It contains essential
user documentation, sample scenes and standard scene include files. User
documentation is in the executable archive in the hypertext file
POVHELP.PHE. The executable archive also includes a help reader program to
read PHE files and utilities to translate PHE into other forms. MS-Dos
specific user documentation is in the text file POVMSDOS.DOC in the
executable archive.
The first question you should ask yourself before proceeding is "Do I
really need to compile POV-Ray at all?" If you do not intend to add any
custom or experimental features to the program, or to port it to an
unsupported compiler you need not compile this program yourself.
As explained in COMPILE.DOC, 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. 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 system. If it
doesn't work for you, we probably cannot tell you why.
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 POV-
Ray source code in other programs.
2.0 SUPPORTED COMPILERS
POV-Ray 3.0 must be compiled using a 32-bit protected mode, flat memory
model compiler for 386 CPU or better. It cannot be compiled as a real mode
or 286 protected mode program. It cannot be compiled in small, medium,
large or even huge memory models. This limits your choices in what
compiler you may use.
We have successfully compiled the program on three such compilers and have
provided the necessary makefiles and configuration to use those compilers.
They are:
1) Watcom C/C++ version 10.6 by Powersoft. The Watcom compiler is the
compiler used for our officially distributed version. It compiles
reasonably fast and produces the fastest, most stable executables we have
tried. The major drawback is that the DOS4GW dos extender that comes with
it is limited to 16 meg of physical memory and 16 meg virtual memory
however other unlimited dos extenders may be purchased. Many large
triangle mesh or recursive object scenes can exceed this limit. Although
we use the current version 10.6, we have successfully used 10.0a, 10.5 and
10.5a versions. See CMPL_WAT.DOC & USER_WAT.DOC in the SOURCE\MSDOS\WATCOM
directory for further details.
2) BC++ 4.52 with the Dos Power Pack by Borland Intl. The Borland compiler
is the fastest compiling C compiler we have ever seen. The resulting
executable is not as fast as Watcom but the dos extender has no memory
limits. BC++ alone, is NOT sufficient to compile a 32-bit dos program.
You MUST have an add-on package called the Dos Power Pack. The Dos Power
Pack works with versions from BC++ 4.02 through BC++ 4.52 and we have
successfully compiled. The current Borland release BC++ 5.0 does not
officially support the Dos Power Pack. The last time we checked, the Dos
Power Pack was no longer for sale. We have been told that it is still
possible to use the command-line 5.0 compiler with an old Dos Power Pack to
create 32-bit Dos programs but we have not personally verified this. See
CMPL_BOR.DOC & USER_BOR.DOC in the SOURCE\MSDOS\BORLAND directory for
further details.
3) DJGPP 2.0 Gnu C/C++ Compiler for MS-Dos. The DJGPP compiler is a
freeware compiler available on the internet at the Simtel archives and at
www.djgpp.com. It is an MS-Dos port of the famous freeware Unix Gnu
compiler supported by the Free Software Foundation. The compiling speed is
somewhat slow but executable speed is usually reasonable. We had good
results compiling POV-Ray under DJGPP version 1.xx but our recent port to
DJGPP 2.0 is less promising. We can only run with all optimizations off.
Even then, we experience floating point exceptions and there are problems
with the current linker. We are hopeful these problems will be resolved in
future releases. Our current POV-Ray code supports only DJGPP 2.0. See
CMPL_DJG.DOC & USER_DJG.DOC in the SOURCE\MSDOS\DJGPP directory for further
details.
Each of the three compiler specific directories contains makefiles and
linkage files for that particular compiler. They are designed to be used
with the command-line versions of the compilers with an appropriate "make"
utility. We do not supply IDE project files but you should be able to
create one yourself.
The makefiles are designed to be run from the compiler-specific directory.
All OBJ files and the resulting executable will be created in that
compiler-specific directory. Files in the SOURCE\MSDOS and SOURCE
directories are referenced backwards up the directory tree. For example
POVRAY.C is referenced as ..\..\POVRAY.C rather than
C:\POVRAY3\SOURCE\POVRAY.C so that you can install the source on any drive
or any root directory and not need to edit the makefiles. It also keeps
OBJ and EXE files for each compiler separate. This was useful for team
members who used more than one compiler.
3.0 LIBRARIES
POV-Ray for MS-Dos uses four pre-compiled libraries from outside sources in
addition to any standard libraries that come with the C compiler. They are
LIBPNG.LIB, ZLIB.LIB, PMODE.LIB & ZTIMER.LIB (Note DJGPP uses "file.A"
extensions rather than "file.LIB". Pre-compiled, ready-to-link versions of
these libraries are provided in each compiler-specific directory. Although
the file names for the Watcom and Borland versions are the same, these
libraries are compiler-specific and should not get mixed up.
The full C source for LIBPNG & ZLIB are provided in the SOURCE\LIBPNG and
SOURCE\ZLIB directories. Although you will probably never need to do so,
you can re-compile both of them by running the BUILDPNG.BAT file. ZLIB is
a data compression and decompression library required by LIBPNG. LIBPNG
reads and writes PNG (Portable Network Graphics) image files.
The PMODE and ZTIMER libraries are freeware libraries created by Scitech
Software. ZTIMER is a timer routine used by POV-Ray's histogram profiling
feature. PMODE is used to call MS-Dos interrupts, and to access real mode
memory and physical memory-mapped devices such as video memory. Various
compilers support these functions in differently. The PMODE library
provides a portable compile-independent interface that greatly simplifies
the job of protected mode access to real mode assets.
They are created from a combination of both C and assembler code. The
Borland assembler TASM 4.0 or greater is required to assembly the code even
if you are using Watcom or DJGPP. In addition DJGPP requires a special
utility to translate OBJ files from TASM into files that DJGPP can use.
Although we supply the source code for these libraries in
SOURCE\MSDOS\PMODE in SOURCE\MSDOS\ZTIMER, we do not have these source
files as organized as ZLIB or LIBPNG. We recommend you stick with the pre-
compiled version.
The files vesavbe.c, vesavbe.h, console.c, console.h, debug.h, ztimer.h and
pmode.h in the SOURCE\MSDOS directory are also the work of Scitech
Software. See SCITECH.DOC for details on where to get updated versions of
these libraries or versions for other compilers.
4.0 CONCLUSION
