*******************************************************************************
**     Building VirtualGL
*******************************************************************************


==================
Build Requirements
==================


All Systems
-----------

-- CMake (http://www.cmake.org) v2.8 or later

-- If building SSL support:
   * OpenSSL (http://www.OpenSSL.org) -- see "Building SSL Support" below

-- libjpeg-turbo SDK v1.1.1 or later
   * The libjpeg-turbo SDK binary packages can be downloaded from the "Files"
     area of http://sourceforge.net/projects/libjpeg-turbo/
   * The VirtualGL build system will search for the TurboJPEG/OSS header and
     library under /opt/libjpeg-turbo on Unix (including Cygwin) or
     c:\libjpeg-turbo[64] on Windows, but you can override this by setting the
     TJPEG_INCLUDE_DIR CMake variable to the directory containing turbojpeg.h
     and the TJPEG_LIBRARY CMake variable to the full path of the TurboJPEG/OSS
     library against which you want to link.


Linux or FreeBSD
----------------

-- GCC and G++

-- X11 and OpenGL development libraries:
   * libX11, libXext, libGL, libGLU, and (if you wish to enable X Video
     support) libXv


Mac
---

-- Xcode Tools
   * Available on the OS X install discs or from:
     http://developer.apple.com/tools/xcode
   * With earlier versions of Xcode, you will need to specify a custom install
     and select the following packages:
     gcc 3.x (or later), X11 SDK, OpenGL SDK, Mac OS X SDK
   * With Xcode 3.x and later, you can simply check "Unix Development Support"


Windows
-------

-- Microsoft Visual C++ 2005 or later

   If you don't already have Visual C++, then the easiest way to get it is by
   installing the Windows SDK:

   http://msdn.microsoft.com/en-us/windows/bb980924.aspx

   The Windows SDK includes both 32-bit and 64-bit Visual C++ compilers and
   everything necessary to build VirtualGL.

   * For 32-bit builds, you can also use Microsoft Visual C++ Express
     Edition.  Visual C++ Express Edition is a free download.
   * If you intend to build VirtualGL from the command line, then add the
     appropriate compiler and SDK directories to the INCLUDE, LIB, and PATH
     environment variables.  This is generally accomplished by executing
     vcvars32.bat or vcvars64.bat and SetEnv.cmd.  vcvars32.bat and
     vcvars64.bat are part of Visual C++ and are located in the same directory
     as the compiler.  SetEnv.cmd is part of the Windows SDK.  You can pass
     optional arguments to SetEnv.cmd to specify a 32-bit or 64-bit build
     environment.

-- OpenText Exceed XDK v8 or later

   * If you plan to build VirtualGL from the command line, add the XDK include
     path (for instance,
     c:\Program Files\Hummingbird\Connectivity\13.00\Exceed\XDK\include)
     to the system or user INCLUDE environment variable prior to building
     VirtualGL.  If you plan to use the Visual Studio IDE, then add this same
     path to the "Include Directories" property in Visual Studio.
   * If you plan to build VirtualGL from the command line, add the XDK library
     path (for instance,
     c:\Program Files\Hummingbird\Connectivity\13.00\Exceed\XDK\lib)
     to the system or user LIB environment variable prior to building
     VirtualGL.  If you plan to use the Visual Studio IDE, then add this same
     path to the "Include Directories" property in Visual Studio.


Cygwin
------

-- GCC and G++

-- X11 and OpenGL development libraries:
   * libX11, libXext, libGL, and libGLU


=======================================
32-bit VirtualGL Builds on 64-bit Linux
=======================================

In order to run 32-bit OpenGL applications using VirtualGL on a 64-bit Linux
platform, it is necessary to build both 32-bit and 64-bit versions of the
VirtualGL server components.  However, not all x86-64 Linux systems contain the
32-bit libraries necessary to build a 32-bit version of VirtualGL.  To build
32-bit VirtualGL components on an x86-64 Linux system, you will need, at
minimum, the following 32-bit libraries:

-- glibc and libstdc++ development libraries
   * On Ubuntu, these can both be obtained by installing the "g++-multilib"
     package

-- X11 and OpenGL development libraries
   * libX11, libXext, libGL, libGLU, and (unless you wish to disable X Video
     support) libXv
   * Ubuntu 10 and 11 ship these libraries in the "ia32-libs" package.
     On older releases, you may have to use getlibs
     (http://explore-ubuntu.blogspot.com/2010/04/getlibs.html) to
     install the 32-bit X11 dev. kit:
     > sudo getlibs -p libx11-dev libxext-dev libxau-dev libglu1-mesa-dev libxv-dev
   * Ubuntu 12 is currently a special case.  Because of the transition to
     MultiArch, ia32-libs is no longer used to install development stubs for
     32-bit libraries.  The accepted way to install these is to install the
     i386 version of the needed dev. kit.  However, unfortunately, some of the
     dev. kits conflict when you attempt to install 64-bit and 32-bit versions
     simultaneously.  The best solution at the moment is to install either the
     32-bit dev. kits:

     > sudo apt-get install libglu1-mesa-dev:i386 libxv-dev:i386

     or the 64-bit dev. kits:

     > sudo apt-get install libglu1-mesa-dev libxv-dev

     depending on which type of build you need to do.

-- Out of the box, Red Hat Enterprise Linux 6 does not contain 32-bit libraries
   at all.  See

   http://www.virtualgl.org/Documentation/RHEL6

   for instructions on how to install 32-bit libraries on that platform.

If for some reason your preferred 64-bit Linux distribution does not contain
one or more of the necessary 32-bit prerequisites, then:

  (1) Complain to your distribution vendor.
  (2) All x86-64 distributions of Linux have a corresponding 32-bit-only
      distribution, usually released on a separate set of discs.  On those
      discs, you should be able to find the 32-bit versions of the X11 dev. kit
      and the glibc dev. kit to match the 64-bit versions that are already
      installed on your system.  You may have to use 'rpm --force' to force the
      install of the 32-bit development packages, since they might contain
      some of the same files as the 64-bit development packages that are
      already installed.  On Debian-based systems, you will need to use
      'dpkg --force-architecture' to force the installation of i386 packages
      on an amd64 system.  See item (1) above.


==================
Out-of-Tree Builds
==================

Binary objects, libraries, and executables are generated in the same directory
from which CMake was executed (the "binary directory"), and this directory need
not necessarily be the same as the VirtualGL source directory.  You can create
multiple independent binary directories, in which different versions of
VirtualGL can be built from the same source tree using different compilers or
settings.  In the sections below, {build_directory} refers to the binary
directory, whereas {source_directory} refers to the VirtualGL source directory.
For in-tree builds, these directories are the same.


===============
Build Procedure
===============


Unix/Mac
--------

The following procedure will build the VirtualGL Client and, on Linux and other
Un*x variants (except OS X), the VirtualGL Server components.  On most 64-bit
systems (Solaris being a notable exception), this will build a 64-bit version
of VirtualGL.  See "Build Recipes" for specific instructions on how to build a
32-bit or 64-bit version of VirtualGL on systems that support both.

  cd {build_directory}
  cmake -G "Unix Makefiles" [additional CMake flags] {source_directory}
  make


Visual C++ (Command Line)
-------------------------

  cd {build_directory}
  cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release [additional CMake flags] {source_directory}
  nmake

This will build either a 32-bit or a 64-bit version of VirtualGL, depending
on which version of cl.exe is in the PATH.


Visual C++ (IDE)
----------------

Choose the appropriate CMake generator option for your version of Visual Studio
(run "cmake" with no arguments for a list of available generators.)  For
instance:

  cd {build_directory}
  cmake -G "Visual Studio 9 2008" [additional CMake flags] {source_directory}

You can then open ALL_BUILD.vcproj in Visual Studio and build one of the
configurations in that project ("Debug", "Release", etc.) to generate a full
build of VirtualGL.


===========
Debug Build
===========

Add "-DCMAKE_BUILD_TYPE=Debug" to the CMake command line.  Or, if building with
NMake, remove "-DCMAKE_BUILD_TYPE=Release" (Debug builds are the default with
NMake.)


===========================================
Building Secure Sockets Layer (SSL) Support
===========================================

If built with SSL support, VirtualGL can use OpenSSL to encrypt the traffic it
sends and receives via the VGL Transport.  This is only a marginally useful
feature, however, since VirtualGL can also tunnel the VGL Transport through
SSH.  To enable SSL support, set the VGL_USESSL CMake variable to 1.

In general, if you are building on a Unix-ish platform that has the OpenSSL
link libraries and include files installed in the standard system locations,
then the VirtualGL build system should detect the system version of OpenSSL
automatically and link against it.  However, this produces a version of
VirtualGL that depends on the OpenSSL dynamic libraries, and thus the VirtualGL
binaries are not necessarily portable.  On Windows platforms, there is no
system version of OpenSSL to link against, so it's a moot point.  Thus, to
build a fully portable, cross-compatible version of VirtualGL with SSL support,
it is necessary on most systems to link against the OpenSSL static libraries.
The following sections describe how to do that on various platforms.


Linux
-----

There is generally no sane way to statically link with OpenSSL on Linux without
building OpenSSL from source.  Some distributions of Linux ship with the
OpenSSL static libraries, but these usually depend on Kerberos, which
introduces a long list of dependencies, some of which aren't available in
static library form.  To build OpenSSL from source:

* Download the latest OpenSSL source tarball from http://www.OpenSSL.org
* Extract the tarball
* cd to the OpenSSL source directory and issue one of the following commands to
  configure the OpenSSL build:

  64-bit:
  ./Configure linux-x86_64 shared no-krb5 no-dso

  32-bit:
  ./Configure -m32 linux-generic32 shared no-krb5 no-dso

* make

You can then manipulate the OPENSSL_INCLUDE_DIR, OPENSSL_SSL_LIBRARIES, and
OPENSSL_CRYPTO_LIBRARIES CMake variables to link VirtualGL against your custom
OpenSSL build.  For instance, adding

  -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=~/openssl/include \
    -DOPENSSL_SSL_LIBRARIES=~/openssl/libssl.a \
    -DOPENSSL_CRYPTO_LIBRARIES=~/openssl/libcrypto.a

to the CMake command line will cause VirtualGL to be statically linked against
a custom build of OpenSSL that resides under ~/openssl.


Mac
---

Linking with the OpenSSL dynamic libraries is generally not a concern on OS X,
since Apple ships several versions of these in order to retain backward
compatibility with OS X 10.4 and later.  See the "Build Recipes" section for
instructions on how to build a backward-compatible version of VirtualGL for
OS X.


Solaris
-------

The easiest approach on Solaris is to install the OpenSSL development libraries
from OpenCSW (http://www.OpenCSW.org) or BlastWave (http://www.BlastWave.org).
You can then add one of the following to the CMake command line to statically
link VirtualGL with OpenSSL:

  64-bit:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=/opt/csw/include \
      -DOPENSSL_SSL_LIBRARIES=/opt/csw/lib/64/libssl.a \
      -DOPENSSL_CRYPTO_LIBRARIES=/opt/csw/lib/64/libcrypto.a

  32-bit:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=/opt/csw/include \
      -DOPENSSL_SSL_LIBRARIES=/opt/csw/lib/libssl.a \
      -DOPENSSL_CRYPTO_LIBRARIES=/opt/csw/lib/libcrypto.a


Windows
-------

The easiest approach on Windows is to install either Win32 OpenSSL or Win64
OpenSSL (http://www.slproweb.com/products/Win32OpenSSL.html).  You can then add
one of the following to the CMake command line to statically link VirtualGL
with OpenSSL:

  Win64 Release:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=c:\OpenSSL-Win64\include \
      -DLIB_EAY_RELEASE=c:\OpenSSL-Win64\lib\VC\libeay32MT.lib \
      -DSSL_EAY_RELEASE=c:\OpenSSL-Win64\lib\VC\ssleay32MT.lib

  Win64 Debug:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=c:\OpenSSL-Win64\include \
      -DLIB_EAY_DEBUG=c:\OpenSSL-Win64\lib\VC\libeay32MTd.lib \
      -DSSL_EAY_DEBUG=c:\OpenSSL-Win64\lib\VC\ssleay32MTd.lib

  Win32 Release:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=c:\OpenSSL-Win32\include \
      -DLIB_EAY_RELEASE=c:\OpenSSL-Win32\lib\VC\libeay32MT.lib \
      -DSSL_EAY_RELEASE=c:\OpenSSL-Win32\lib\VC\ssleay32MT.lib

  Win32 Debug:

    -DVGL_USESSL=1 -DOPENSSL_INCLUDE_DIR=c:\OpenSSL-Win32\include \
      -DLIB_EAY_DEBUG=c:\OpenSSL-Win32\lib\VC\libeay32MTd.lib \
      -DSSL_EAY_DEBUG=c:\OpenSSL-Win32\lib\VC\ssleay32MTd.lib


=============
Build Recipes
=============


32-bit Build on 64-bit Linux/Unix (including OS X)
--------------------------------------------------

Use export/setenv to set the following environment variables before running
CMake:

  CFLAGS=-m32
  CXXFLAGS=-m32
  LDFLAGS=-m32


64-bit Backward-Compatible Build on 64-bit OS X
-----------------------------------------------

Add

  -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.5.sdk \
    -DCMAKE_OSX_DEPLOYMENT_TARGET=10.5 

to the CMake command line.  The OS X 10.5 SDK must be installed.


32-bit Backward-Compatible Build on 64-bit OS X
-----------------------------------------------

Use export/setenv to set the following environment variables:

  CC=gcc-4.0
  CXX=g++-4.0
  CFLAGS=-m32
  CXXFLAGS=-m32
  LDFLAGS=-m32

and add

  -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.4u.sdk \
    -DCMAKE_OSX_DEPLOYMENT_TARGET=10.4

to the CMake command line.  The OS X 10.4 SDK must be installed.


64-bit Build on Solaris
-----------------------

Use export/setenv to set the following environment variables before running
CMake:

  CFLAGS=-m64
  CXXFLAGS=-m64
  LDFLAGS=-m64


Compilers Other Than GCC
------------------------

On Un*x systems, prior to running CMake, you can set the CC environment
variable to the command used to invoke the C compiler and the CXX environment
variable to the command used to invoke the C++ compiler.


*******************************************************************************
**     Advanced CMake Options
*******************************************************************************

To list and configure other CMake options not specifically mentioned in this
guide, run

  ccmake {source_directory}

or

  cmake-gui {source_directory}

after initially configuring the build.  CCMake is a text-based interactive
version of CMake, and CMake-GUI is a GUI version.  Both will display all
variables that are relevant to the VirtualGL build, their current values, and a
help string describing what they do.


*******************************************************************************
**     Installing VirtualGL
*******************************************************************************

You can use the build system to install VirtualGL into a directory of your
choosing.  To do this, add:

  -DCMAKE_INSTALL_PREFIX={install_directory}

to the CMake command line.  Then, you can run 'make install' or 'nmake install'
(or build the "install" target in the Visual Studio IDE) to build and install
VirtualGL.  Running 'make uninstall' or 'nmake uninstall' (or building the
"uninstall" target in the Visual Studio IDE) will uninstall VirtualGL.

If you don't specify CMAKE_INSTALL_PREFIX, then the default is
c:\Program Files\VirtualGL on Windows and /opt/VirtualGL on Unix.


*******************************************************************************
**     Creating Release Packages
*******************************************************************************

The following commands can be used to create various types of release packages:


====
Unix
====

make rpm

  Create Red Hat-style binary RPM package.  Requires RPM v4 or later.

make deb

  Create Debian-style binary package.  Requires dpkg.

make dmg

  Create Macintosh package/disk image.  This requires the PackageMaker
  application, which the build system looks for in
  /Developer/Applications/Utilities by default.  You can override this by
  setting the PACKAGEMAKER_PATH CMake variable.

make udmg

  On 64-bit OS X systems, this creates a version of the Macintosh package and
  disk image that contains universal i386/x86-64 binaries.  You should first
  configure a 32-bit out-of-tree build of VirtualGL, then configure a 64-bit
  out-of-tree build, then run 'make udmg' from the 64-bit build directory.  The
  build system will look for the 32-bit build under {source_directory}/osxx86
  by default, but you can override this by setting the VGL_32BIT_BUILD CMake
  variable.

make cygwinpkg

  Build a Cygwin binary package.


=======
Windows
=======

If using NMake:

  cd {build_directory}
  nmake installer

If using the Visual Studio IDE, build the "installer" project.

The installer package (VirtualGL[64]-{version}-exceed.exe) will be located
under {build_directory}.  If building using the Visual Studio IDE, then the
installer package will be located in a subdirectory with the same name as the
configuration you built (such as {build_directory}\Debug\ or
{build_directory}\Release\).

Building a Windows installer requires the Nullsoft Install System
(http://nsis.sourceforge.net/).  makensis.exe should be in your PATH.
