Move BUILDING.txt to the top of the tree, since it contains general build instructions that are useful to all users, not just users who are using the packaging tools under release/

git-svn-id: svn://svn.code.sf.net/p/tigervnc/code/trunk@4286 3789f03b-4d11-0410-bbf8-ca57d06f2519

1 files changed, 531 insertions, 0 deletions

diff --git a/BUILDING.txt b/BUILDING.txt
new file mode 100644
index 00000000..7ab891b9
--- /dev/null
+++ b/BUILDING.txt
@@ -0,0 +1,531 @@
+*******************************************************************************
+**     Building on Unix Platforms (including Cygwin)
+*******************************************************************************
+
+
+==================
+Build Requirements
+==================
+
+-- autoconf 2.57 or later
+-- automake 1.7 or later
+-- libtool 1.4 or later
+
+-- NASM
+   * 0.98 or later is required for a 32-bit build
+   * NASM 2.05 or later is required for a 64-bit build
+   * NASM 2.07 or later is required for a 64-bit build on OS X.  This can be
+     obtained from MacPorts (http://www.macports.org/).
+
+   The NASM 2.05 RPMs do not work on older Linux systems, such as Red Hat
+   Enterprise Linux 4.  On such systems, you can easily build and install NASM
+   2.05 from the source RPM by executing the following as root:
+
+     ARCH=`uname -m`
+     wget http://www.nasm.us/pub/nasm/releasebuilds/2.05.01/nasm-2.05.01-1.src.rpm
+     rpmbuild --rebuild nasm-2.05.01-1.src.rpm
+     rpm -Uvh /usr/src/redhat/RPMS/$ARCH/nasm-2.05.01-1.$ARCH.rpm
+
+   NOTE: NASM build will fail if texinfo is not installed.
+
+-- GCC v4.1 or later recommended for best performance
+
+-- X11 development kit
+
+-- If building Xvnc:
+   * Python v2.3 or later
+   * zlib v1.2 or later
+   * OpenSSL v0.9.7 or later
+
+-- If building VeNCrypt support:
+   * GnuTLS and its dependencies (libgcrypt, libtasn1, libgpg-error)
+
+
+==================
+Out-of-Tree Builds
+==================
+
+Binary objects, libraries, and executables are generated in the same directory
+from which configure was executed (the "binary directory"), and this directory
+need not necessarily be the same as the TigerVNC source directory.  You can
+create multiple independent binary directories, in which different versions of
+TigerVNC 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 TigerVNC source directory.
+For in-tree builds, these directories are the same.
+
+
+=================
+Building TigerVNC
+=================
+
+The following procedure will build the TigerVNC viewer on Linux and Unix
+systems.  On 64-bit systems, this may build a 32-bit version of TigerVNC,
+depending on the default autotools configuration for your system.  See below
+for specific build instructions for 64-bit systems.
+
+  cd {source_directory}
+  autoreconf -fiv
+  cd {build_directory}
+  sh {source_directory}/configure [additional configure flags]
+  make
+
+NOTE: Running autoreconf in the source directory is only necessary if building
+TigerVNC from the SVN repository.
+
+Building the TigerVNC server (Xvnc) is a bit trickier.  On newer systems, such
+as Fedora, Xvnc is typically built to use the X11 shared libraries provided
+with the system.  This requires a system with Xorg 7.4 or later, however.
+Systems with older versions of Xorg must build a "legacy-friendly" version of
+the TigerVNC server.  This is accomplished by downloading and building the
+more recent Xorg modules in a local directory and then building Xvnc such that
+it links against the local build of these libraries, not the X11 libraries
+installed on the system.  The "build-xorg" script in the TigerVNC source
+distribution automates this process.
+
+The following procedure will build both the TigerVNC viewer and a
+"legacy-friendly" version of the TigerVNC server:
+
+  cd {build_directory}
+  sh {source_directory}/unix/build-xorg init -version 7.4
+  sh {source_directory}/unix/build-xorg build -version 7.4 [-static] [additional configure flags]
+
+Passing an argument of "-static" to the build command line will generate a
+version of Xvnc that has no external dependencies on the X11 shared libraries
+or any other distribution-specific shared libraries.  This version of Xvnc
+should be transportable across multiple O/S distributions.  The legacy-friendly
+build should work on Red Hat Enterprise 4, its contemporaries, and later
+systems.  It probably will not work on older systems.  It has not been tested
+on non-Linux systems (yet).
+
+build-xorg can also be used to rebuild just the TigerVNC server and viewer,
+once the X11 modules and other dependencies have been built the first time.
+This is convenient for testing changes that just apply to the TigerVNC source
+code.  To accomplish this, run:
+
+  sh {source_directory}/unix/build-xorg rebuild [additional make flags]
+
+For instance,
+
+  sh {source_directory}/unix/build-xorg rebuild clean
+
+will clean both the Xvnc and vncviewer builds without destroying any of the
+build configuration or module dependencies.
+
+
+=========================
+Building VeNCrypt support
+=========================
+
+Building VeNCrypt (the TigerVNC security and authentication extensions)
+requires GnuTLS, which is not pre-installed on all platforms.  In general, if
+you are building on a Unix-ish platform that has the GnuTLS libraries and
+include files installed in the standard system locations, then the TigerVNC
+build system should detect the system version of GnuTLS automatically and link
+against it.  However, this produces a version of TigerVNC that depends on the
+GnuTLS dynamic libraries, and thus the TigerVNC binaries are not portable.
+
+To build a fully portable, cross-compatible version of TigerVNC with VeNCrypt
+support, it is necessary to link against the GnuTLS static library (as well
+as the static libraries of its dependencies.)  If you are lucky enough, your
+O/S distribution may include pre-packaged versions of these static libraries.
+Otherwise, it will probably be necessary to build GnuTLS, libgcrypt, libtasn1,
+and libgpg-error from source.
+
+You can manipulate the GNUTLS_CFLAGS and GNUTLS_LDFLAGS configure variables to
+accommodate a custom build of GnuTLS that is installed in a non-system
+directory.  For instance, adding
+
+  GNUTLS_CFLAGS=-I/opt/gnutls/include \
+    GNUTLS_LDFLAGS='/opt/gnutls/lib/libgnutls.a /opt/gnutls/lib/libgcrypt.a \
+    /opt/gnutls/lib/libgpg-error.a /opt/gnutls/lib/libtasn1.a' \
+    --with-included-zlib
+
+to the configure or 'build-xorg build' command line will cause TigerVNC to be
+statically linked against a custom installation of GnuTLS that resides under
+/opt/gnutls.  GnuTLS depends on zlib, so specifying --with-included-zlib will
+satisfy that dependency using TigerVNC's in-tree version of zlib, which
+prevents TigerVNC from depending on the libz dynamic library.
+
+
+==================
+Unix Build Recipes
+==================
+
+
+32-bit Build on 64-bit Linux
+----------------------------
+
+Add
+
+  --host i686-pc-linux-gnu CFLAGS='-O3 -m32' CXXFLAGS='-O3 -m32' LDFLAGS=-m32
+
+to the configure or build command lines.
+
+
+64-bit Build on 64-bit OS X
+---------------------------
+
+Add
+
+  --host x86_64-apple-darwin NASM=/opt/local/bin/nasm
+
+to the configure command line.  NASM 2.07 or later from MacPorts must be
+installed.
+
+
+32-bit Build on 64-bit OS X
+---------------------------
+
+Add
+
+  CFLAGS='-O3 -m32' CXXFLAGS='-O3 -m32' LDFLAGS=-m32
+
+to the configure command line.
+
+
+64-bit Backward-Compatible Build on 64-bit OS X
+-----------------------------------------------
+
+Add
+
+  --host x86_64-apple-darwin NASM=/opt/local/bin/nasm \
+  CFLAGS='-isysroot /Developer/SDKs/MacOSX10.5.sdk \
+    -mmacosx-version-min=10.5 -O3' \
+    CXXFLAGS='-isysroot /Developer/SDKs/MacOSX10.5.sdk \
+    -mmacosx-version-min=10.5 -O3' \
+    LDFLAGS='-isysroot /Developer/SDKs/MacOSX10.5.sdk \
+    -mmacosx-version-min=10.5'
+
+to the configure command line.  The OS X 10.5 SDK, and NASM 2.07 or later from
+MacPorts, must be installed.
+
+
+32-bit Backward-Compatible Build on 64-bit OS X
+-----------------------------------------------
+
+Add
+
+  CC=gcc-4.0 CXX=g++-4.0 CFLAGS='-isysroot /Developer/SDKs/MacOSX10.4u.sdk \
+    -mmacosx-version-min=10.4 -O3 -m32' \
+    CXXFLAGS='-isysroot /Developer/SDKs/MacOSX10.4u.sdk \
+    -mmacosx-version-min=10.4 -O3 -m32' \
+    LDFLAGS='-isysroot /Developer/SDKs/MacOSX10.4u.sdk \
+    -mmacosx-version-min=10.4 -m32'
+
+to the configure command line.  The OS X 10.4 SDK must be installed.
+
+
+
+*******************************************************************************
+**     Building on Windows (Visual C++ or MinGW)
+*******************************************************************************
+
+
+==================
+Build Requirements
+==================
+
+-- CMake (http://www.cmake.org) v2.6 or later
+
+-- 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 TigerVNC.
+
+   * 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 TigerVNC 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.
+
+... OR ...
+
+-- MinGW
+
+   GCC v4.1 or later recommended for best performance
+
+-- NASM (http://www.nasm.us/) 0.98 or later (NASM 2.05 or later is required for
+   a 64-bit build)
+
+-- Inno Setup (needed to build the TigerVNC installer)
+   Inno Setup can be downloaded from http://www.jrsoftware.org/isinfo.php.
+   You also need the Inno Setup Preprocessor, which is available in the
+   Inno Setup QuickStart Pack.
+
+   Add the directory containing iscc.exe (for instance, 
+   C:\Program Files\Inno Setup 5) to the system or user PATH environment
+   variable prior to building TigerVNC.
+
+-- If building VeNCrypt support:
+   * GnuTLS and its dependencies (libgcrypt, libtasn1, libgpg-error)
+
+
+==================
+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 TigerVNC source directory.  You can create
+multiple independent binary directories, in which different versions of
+TigerVNC 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 TigerVNC source directory.
+For in-tree builds, these directories are the same.
+
+
+=================
+Building TigerVNC
+=================
+
+
+Visual C++ (Command Line)
+-------------------------
+
+  cd {build_directory}
+  cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release {source_directory}
+  nmake
+
+This will build either a 32-bit or a 64-bit version of TigerVNC, 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" {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 TigerVNC.
+
+
+MinGW
+-----
+
+  cd {build_directory}
+  cmake -G "MSYS Makefiles" {source_directory}
+  make
+
+This will generate only vncviewer.  Currently, Visual C++ must be used to build
+WinVNC.
+
+
+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.)
+
+
+Self-Contained MinGW Build
+--------------------------
+
+If TigerVNC is built using MinGW, then it may depend on the MinGW libgcc DLL.
+To eliminate this dependency, add
+
+  -DCMAKE_C_FLAGS=-static-libgcc -DCMAKE_CXX_FLAGS=-static-libgcc
+
+to the cmake command line.
+
+
+=========================
+Building VeNCrypt support
+=========================
+
+Building VeNCrypt (the TigerVNC security and authentication extensions)
+requires GnuTLS, which is not Microsoft-friendly.  There is generally no
+sane way to build GnuTLS and its dependencies using Visual C++.  Those with
+a lot of time on their hands can build the GnuTLS DLLs using MinGW (or download
+32-bit versions of these from the link below), generate Visual C++ import
+libraries from the DLLs, then link TigerVNC against the Visual C++ import
+libraries.  However, this creates a version of TigerVNC that depends on
+the GnuTLS DLLs.  The TigerVNC packaging system currently is not designed to
+handle DLL dependencies, so really the only way to build and package a
+self-contained, VeNCrypt-enabled version of TigerVNC for Windows is to use
+MinGW and the static GnuTLS libraries.  The use of MinGW means that only the
+viewer can be built, not the server.
+
+An installer containing the GnuTLS header files, as well as static and dynamic
+link libraries for 32-bit MinGW, is available from the following site:
+
+http://josefsson.org/gnutls4win/
+
+Whether you choose to use the above installer or build GnuTLS from source,
+make sure that you install the libraries and headers into a pathname that
+doesn't contain spaces (the installer will try to install under
+c:\Program Files unless you tell it otherwise.)  If the GnuTLS include path
+contains spaces, then the MinGW resource compiler will barf.
+
+You can manipulate the GNUTLS_INCLUDE_DIR and GNUTLS_LIBRARY cmake variables to
+specify the directory under which you installed GnuTLS.  For instance, adding
+
+  -DGNUTLS_INCLUDE_DIR=/c/gnutls/include \
+    -DGNUTLS_LIBRARY='/c/gnutls/lib/libgnutls.a;/c/gnutls/lib/libgcrypt.a;/c/gnutls/lib/libtasn1.a;/c/gnutls/lib/libgpg-error.a'
+
+to the cmake command line when using MinGW will cause TigerVNC to be statically
+linked against an installation of GnuTLS that resides under c:\gnutls.
+
+
+===================
+Installing TigerVNC
+===================
+
+You can use the build system to install TigerVNC into a directory of your
+choosing (as opposed to creating an installer.)  To do this, add:
+
+  -DCMAKE_INSTALL_PREFIX={install_directory}
+
+to the cmake command line.
+
+For example,
+
+  cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_INSTALL_PREFIX=c:\TigerVNC {source_directory}
+  nmake install
+
+If you don't specify CMAKE_INSTALL_PREFIX, then the default is
+c:\Program Files\TigerVNC.
+
+
+=====================
+Windows Build Recipes
+=====================
+
+
+64-bit MinGW Build on Cygwin
+----------------------------
+
+  cd {build_directory}
+  CC=/usr/bin/x86_64-w64-mingw32-gcc CXX=/usr/bin/x86_64-w64-mingw32-g++ \
+    RC=/usr/bin/x86_64-w64-mingw32-windres \
+    cmake -G "Unix Makefiles" -DCMAKE_SYSTEM_NAME=Windows \
+    -DCMAKE_AR=/usr/bin/x86_64-w64-mingw32-ar \
+    -DCMAKE_RANLIB=/usr/bin/x86_64-w64-mingw32-ranlib {source_directory}
+  make
+
+This produces a 64-bit build of TigerVNC that does not depend on cygwin1.dll or
+other Cygwin DLL's.  The mingw64-x86_64-gcc-core and mingw64-x86_64-gcc-g++
+packages (and their dependencies) must be installed.
+
+
+32-bit MinGW Build on Cygwin
+----------------------------
+
+  cd {build_directory}
+  CC=/usr/bin/i686-w64-mingw32-gcc CXX=/usr/bin/i686-w64-mingw32-g++ \
+    RC=/usr/bin/i686-w64-mingw32-windres \
+    cmake -G "Unix Makefiles" -DCMAKE_SYSTEM_NAME=Windows \
+    -DDCMAKE_AR=/usr/bin/i686-w64-mingw32-ar \
+    -DCMAKE_RANLIB=/usr/bin/i686-w64-mingw32-ranlib {source_directory}
+  make
+
+This produces a 32-bit build of TigerVNC that does not depend on cygwin1.dll or
+other Cygwin DLL's.  The mingw64-i686-gcc-core and mingw64-i686-gcc-g++
+packages (and their dependencies) must be installed.
+
+
+MinGW-w64 Build on Windows
+--------------------------
+
+This produces a 64-bit build of TigerVNC using the "native" MinGW-w64 toolchain
+(which is faster than the Cygwin version):
+
+  cd {build_directory}
+  CC={mingw-w64_binary_path}/x86_64-w64-mingw32-gcc \
+    CXX={mingw-w64_binary_path}/x86_64-w64-mingw32-g++ \
+    RC={mingw-w64_binary_path}/x86_64-w64-mingw32-windres \
+    cmake -G "MSYS Makefiles" \
+    -DCMAKE_AR={mingw-w64_binary_path}/x86_64-w64-mingw32-ar \
+    -DCMAKE_RANLIB={mingw-w64_binary_path}/x86_64-w64-mingw32-ranlib \
+    {source_directory}
+  make
+
+
+MinGW Build on Linux
+--------------------
+
+  cd {build_directory}
+  CC={mingw_binary_path}/i386-mingw32-gcc \
+    CXX={mingw_binary_path}/i386-mingw32-g++ \
+    RC={mingw_binary_path}/i386-mingw32-windres \
+    cmake -G "Unix Makefiles" -DCMAKE_SYSTEM_NAME=Windows \
+    -DCMAKE_AR={mingw_binary_path}/i386-mingw32-ar \
+    -DCMAKE_RANLIB={mingw_binary_path}/i386-mingw32-ranlib \
+    {source_directory}
+  make
+
+
+*******************************************************************************
+**     Creating Release Packages
+*******************************************************************************
+
+The following commands can be used to create various types of release packages:
+
+
+Unix
+----
+
+make tarball
+
+  Create a binary tarball containing the TigerVNC Viewer
+
+make servertarball
+
+  Create a binary tarball containing both the TigerVNC Server and Viewer
+
+make dmg
+
+  Create Macintosh package/disk image.  This requires the PackageMaker
+  application, which must be installed in /Developer/Applications/Utilities.
+
+make udmg [BUILDDIR32={32-bit build directory}]
+
+  On 64-bit OS X systems, this creates a version of the Macintosh package and
+  disk image which contains universal i386/x86-64 binaries.  You should first
+  configure a 32-bit out-of-tree build of TigerVNC, 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 BUILDDIR32 variable on
+  the make command line as shown above.  Either the 64-bit or 32-bit build can
+  be configured to be backward-compatible by using the instructions in the
+  "Unix Build Recipes" section.
+
+
+Windows
+-------
+
+If using NMake:
+
+  cd {build_directory}
+  nmake installer
+
+If using MinGW:
+
+  cd {build_directory}
+  make installer
+
+If using the Visual Studio IDE, build the "installer" project.
+
+The installer package (TigerVNC[64].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\).