path: root/BUILDING.txt

*******************************************************************************
**     Building TigerVNC
*******************************************************************************


================================
Build requirements (all systems)
================================

-- CMake (http://www.cmake.org) v3.10 or later

-- gcc

Development kits for the following packages:

-- zlib

-- pixman

-- FLTK 1.3.3 or later

-- If building TLS support:
   * GnuTLS 3.x
   * See "Building TLS Support" below.

-- If building RSA-AES support:
   * Nettle 3.0 or later

-- If building native language support (NLS):
   * Gnu gettext 0.14.4 or later
   * See "Building Native Language Support" below.

-- libjpeg-turbo
   * "Normal" libjpegv6 is also supported, although it is not
     recommended as it is much slower.


=========================
Build requirements (Unix)
=========================

-- Non-Mac platforms:
   * Development kits for all standard X11 libraries
   * PAM

-- If building Xvnc/libvnc.so:
   * Xorg server source code, 1.20 or later
   * All build requirements Xorg imposes (see its documentation)
   * patch

-- If building x0vncserver with socket activation support:
   * libsystemd

-- Optional ffmpeg development kit support (libav)
   * You might have to enable additional repositories for this. E.g.,
     on RHEL, EPEL and RPMFusion (free + nonfree) need to be enabled.

-- If building vncpasswd with password quality check support:
   * libpwquality

============================
Build requirements (Windows)
============================

-- MinGW or MinGW-w64

-- 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.


=========================
Build requirements (Java)
=========================

-- Sun/Oracle JDK 1.7 or later or OpenJDK 7 or later

-- See "Building Java support" below.


==================
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
=================


Building the TigerVNC viewer on Unix/Mac systems
------------------------------------------------

The following procedure will build the TigerVNC viewer on Linux and Unix
systems.

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


Building the TigerVNC server on Unix/Linux systems
--------------------------------------------------

Building the TigerVNC server (Xvnc) is a bit trickier. Xvnc is typically built
to use the X11 shared libraries provided with the system.  The procedure for
this is system-specific, since it requires specifying such things as font
directories, but the general outline is as follows (this procedure assumes
that the viewer has already been built, per above.)

  > cd {build_directory}

    If performing an out-of-tree build:
  > cp -R {source_directory}/unix/xserver unix/

  > cp -R {xorg_source}/* unix/xserver/
    (NOTE: {xorg_source} is the directory containing the Xorg source for the
    machine on which you are building TigerVNC.  The most recent versions of
    Red Hat/CentOS/Fedora, for instance, provide an RPM called
    "xorg-x11-server-source", which installs the Xorg source under
    /usr/share/xorg-x11-server-source.)

  > cd unix/xserver/
  > patch -p1 < {source_directory}/unix/xserver{version}.patch
    (where {version} matches the X server version you are building, such as
    "120" for version 1.20.x.)
  > autoreconf -fiv

  > ./configure --with-pic --without-dtrace --disable-static --disable-dri \
      --disable-xinerama --disable-xvfb --disable-xnest --disable-xorg \
      --disable-dmx --disable-xwin --disable-xephyr --disable-kdrive \
      --disable-config-hal --disable-config-udev --disable-dri2 --enable-glx \
      --with-default-font-path="catalogue:/etc/X11/fontpath.d,built-ins" \
      --with-xkb-path=/usr/share/X11/xkb \
      --with-xkb-output=/var/lib/xkb \
      --with-xkb-bin-directory=/usr/bin \
      --with-serverconfig-path=/usr/lib64/xorg \
      {additional configure options}
    (NOTE: This is merely an example that works with Red Hat Enterprise/CentOS
    9 and recent Fedora releases.  You should customize it for your particular
    system.  In particular, it will be necessary to customize the XKB
    directory.)

    For a regular, in-tree build:
  > make TIGERVNC_SRCDIR={source_directory}
    If performing an out-of-tree build:
  > make TIGERVNC_SRCDIR={source_directory} TIGERVNC_BUILDDIR={build_directory}
    (NOTE: Use absolute paths for source_directory and build_directory)


Building the Windows TigerVNC viewer with MinGW
-----------------------------------------------

If building the Windows version of TigerVNC on a Windows build system, use
the following procedure.

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

If cross-compiling on a Unix/Linux system, then see the "Build Recipes" section
below.


Debug build
-----------

Add "-DCMAKE_BUILD_TYPE=Debug" to the CMake command line.


Portable (semi-static) build
----------------------------

TigerVNC can under favourble circumstances be built in a way that allows
the resulting binaries to run on any system without having to also install
all the dynamic libraries it depends on. Enable this mode by adding:

  -DBUILD_STATIC=1

to the CMake command line.

Note that the method used to achieve this is very fragile and it may be
necessary to tweak cmake/StaticBuild.cmake to make things work on your
specific system.


=====================
Building Java support
=====================

TigerVNC includes a Java version of the TigerVNC Viewer, which can be used on
any platform that has a Java Runtime Environment (JRE) installed.  The Java
viewer works similarly to the native viewer, but with lower performance.

To build the Java TigerVNC Viewer, add

  -DBUILD_JAVA=1

to the CMake or build-xorg command line.  The build system will attempt to find
an installed Java Development Kit (JDK) and determine the appropriate paths for
the Java compiler (javac) and the JAR creation utility (jar).  You can override
these paths by setting the Java_JAVAC_EXECUTABLE and Java_JAR_EXECUTABLE CMake
variables.  You can also override the default flags that are passed to javac
by setting the JAVACFLAGS CMake variable.  The build system will look for
keytool and jarsigner in the same directory as Java_JAR_EXECUTABLE.  These
tools are needed to sign the JAR file, which is necessary to enable certain
functionality (such as clipboard transfers) when the Java viewer is used as an
applet.

If the Java viewer is built along with the Windows TigerVNC server (WinVNC),
then the build system will embed the Java viewer into WinVNC4.exe so that it
will automatically be served up using WinVNC's built-in HTTP server.
Similarly, if the Java viewer is built along with the Unix TigerVNC server
(Xvnc), then the build system will include the Java viewer in the server
tarball.

By default, a self-signed certificate will be generated and used to sign the
jar file.  By specifying the following command line arguments to the CMake
command line, an alternate certificate may be used for signing.

  -DJAVA_KEYSTORE=${keystore_location_or_url}
  -DJAVA_KEYSTORE_TYPE=${keystore_type} (Default: "jks")
  -DJAVA_KEY_ALIAS=${keytore_key_alias}
  -DJAVA_STOREPASS=${keystore_password}
  -DJAVA_KEYPASS=${keystore_entry_password}
  -DJAVA_TSA_URL=${url_of_timestamping_authority}

The values of the JAVA_STOREPASS and JAVA_KEYPASS arguments may optionally be
read from file or environment variables by prefixing the value with ":env " 
or ":file " (see the jarsigner documentation for more info): 

  export StorePass=tigervnc
  export KeyPass=tigervnc
  cmake \
    ...
    -DJAVA_STOREPASS=":env StorePass"
    -DJAVA_KEYPASS=":env KeyPass"


======================================
Building TLS support
======================================

TLS requires GnuTLS, which is supplied with most Linux distributions and
with MinGW for Windows and can be built from source on OS X and other 
Unix variants. However, GnuTLS versions > 2.12.x && < 3.3.x should be
avoided because of potential incompatibilities during initial handshaking.

You can override the GNUTLS_LIBRARY and GNUTLS_INCLUDE_DIR CMake variables
to specify the locations of libgnutls and any dependencies.  For instance,
adding

  -DGNUTLS_INCLUDE_DIR=/usr/local/include \
  -DGNUTLS_LIBRARY=/usr/local/lib/libgnutls.a

to the CMake command line would link TigerVNC against a static version of
libgnutls located under /usr/local.


======================================
Building native language support (NLS)
======================================

NLS requires gettext, which is supplied with most Linux distributions and
with MinGW for Windows and which can easily be built from source on OS X and
other Unix variants.

You can override the ICONV_LIBRARIES and LIBINTL_LIBRARY CMake variables to
specify the locations of libiconv and libintl, respectively.  For instance,
adding

  -DLIBINTL_LIBRARY=/opt/gettext/lib/libintl.a

to the CMake command line would link TigerVNC against a static version of
libintl located under /opt/gettext.  Adding

  -DICONV_INCLUDE_DIR=/mingw/include \
    -DICONV_LIBRARIES=/mingw/lib/libiconv.a \
    -DGETTEXT_INCLUDE_DIR=/mingw/include \
    -DLIBINTL_LIBRARY=/mingw/lib/libintl.a

to the CMake command line would link TigerVNC against the static versions of
libiconv and libintl included in the MinGW Developer Toolkit.


===================
Installing TigerVNC
===================

You can use the build system to install TigerVNC 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' to build and
install it.

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


=========================
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 disk image file that contains an application bundle of the
  TigerVNC viewer


Windows
-------

make installer

  Create a Windows installer using Inno Setup.  The installer package
  (TigerVNC[64].exe) will be located under {build_directory}.


=============
Build recipes
=============


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 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.


MinGW-w64 build on Windows
--------------------------

This produces a 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}/x86_64-w64-mingw32-gcc \
    CXX={mingw_binary_path}/x86_64-w64-mingw32-g++ \
    RC={mingw_binary_path}/x86_64-w64-mingw32-windres \
    cmake -G "Unix Makefiles" -DCMAKE_SYSTEM_NAME=Windows \
    -DCMAKE_AR={mingw_binary_path}/x86_64-w64-mingw32-ar \
    -DCMAKE_RANLIB={mingw_binary_path}/x86_64-w64-mingw32-ranlib \
    {source_directory}
  make


===============================
Distribution-specific packaging
===============================

Configuration for building packages for current versions of RHEL/CentOS
and Ubuntu LTS can be found under contrib/packages.