install.txt

===============================================================================
POV-Ray v3.8 for UNIX/Linux - INSTALL file

Compiling and installing POV-Ray for Unix from sources.

Please report bugs via our GitHub issue tracker at
https://github.com/POV-Ray/povray/issues or to our forum at
news://news.povray.org/povray.unix/ or http://news.povray.org/povray.unix/
===============================================================================

+----------------------------------------------------------------------------+
| NOTE: If this file does not reside in the root directory of your POV-Ray   |
| source package, you have received a platform-neutral package. In that case |
| make sure to run the following command before you proceed:                 |
|                                                                            |
|   cd unix/ ; ./prebuild.sh ; cd ../                                        |
+----------------------------------------------------------------------------+

Table of contents
  1. Quick start
  2. Software requirements
  3. Configuring, building, and (un)installing POV-Ray
  4. Additional configure options
  5. Reporting bugs


==============
1. Quick start 
==============

This document gives basic and detailed instructions on how to compile and
install the source distribution of POV-Ray for UNIX/Linux.  It is intended to
those already familiar with compiling and installing programs on UNIX
platforms using the GNU build system.

Compiling and installing POV-Ray from sources is achieved by running the
usual 'configure' and 'make' commands.  For a system-wide installation:

  ./configure COMPILED_BY="your name <email@address or website>" [options]
  make check
  sudo make install

The COMPILED_BY argument to 'configure' should be filled
with your name and/or organization so that the generated binary can be
differentiated from official POV-Ray builds.

Additional configure options are described in section 4 of this document.

The 'make' command builds the program once it is configured.  The optional
'check' argument allows to run a short test render after POV-Ray is compiled
and before it is installed with 'make install' (see below).  Other options
are listed in section 3.

The last command in the example above installs POV-Ray under system-wide
directories and needs root privileges.  Installing as non-privileged user is
also possible; see section 3.1.  By default (i.e. as root), 'make install'
installs the following components (X.Y representing the first two fields of
the version number, e.g. for v3.8.1 this would be 3.8):
  povray binary (executable)              in /usr/local/bin
  data files (e.g. includes, scene files) in /usr/local/share/povray-X.Y
  documentation (text and html)           in /usr/local/share/doc/povray-X.Y
  configuration files (e.g. povray.conf)  in /usr/local/etc/povray/X.Y

The configuration files are also copied under the $HOME/.povray/X.Y directory
of the user (or root) who is doing the installation.  For further details
regarding those files, please read the instructions in README.unix and in
chapter 1 of the documentation.


========================
2. Software requirements
========================

Building POV-Ray on a UNIX platform requires a relatively modern C++ compiler,
the 'make' utility, a Bourne-compatible shell (e.g. bash), and several support
libraries.


2.1 Environment
    ===========

The build system must have:

- a modern C++ compiler which complies with the ISO C++11 standard as much as
  possible; for instance, the GNU GCC 5.x series, the Clang++ compiler version
  3.3 or above, and the Intel C++ compiler version 15.x or above.  They are
  available at:
  https://www.gnu.org/software/gcc/
  https://clang.llvm.org/
  https://software.intel.com/en-us/intel-compilers

- a working 'make' utility.  We strongly recommand to use GNU Make version 3.79
  or above.  Most GNU/Linux distribution should come with it.  Other platforms
  should install it before running configure.  GNU make can be found at:
  https://www.gnu.org/software/make/

- in the unlikely case you don't have a Bourne-compatible shell installed
  on your system or that the shell fails running POV-Ray's configure, it is
  recommanded to install GNU bash first.  Download it at:
  https://www.gnu.org/software/bash/


2.2 Required support libraries
    ==========================

The following external libraries are required to build a fully-featured
POV-Ray executable.  The Boost libraries are in general not installed on
most systems; several Linux distributions offer Boost through their package
repositeries -- please check out there first.  The image libraries are
relatively standard and should be automatically detected at least on most
Linux-based systems.  Be sure to have not only the run-time libraries but also
the development packages (header files in particular).

- Boost version 1.38 or above
  http://www.boost.org

- Zlib version 1.2.1 or above
  http://www.zlib.net

- LibPNG version 1.2.5 or above
  http://www.libpng.org

- LibJPEG version 6b or above
  http://www.ijg.org

- LibTIFF version 3.6.1 or above
  http://www.libtiff.org


2.3 Optional libraries
    ==================

These additional libraries are not mandatory to build POV-Ray but are
recommanded to generate a fully-featured POV-Ray executable.

- OpenEXR version 1.2 or above
  http://www.openexr.com

- SDL version 1.2 or above (used for the display preview)
  http://www.libsdl.org


2.4 Compatibility issues
    ====================

- Boost version 1.46 has been reported to be unstable on the Raspberry Pi 2.
  We recommend using Boost version 1.50 on this platform.

- Clang 3.4 using standard headers from gcc 4.6 is known to fail when using the
  default configure settings, reporting errors in a gcc header file named
  "math-finite.h" related to an identifier named "__extern_always_inline". Other
  version combinations may be affected as well. To work around this issue, use
  the configure option "CXXFLAGS=-fno-fast-math".

- When configured with "--disable-optimiz", linkage may fail in some cases,
  reporting undefined references related to "boost::gregorian::greg_month". To
  work around this issue, use the configure option "LDFLAGS=-lboost_date_time".


====================================================
3. Configuring, building, and (un)installing POV-Ray
====================================================

Configuring POV-Ray prepares the source package to generate an executable
for your particular machine and environment, and allows to change the default
paths where the program and its accompanying documentation and data files
are installed.  Using default installation directories requires to install
POV-Ray as root; this is the recommanded method if you have the choice.
Otherwise, POV-Ray can be installed anywhere one has write access to.


3.1 Building and installing
    =======================

3.1.1 As root
      -------

Configure POV-Ray for building and installing in standard directories:

  ./configure COMPILED_BY="your name <email@address or website>"
  make check         # build the program (binary) and run a test render
  sudo make install  # install everything in the /usr/local hierarchy

Here, these commands are run in the source directory of POV-Ray (but this is
not required, see section 3.1.3 below).  Note that the COMPILED_BY argument
is highly recommended. The 'check' target for 'make' may be omitted (no test render
is performed) in particular when building POV-Ray in batch.

The top Makefile generated by configure supports the following targets:

  make                   # build the program
  make check             # (build and) perform of short test render
  make clean             # clean all object files created by make
  make dist              # create distributions in .tar.gz & .tar.bz2 formats
  make dist-bzip2        # create distribution in .tar.bz2 format only
  make dist-gzip         # create distribution in .tar.gz format only
  make distcheck         # create and check (build) a distribution
  make distclean         # clean all files created by configure and make
  make install           # (build and) install the program, data, and docs
  make maintainer-clean  # caution: maintainers only (see Appendix A)
  make uninstall         # uninstall the program, data, and docs


3.1.2 As non-privileged user
      ----------------------

Without root priviledges, POV-Ray may be configured for installation under an
alternate hierarchy (e.g. /some/path) where one has write access to:

  ./configure --prefix=/some/path COMPILED_BY="your name <email@address>"
  make check install

The compilation, test render, and installation are invoqued using a single
'make' command.  All make targets listed in the section above are supported
when building POV-Ray as a regular user.  The test render may be skipped by
invoquing 'make install' instead.

For test purposes, POV-Ray may also be compiled without installing:

  ./configure COMPILED_BY="your name <email@address>"
  make check  # or 'make' to skip the test render

The povray executable is then located under the unix/ directory of the build
tree.  The program will keep searching for its configuration files under the
/usr/local hierarchy.  Note that compiling POV-Ray without installing is NOT
the recommanded way as it complicates the normal usage of the program (e.g.
to access POV-Ray's standard include files).


3.1.3 Building in-place or elsewhere
      ------------------------------

As presented above, the configure command is run from the source directory
of POV-Ray.  This is commonly referred to as building the package "in-place".
It is also possible (and often recommanded) to build the platform-specific
object files and executable in a different location.  The source tree thus
remains unchanged; this is useful especially in the case of read-only
distribution media (such as CDs).

For instance:

  mkdir -p /tmp/build/povray && cd /tmp/build/povray
  /path/to/configure COMPILED_BY="your name <email@address or website>" [options]
  make check install

Doing so creates a mirror of the POV-Ray source hierarchy (the build tree)
under the /tmp/build/povray directory.  All Makefiles and platform-specific
object files as well as the povray executable are created therein.


3.1.4 Cross-compiling POV-Ray
      -----------------------

Cross-compiling is the procedure by which a compiler running on one system
produces executables for another system.  Cross-compiling is important in
particular when the target system doesn't have a native set of compilation
tools.  Such a situation can happen for instance with embedded systems.

While the configure script for POV-Ray has been written with this concept
in mind, it has not been much tested in a cross-compiling environment.  Thus,
it is likely that the configure script will fail in this particular context.
If you have any experience in setting up a cross-compiling toolchain and
are able to test POV-Ray's configure with it, you are welcome to report
any success or patches via http://news.povray.org/povray.unix.


3.2 Uninstalling POV-Ray
    ====================

Regardless of the way POV-Ray was installed (as root or as non-privileged
user), the program, documentation, configuration and data files may be
uninstalled by running:

  make uninstall

in the main source directory of POV-Ray (or in the build directory where
the package has been configured, see section 4.1.3).  Only those files and
directories that were created by the installation procedure are removed.

Note that the uninstall procedure will only work when:
(a) you have write access to the directory where POV-Ray is installed, and
(b) POV-Ray has not been re-configured in between the 'make install' and
    'make uninstall' commands using another --prefix path.



===============================
4. Additional configure options
===============================

More options can be passed to POV-Ray's configure in order to tweak the
configuration process to specific needs.  The full list of supported options
is displayed with:

  ./configure --help

A shorter list is displayed with:

  ./configure --help=short


4.1 Generic configure options
    =========================

The list below describes the generic configure options that might be the most
relevant when building POV-Ray from sources:

--prefix=PREFIX
    allows to install the package under PREFIX.  You must have write access
    to the PREFIX directory.  The package is installed under the PREFIX/bin,
    PREFIX/etc, PREFIX/man, and PREFIX/share directories.

--with-x (default) or --without-x
    requests to use the X Window System (when possible) or not.  The
    X Window System allows to display the image POV-Ray is rendering in a
    seperate graphics window.  In order to use the X Window System, the
    POV-Ray binary is linked with the X11 library installed on your system.

CXX="C++ compiler (path)name"
CXXFLAGS="C++ compiler flags"
LDFLAGS="linker flags"
LIBS="additional libraries to link with"
    allows to specify which C++ compiler to use and the corresponding
    compiler and linker flags, instead of those detected by configure.
    For instance, if one wants to use the Intel C++ compiler instead of GCC
    and a safe optimization mode, one can type (the COMPILED_BY argument is
    omitted for clarity):

    % ./configure CXX=icpc CXXFLAGS="-O2"

    Here, the -O2 compiler option will not override the list of optimization
    options that configure will detect, but will be appended to this list
    (effectively replacing any -O option set previously).  In case no other
    optimization flags are wanted, use the --disable-optimiz option described
    in the next section.

    The LDFLAGS are meant to be used for the linker only.  Using this option
    should be useful in only very rare cases (if any).

    LIBS can be used to specify extra libraries for POV-Ray to link with,
    for example: LIBS=-ljunk or LIBS=/usr/local/lib/libjunk.a .  Using this
    option is usually not necessary, but might be useful in some very
    specific cases (see e.g. the --enable-static option below).


4.2 POV-Ray specific configure options
    ==================================

Additional POV-Ray specific options are:

--with-boost=DIR
    requests to find the Boost library in the DIR directory.  Boost 1.38 or
    above is mandatory to build POV-Ray.

--with-zlib=DIR or --without-zlib
    requests to find the ZLIB library in the DIR directory, where DIR is
    for instance /path/lib if ZLIB is /path/lib/libz.a (static form) or
    /path/lib/libz.so* (shared form).  On 64-bit systems, one may have to
    specify e.g. /path/lib64 instead.  The library headers are assumed to be
    located under the DIR/../include directory.  The --without-zlib option
    must be used together with NON_REDISTRIBUTABLE_BUILD (described below)
    in order to disable all POV-Ray features requiring this library.

--with-libpng=DIR or --without-libpng
    requests to find the PNG library in the DIR directory.  Further details
    are given in the related --with-zlib option above.

--with-libjpeg=DIR or --without-libjpeg
    requests to find the JPEG library in the DIR directory.  Further details
    are given in the related --with-zlib option above.

--with-libtiff=DIR or --without-libtiff 
    requests to find the TIFF library in the DIR directory.  Further details
    are given in the related --with-zlib option above.

--with-openexr=DIR or --without-openexr
    requests to find the OpenEXR library in the DIR directory, or to disable
    all POV-Ray features requiring this library.  DIR is e.g. /path/lib or
    /path/lib64.  The library headers are assumed to be located under the
    DIR/../include directory.

--with-libsdl=DIR or --without-libsdl
    requests to find the SDL library in the DIR directory, or to disable the
    preview display that uses this library.  DIR is for instance /path/lib
    or /path/lib64.  The library headers are assumed to be located under the
    DIR/../include directory.
    BETA: support for libSDL is required for the preview display but will
    become optional in the final source release.

--with-libmkl=DIR or --without-libmkl
    requests to use the Intel(R) Math Kernel Library (in directory DIR).
    BETA: this option is not properly working yet.

--with-cygwin-dll (default) or --without-cygwin-dll
    on the Cygwin platform, requests to link with the Cygwin DLL or not.
    The --without-cygwin-dll option allows to build an executable that
    should work on any Cygwin release.  It requires having the MinGW tools
    (Minimalist GNU for Windows, http://www.mingw.org) installed on your
    machine.  You might also use the --disable-shared option with it; see
    below.
    BETA: support for the cygwin environment hasn't been tested much.

--enable-watch-cursor
    enables the mouse pointer to show up as a watch cursor over the X Window
    display while rendering the image.

--enable-debug
    enables compiler debugging mode, i.e. ask the compiler to insert debug
    information within the executable that is useful for a debugger such as
    GDB (http://www.gnu.org/software/gdb).  The debugging mode dramatically
    increases the size of the generated executable and may also make it run
    slower.  It is therefore only meant for developers who want to experiment
    with the source code.  For best results, it is often recommended to
    disable all compiler optimizations; see below.

--enable-profile
    enables execution profiling, i.e. ask the compiler to generate run-time
    information that details in which parts of the code the program spends
    most of the CPU time.  This mode is targeted at developers who are willing
    to experiment with the code.  Using this mode requires debug information
    in the binary, so configure automatically turns on --enable-debug when
    --enable-profile is used.

--enable-static or --disable-shared
    disables linking with shared libraries, i.e. the POV-Ray executable will
    include all the machine code corresponding to its own source as well as
    that of the libraries it uses.  This option thus allows to generate a
    "static" binary that has no dependency to any system-specific library.
    Obviously, the size of the executable increases dramatically.  Using this
    option is preferred to redefining LDFLAGS, as configure will try to guess
    and test what option the linker really needs to link with the static
    (rather than the shared) libraries.

    Note: Some platforms (e.g. several GNU/Linux distributions, Solaris) can
    not statically link the X11 library with POV-Ray for various reasons, and
    might either disable support for the X Window display or cause a linkage
    error.  In the first situation, it might be required to pass additional
    libraries to the linker, e.g. LIBS=-ldl (the exact libraries can be
    guessed by inspecting the config.log file).  In the second situation,
    specify --without-x or do not use the present option.

--disable-optimiz
    disables all compiler optimizations, i.e. configure will not try to set
    any optimization flags suitable for your system.  This option is useful
    in particular together with specifying CXXFLAGS.

--disable-optimiz-arch
    disables only the architecture-specific compiler optimizations.  Generic
    optimization flags such as "-O3" are still detected and used.

--disable-pipe
    disables the use of pipes for communication between the various stages
    of compilation, and use temporary files instead.  This is slower, but on
    some systems pipes cannot work properly.

--disable-strip
    disables the compiler to strip all symbols from the object files, which
    results in a much larger executable.  This option is only useful when
    specifying the debugging and/or profiling mode described above.

--disable-io-restrictions
    disables all file input/output restrictions, meaning that POV-Ray will
    never try to check whether it is allowed or not to perform file and/or
    shellout operations.  For more details about I/O restrictions, please
    refer to chapter 1 of the documentation.  Use this option at your own
    risk.

COMPILED_BY="your name <email@address>"
    this option is highly recommended when configuring the source package.
    Please provide a valid contact information that will be included in the
    executable and displayed whenever POV-Ray (or a modified version) is
    started.  If not specified, this option will default to your login
	name and "<no contact address>".

NON_REDISTRIBUTABLE_BUILD=yes
    this option must be used in case one needs to build POV-Ray without
    support for a particular image library, i.e. together with any of the
    --without-zlib, --without-libpng, --without-libjpeg or --without-libtiff
    options.  Using this option means you acknowledge that the generated
    POV-Ray executable must *not* be redistributed.

C99_COMPATIBLE_RADIOSITY={1,2,3,4,5,6,7,8,9}
    adapts the POV-Ray radiosity code to use non-IEEE 754 floating point
    on machines that do not support this standard.  You must specify one
    of the possible values given above (e.g. C99_COMPATIBLE_RADIOSITY=2).
    Each value corresponds to a different implementation of certain basic
    operations. More details are given in the configcore.h
    source file.  On platforms where integer ('int') and single-precision
    floating-point ('float') numbers are not 32-bit, configure will try to
    determine automatically which function to use.


=================
5. Reporting bugs
=================

In case POV-Ray's configure or any part of the compilation/installation fails
on your system, please report the problem via http://news.povray.org/povray.unix.
Please try to be as specific as possible in describing the problem.

If POV-Ray was otherwise built but fails to run for some reason, please report
the output of the "povray --version" command (without quotes) along with the
description of the problem.