INSTALL

==================================
DICOM TOOLKIT (DCMTK) INSTALLATION
==================================

-------------------------------------------------------------------------------
 IMPORTANT NOTE FOR SNAPSHOT AND CURRENT DEVELOPMENT VERSION 3.6.1_DEV
-------------------------------------------------------------------------------
 Please note that most sections of this document refer to the official release
 DCMTK 3.6.0, i.e. they are not yet updated for the changes of the latest
 development version 3.6.1.  This will be done for the next release, which will
 probably be called version 3.6.2.

 The toolkit should compile on Linux systems with gcc 4.7.2 to 4.9.2 since
 this is our main development platform.  Also on Windows systems, it usually
 works with VisualStudio 2008 to 2013.  However, there is no guarantee that
 the software also compiles on your system.
-------------------------------------------------------------------------------


PRE-REQUISITES
==============

The DICOM toolkit (DCMTK) needs to be compiled with a C++ compiler.  We
recommend using the GNU C++ compiler in versions higher than 2.95 (most of the
development was done using GNU C++ 4.1.2 on Linux 2.6).  The software is also
known to compile using the SUNPro C++ compiler, the Intel C++ compiler and the
Microsoft Visual C++ compiler.

Compatibility with other C++ compilers is unknown, however, we have tried to
keep language demands to a minimum (newer C++ features such as ANSI C++ Library,
Exceptions and RTTI have been avoided).

You will need several hundred Mbytes of disk space to compile all the software.


SUPPORTED SYSTEMS
=================

Microsoft Windows
-----------------

The DCMTK software can be compiled under a native Microsoft Windows environment
(see section "BUILDING (Windows)" below for more information).

The current release successfully compiles on the following systems:

   Windows XP      / Intel x86    / Microsoft Visual C++ 6.0 (Service Pack 6)
   Windows XP      / Intel x86    / Microsoft Visual C++ 2005 Standard (VS 8)
   Windows XP      / Intel x86    / Microsoft Visual C++ 2008 Express (VS 9)
   Windows XP      / Intel x86    / Microsoft Visual C++ 2010 Express (VS 10)
   Windows Vista   / Intel x86    / Microsoft Visual C++ 2008 Professional (VS 9)
   Windows 7       / Intel x86    / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 7       / amd64|x86_64 / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 7       / amd64|x86_64 / Microsoft Visual C++ 2010 Ultimate (VS 10)

The dcmqrscp tool has been ported to Windows, but does not yet support
multi-processing (i.e. multiple clients concurrently) under Windows.  The
worklist WWW scripts require an HTTP server and a Perl interpreter and have
not been tested under Windows (file locking interaction with the wlmscpfs
server may or may not work).

Unix (or lookalikes)
--------------------

The current DCMTK software release successfully compiles on the following
operating system / hardware / compiler combinations using the instructions
given below:

   FreeBSD 6.4     / Intel x86    / GNU gcc 3.4.6
   FreeBSD 7.3     / Intel x86    / GNU gcc 4.2.1
   FreeBSD 8.1     / Intel x86    / GNU gcc 4.2.1
   FreeBSD 8.1     / amd64|x86_64 / GNU gcc 4.2.1
   HP-UX 10.20     / HP PA-RISC   / GNU gcc 2.95.3    (see note *1,*2)
   IRIX 6.3        / SGI O2       / GNU gcc 2.95.3    (see note *1)
   Linux 2.4.20    / Intel x86    / GNU gcc 2.95.3    (RedHat 7.3)
   Linux 2.4.21    / Intel x86    / GNU gcc 3.4.6     (CentOS 3.9)
   Linux 2.6.18    / Intel x86    / GNU gcc 4.1.2     (Debian 4.0)
   Linux 2.6.18    / amd64|x86_64 / Intel Compiler 11.1 (Scientific Linux 5.5)
   Linux 2.6.18    / amd64|x86_64 / GNU gcc 4.1.2     (Debian 4.0)
   Linux 2.6.18    / amd64|x86_64 / GNU gcc 4.5.2     (CentOS 5.5)
   Linux 2.6.26    / amd64|x86_64 / GNU gcc 4.3.2     (Debian 5.0)
   Linux 2.6.32    / amd64|x86_64 / GNU gcc 4.4.4     (RHEL 6.0)
   Linux 2.6.34    / amd64|x86_64 / Intel Compiler 11.1 (SuSE 11.3, see note *3)
   Linux 2.6.35    / amd64|x86_64 / GNU gcc 4.4.5     (Ubuntu 10.10)
   MacOS X 10.4.10 / amd64|x86_64 / Apple gcc 4.0.1   (see note *10)
   MacOS X 10.6.5  / amd64|x86_64 / Apple gcc 4.2.1   (see note *10)
   OpenBSD 4.4     / Intel x86    / GNU gcc 3.3.5 propolice
   Solaris 9       / Sun Sparc    / SunPro CC 5.8     (Sun Studio 11)
   Solaris 10      / Sun Sparc    / SunPro CC 5.9     (Sun Studio 12u2)
   Solaris 10      / Sun Sparc    / GNU gcc 3.4.3
   Windows XP      / Intel x86    / CygWin 1.7.7-1    (gcc 3.4.4 and 4.3.4)
   Windows XP      / Intel x86    / MinGW/MSys 1.0.11 (gcc 4.5.0)

Earlier releases are known to also compile on the following platforms which
are not available to us for testing purposes any more:

   FreeBSD 4.11    / Intel x86    / GNU gcc 2.95.4
   FreeBSD 6.0     / Intel x86    / GNU gcc 3.4.4
   HP-UX 9.05      / HP PA 1.1    / GNU gcc 2.7.2.1
   IBM AIX 3.2     / RS 6000      / IBM AIX XL C++ Compiler/6000 V1.0
   IRIX 5.3        / SGI Indy     / GNU gcc 2.95.2    (see note *1)
   IRIX 6.5        / SGI Onyx     / GNU gcc 2.95.2    (see note *4)
   IRIX 6.5        / SGI Onyx     / MIPSpro 7.3.1.1m  (see note *4)
   Linux 2.0.33    / Intel x86    / GNU gcc 2.7.2.1
   Linux 2.2.16    / IBM S/390    / GNU gcc 2.95.2
   Linux 2.2.16    / Intel x86    / GNU gcc 2.95.2
   Linux 2.4.20    / Intel x86    / GNU gcc 2.95.4, 3.2.3, 3.3.6, 3.4.5 and 4.0.3 (Debian)
   Linux 2.6.1     / amd64|x86_64 / GNU gcc 4.0       (Fedora Core 4)
   MacOS X 10.1.5  / Power Mac G4 / Apple gcc-934.3   (gcc 2.95.2, see note *5)
   MacOS X 10.3.3  / Power Mac G4 / Apple gcc-1640    (gcc 3.3)
   MacOS X 10.4.3  / Power Mac G4 / Apple gcc 4.0.1
   NetBSD 1.6.2    / Intel x86    / GNU gcc 2.95.3
   NetBSD 2.1      / Intel x86    / GNU gcc 3.3.3
   NeXTStep 3.3    / Intel x86    / NeXT/GNU gcc 2.5.8 (see note *6)
   OpenBSD 3.8     / Intel x86    / GNU gcc 3.3.5 propolice
   OSF/1 4.0       / DEC Alpha    / Compaq C++ V6.3-002 (see note *7)
   OSF/1 4.0       / DEC Alpha    / GNU gcc 2.95.3
   QNX 6.2.1       / Intel x86    / GNU gcc 2.95.3    (see note *8)
   Solaris 2.5.1   / Sun Sparc    / GNU egcs 1.1.2    (egcs-2.91.66)
   Solaris 2.5.1   / Sun Sparc    / Sun SC 2.0.1      (SunPro C++ 3.0.1)
   Solaris 2.5.1   / Sun Sparc    / SunPro CC 4.2
   Solaris 7       / Sun Sparc    / GNU gcc 2.95.3
   Solaris 7       / Sun Sparc    / SunPro CC 4.2
   Solaris 8       / Sun Sparc    / GNU gcc 3.2.3, 3.4
   Solaris 8       / Sun Sparc    / SunPro CC 5.2     (Sun WorkShop 6 update 1)
   Solaris 9       / Sun Sparc    / SunPro CC 5.2     (Sun WorkShop 6 update 1)
   Solaris 10      / Intel x86    / SunPro CC 5.8     (Sun Studio 11)
   SunOS 4.1.3     / Sun Sparc    / GNU gcc 2.7.2
   Ultrix 4.4      / DEC MIPS     / GNU gcc 2.95.2    (see notes *1,*9)
   Windows 9x      / Intel x86    / Microsoft Visual C++ 5.0
   Windows NT 4.0  / Intel x86    / Microsoft Visual C++ 6.0 (Service Pack 6)
   Windows XP      / Intel x86    / Microsoft Visual C++ .NET 2003 (VS 7.1)
   Windows XP      / Intel x86    / CygWin 1.5.18     (gcc 3.4.4)
   Windows XP      / Intel x86    / MinGW/MSys 1.0.10 (gcc 3.4.2)

Platform Notes
--------------

(*1) The dcmimage/dcmimgle module makes intensive use of inlined templates.
     Depending on the compiler and the available virtual memory, compilation
     might fail if this module is compiled with optimization.  Compilation
     succeeds if the optimizer and any automatic inlining of code are switched
     off.  For example GNU gcc might require that the -O option is removed and
     -fno-default-inline is added to the CXXFLAGS setting in the file
     "config/Makefile.def", which is created by configure (see below).
(*2) HP-UX 10.2 requires DCMTK to be configured with --disable-lfs, i.e.
     without large file support.
(*3) Building with Intel Compiler Suite 11.1 requires GNU C++ Standard Library
     version 4.3.
(*4) IRIX 6 users are recommended to consult SGI's Notes on building Open
     Source software on IRIX, available from: http://freeware.sgi.com/howto.html
     In short, after running configure, the following modifications are
     required in "config/Makefile.def" before DCMTK can be compiled:
       - remove "-lsocket -lnsl" from LIBS
     On IRIX, DCMTK should be built using GNU make (gmake), not with the IRIX
     specific pmake/smake/make commands.
(*5) MacOS X 10.1 requires DCMTK to be configured with --disable-threads
     because certain re-entrant Posix functions such as localtime_r are not
     available.
(*6) The NeXT gcc 2.5.8 compiler provides only very limited support for C++
     templates and, therefore, might fail to compile the dcmimage/dcmimgle
     module ("internal compiler error").  The gcc compiler also does not
     properly support the "protected" derivation of classes which is used in
     the dcmsr module.  However, modules and applications that were present in
     earlier releases of DCMTK still compile.
(*7) Might require -O0 in order to compile "dcmsr/libsrc/dsrdoctr.cc".
(*8) The libz.so included in QNX 6.2.1 is missing the zlibVersion()
     function.  This will cause the DCMTK compile to fail if configured with
     --with-zlib.  It has already been corrected in QNX's internal cvs
     repository.  Earlier QNX versions (6.2.0) and future versions (6.3.x)
     should work fine.  As a temporary measure it is possible to link against
     /usr/lib/libz.so.1 which does include that function, or to disable zlib
     support in DCMTK by calling configure --without-zlib.
(*9) Requires -fpermissive when compiled with GNU gcc due to the X11R5 header
     files which are not ANSI compliant.
(*10) For MacOS X 10.4 and 10.6 the OFSemaphore class is not available since it
     is compiling but not working on MacOS X.  The reason is that semaphores
     must be named in MacOS X and thus the current implementation fails to
     construct semaphores in the OFSemaphore constructor.  However, the toolkit
     so far does not make any use of this class.

Please note: Due to resource limitations it is not practical for us to ensure
that the newest release of DCMTK is problem free under all the above
combinations.  Currently, our main development environment is Linux 2.6 using
GNU C++ 4.1.2 and DCMTK should always compile on this platform.


OPENSSL SUPPORT
===============

Starting with release 3.4.2, DCMTK supports the "DICOM Security Enhancements
One", i.e. DICOM network transmission "tunneled" through a secure TLSv1
transport connection.  DCMTK relies on the OpenSSL toolkit (www.openssl.org)
for the underlying cryptographic routines and the TLS protocol implementation.
This release of DCMTK is known to compile with the OpenSSL releases 0.9.8 to
1.0.0, although other releases may work as well.

When using autoconf, if support for security enhancements is desired, a compiled
version of the OpenSSL libraries and include files must be available during
compilation of DCMTK.  By default, DCMTK checks whether OpenSSL is installed
in the standard path and enables support automatically if present.

When using CMake, if support for security enhancements is desired, a compiled
version of the OpenSSL libraries and include files must be available during
compilation of DCMTK, and the OpenSSL support must be switched on explicitly
(using CMake, see below).  By default, DCMTK checks whether OpenSSL is installed
and enables support automatically if present.  By default, DCMTK checks the
standard paths on Unix platforms.  For Windows platforms, check the discussion
on CMake below.


ZLIB SUPPORT
============

Starting with release 3.5.2, DCMTK supports the "Deflated Explicit VR Little
Endian" Transfer Syntax, i.e. ZIP-compressed network transmission and media
storage.  DCMTK relies on the zlib toolkit (www.zlib.org) for the underlying
compression routines.  This release of DCMTK is known to compile with the
zlib releases 1.2.3 to 1.2.5, although other releases may work as well.

When using autoconf, if support for zlib compression is desired, a compiled
version of the zlib library and include files must be available during
compilation of DCMTK.  By default, DCMTK checks whether zlib is installed
in the standard path and enables support automatically if present.

When using CMake, a compiled version of the zlib libraries and include
files must be available during compilation of DCMTK.  See discussion on CMake
below.


LIBTIFF SUPPORT
===============

Starting with release 3.5.1, DCMTK supports the conversion of DICOM images
to TIFF.  DCMTK relies on the libtiff toolkit (www.libtiff.org) for this
purpose.  This release of DCMTK is known to compile with the libtiff releases
3.7.4 to 3.9.4, although other releases may work as well.  However, libtiff
releases prior to version 3.7.0 will not work since the TIFFCleanup() function
was not yet available.  On Windows, libtiff 3.7.4 or higher is required due to
incompatible API changes in libtiff.

When using autoconf, if support for TIFF export is desired, a compiled version
of the libtiff libraries and include files must be available during compilation
of DCMTK, and the libtiff support must be switched on explicitly.  By default,
DCMTK checks whether libtiff is installed in the standard path and enables
support automatically if present.

When using CMake, a compiled version of the libtiff libraries and include
files must be available during compilation of DCMTK.  See discussion on CMake
below.


LIBPNG SUPPORT
==============

Starting with release 3.5.3, DCMTK supports the conversion of DICOM images to
PNG.  DCMTK relies on the libpng toolkit (www.libpng.org) for this purpose.
This release of DCMTK is known to compile with the current libpng releases
1.2.8 to 1.4.3, although other releases may work as well.

When using autoconf, if support for PNG export is desired, a compiled version of
the libpng libraries and include files must be available during compilation of
DCMTK, and the libpng support must be switched on explicitly.  By default,
DCMTK checks whether libpng is installed in the standard path and enables
support automatically if present.  It should be noted that libpng requires
zlib.

When using CMake, a compiled version of the libpng libraries and include
files must be available during compilation of DCMTK.  See discussion on CMake
below.


LIBXML2 SUPPORT
===============

Starting with release 3.5.3, DCMTK supports the conversion of XML documents to
DICOM files.  DCMTK relies on the libxml2 toolkit (www.libxml.org) for this
purpose.  This release of DCMTK is known to compile with the libxml2 releases
2.6.26 to 2.7.7, although other releases may work as well.

When using autoconf, if support for XML import is desired, a compiled version of
the libxml2 (and possibly iconv) libraries and include files must be available
during compilation of DCMTK.  By default, DCMTK checks whether libxml2 is
installed in the standard path and enables support automatically if present.

When using CMake, if support for XML import is desired, a compiled version
of the libxml2 (and possibly iconv) libraries and include files must be
available during compilation of DCMTK.  See discussion on CMake below.


TCP WRAPPER (LIBWRAP) SUPPORT
=============================

Starting with release 3.5.3, DCMTK supports Wietse Venema's TCP wrappers
library (libwrap) which is freely available for most Unix platforms and part
of the default installation of most recent Linux distributions.  This library
allows to enforce host-based access control via the "/etc/hosts.deny" and
"/etc/hosts.allow" configuration files.  See hosts_access(5) man page for
details.

When using autoconf, if support for TCP wrappers is desired, a compiled version
of the libwrap library and include file <tcpd.h> must be available during
compilation of DCMTK.  By default, DCMTK checks whether libwrap is installed
in the standard path and enables support automatically if present.

Since DCMTK uses the TCP wrappers from C++ code, an ANSI C compatible header
file <tcpd.h> is required.  The official release 7.6 of the TCP wrappers
library is not ANSI C compatible and does not work with DCMTK (i.e. will not be
recognized by DCMTK's configure script).  However, many current Linux and BSD
distributions ship with an ANSI C compatible header file.

When using CMake, TCP wrappers are currently not supported.


LIBICONV SUPPORT
================

Starting with release 3.6.2, DCMTK supports the conversion between different
character encodings.  For this purpose, DCMTK relies on the libiconv toolkit
(www.gnu.org/s/libiconv/).  This release of DCMTK is known to compile with the
libiconv release 1.14, although other releases may work as well.

When using autoconf, if support for libiconv conversion is desired, a compiled
version of the libiconv library and include files must be available during
compilation of DCMTK.  Please note that DCMTK also needs the bundled copy of
libcharset.  By default, DCMTK checks whether libiconv and libcharset are
installed in the standard path and enables support automatically if present.

When using CMake, a compiled version of the libiconv and libcharset libraries
and include files must be available during compilation of DCMTK.  See discussion
on CMake below.


C++11 SUPPORT
=============
DCMTK can be enabled to use the C++11 STL.  This is controlled by the macro
"DCMTK_USE_CXX11_STL", described in "config/docs/macros.txt" (or
"/usr/local/share/doc/dcmtk/macros.txt").


BUILDING (Unix with autoconf)
=============================

GNU autoconf is used to configure the software for the hardware / operating
system you are using.  You do not need to obtain GNU autoconf to compile and
install this software.  All the necessary configure scripts are included in
this distribution.  The configure scripts examine your system capabilities and
automatically generate include files and Makefiles.

Perform the following steps from the top-level (dcmtk-3.6.0) directory to
compile and install the software:

Step 1:
    ./configure

Step 1 executes the configure scripts in each subdirectory.  First, the system
capabilities are examined and then Makefiles are generated.  By default,
executables and other files will be installed (in Step 3) in the directory
"/usr/local" in the corresponding subdirectories.  If you wish to use another
install prefix you can use the --prefix=<path> flag to configure.  E.g., if you
wish to install underneath your home directory in "~/dicom" then you should
start configure as:

    ./configure --prefix=$HOME/dicom

Step 1 is also the place where support for the external libraries can be
enabled or disabled.  By default, all libraries installed in the standard
path are enabled automatically.  Use the --without-openssl switch to disable
OpenSSL support.  The --with-opensslinc option allows to specify the directory
in which OpenSSL is installed.  This is usually the directory that has been
used as --prefix when compiling and installing OpenSSL.

For example, if you wish to enable the security enhancements, and OpenSSL is
installed in "/usr/local/apps/openssl-1.0.0", then you should start configure
as:

    ./configure --with-opensslinc=/usr/local/apps/openssl-1.0.0

Configure will assume that the OpenSSL include files are installed in
"/usr/local/apps/openssl-1.0.0/include" and will expect the library in
"/usr/local/apps/openssl-1.0.0/lib".  Appropriate options will be passed to
the compiler and the linker.

Support for zlib, libtiff, libpng, libxml2, libwrap and libiconv can be enabled
in a similar way (in case these libraries are not installed in the standard
path):

    ./configure --with-libzlibinc=/usr/local/apps/zlib-1.2.5
                --with-libtiffinc=/usr/local/apps/libtiff-3.9.4
                --with-libpnginc=/usr/local/apps/libpng-1.4.3
                --with-libxmlinc=/usr/local/apps/libxml-2.7.7
                --with-libwrapinc=/usr/local/apps/tcp_wrappers-7.6
                --with-libiconvinc=/usr/local/apps/libiconv-1.14

Different configure options can be combined in any order.  configure --help
will print a list of all existing configure options.  configure --help=short
will display only those options specific to the DCMTK.  Useful configure
options are:

  --enable-debug          compile with debug code, don't optimize
  --disable-debug         compile without debug code (default)
  --enable-threads=TYPE   compile with MT support (posix/solaris/auto=default)
  --disable-threads       compile without MT support
  --enable-lfs=TYPE       compile with LFS support (lfs/lfs64/auto=default)
  --disable-lfs           compile without LFS support
  --enable-std-includes   use C++ ANSI standard includes
  --disable-std-includes  use old C++ includes

Step 2:
    make all

Step 2 will build the libraries and executables.  If you run into problems see
the section "Solving configuration and compilation problems" below.

Step 3:
    make install

Step 3 will install the executables and some support files (data dictionary,
configuration and documentation files).  If you also wish to install the
libraries and include files then use "make install-lib".  For the HTML
documentation (see below) use "make install-html" (requires Doxygen to be
installed); "make install-all" installs all of the above.

In case the files should be installed in a temporary directory, e.g. in order
to create a distribution package, use "make install DESTDIR=<path>" to prepend
<path> to the installation directories specified for configure.

Step 4:
    make distclean

Step 4 will revert the source tree to the state prior to Step 1.  If you just
want to get rid of object files and local executables use "make clean" instead.

Note: In case you do not want to compile all modules, you can remove those
modules from the text file "config/modules" prior to Step 1 and execute the
following commands:

    cd config
    ./rootconf
    cd ..

This generates a new Makefile and configure script in the top-level toolkit
directory.

Solving configuration and compilation problems:

The configure script might not be able to guess the correct compiler and
compiler flags to use.  For example, we have noticed that use of the -pedantic
flag to the GNU C++ compiler causes compilation errors on some systems (e.g.
SunOS 4.1.3) due to system include files with incorrect ANSI function
prototypes.

You can set environment variables to initialize configure before it is called
(before Step 1 above):

  Set environment variable CC to the name of your C compiler.
  Set environment variable CFLAGS to the compile flags of your C compiler.
  Set environment variable CXX to the name of your C++ compiler.
  Set environment variable CXXFLAGS to the compile flags of your C++ compiler.
  Set environment variable LDFLAGS to your linker flags.
  Set environment variable CPPFLAGS to you preprocessor flags.

You do not need to specify all the above environment variables since the
default settings are sensible for most Unix compilers.  Further influential
environment variables are listed in the output of configure --help.

If the configure script fails you may have to change the configuration settings
in the config directory.  See the "config/docs" directory for more information.

See also the FAQ at http://forum.dcmtk.org/faq for more hints.


BUILDING (CMake in general)
===========================

CMake is a cross-platform, open-source make system which can be used to control
the software compilation process using simple configuration files.  CMake can be
obtained free of charge from http://www.cmake.org/.  For configuring the DCMTK,
the toolkit contains corresponding "CMakeLists.txt" files in all necessary
directories.  In detail, these "CMakeLists.txt" files will serve as an input to
CMake which will generate suitable build files for all of DCMTK's projects from
these files.

More info about building the DCMTK with CMake can be found in DCMTK's wiki:

  http://support.dcmtk.org/wiki/dcmtk/howto/cmakeconfiguration


Microsoft Windows with CMake
----------------------------

Starting with DCMTK 3.5.4, no project files for Visual Studio are provided
anymore.  Project files for all supported compilers can be generated with
CMake.

In order to be able to use CMake for configuration purposes in DCMTK, perform
the following steps to install CMake on your machine:

1. Go to http://www.cmake.org/ to download the latest release version of CMake
   for Windows.
2. Execute the file which was downloaded to install CMake on your machine.
   Follow all install instructions appropriately.

In order to manually configure the support for the above mentioned external
libraries (OpenSSL, zlib, libtiff, libpng, libxml2 and libiconv) through CMake,
perform the following steps:

1. Go Start -> Programs -> CMake -> "CMake" or "CMake (cmake-gui)" to start the
   CMake utility through which the configuration can be done.
2. In the entry field "Where is the source code:" enter the directory in which
   the DCMTK source code resides, e.g. "C:\dcmtk-3.6.0".
3. In the entry field "Where to build the binaries:" enter the directory in
   which the libraries and binaries are to be built, e.g. "C:\dcmtk-bin".
4. In the combobox "Build for:" or "Specify the generator for this project:"
   select the corresponding development environment which shall be used to
   compile DCMTK.
5. Go "Configure".  (CMake will look for a corresponding compiler, read in all
   of DCMTK's "CMakeLists.txt" files and perform some tests.  The variables in
   the tabular area will be displayed in red.  These variables can now be set
   in order to turn the support for any of the external libraries on or off.)
6. Make the corresponding configurations in CMake's user interface.  For
   example, in order to turn on libxml2 support, set the value of variable
   "DCMTK_WITH_XML" to "ON" and set the value of variable "WITH_LIBXMLINC"
   to the path where the include files and libraries of libxml2 can be found,
   e.g. "C:\libxml2-2.7.7".  The support of all other external libraries can
   be turned on in a similar way:

     libpng support:
       set "DCMTK_WITH_PNG" to "ON" and
       set "WITH_LIBPNGINC" e.g. to "C:\libpng-1.4.2"

     libtiff support:
       set "DCMTK_WITH_TIFF" to "ON" and
       set "WITH_LIBTIFFINC" e.g. to "C:\tiff-3.9.2"

     OpenSSL support:
       set "DCMTK_WITH_OPENSSL" to "ON" and
       set "WITH_OPENSSLINC" e.g. to "C:\openssl-1.0.0"

     zlib support:
       set "DCMTK_WITH_ZLIB" to "ON" and
       set "WITH_ZLIBINC" e.g. to "C:\zlib-1.2.5"

     libiconv support:
       set "DCMTK_WITH_ICONV" to "ON" and
       set "WITH_LIBICONVINC" e.g. to "C:\libiconv-1.14"

   In order to turn the support of a certain external library off, set the
   value of the corresponding variable ("DCMTK_WITH_XML", "DCMTK_WITH_PNG",
   "DCMTK_WITH_TIFF", "DCMTK_WITH_OPENSSL", "DCMTK_WITH_ZLIB" or
   "DCMTK_WITH_ICONV") to "OFF".

   (Please note that the include files of all external libraries are always
   expected in a directory named "include" below the directory which is
   specified in "WITH_LIBXMLINC", "WITH_LIBPNGINC", "WITH_LIBTIFFINC",
   "WITH_OPENSSLINC", "WITH_ZLIBINC" or "WITH_LIBICONVINC".)

   (Please note also that the library files of all external libraries are
   always expected in directory named "lib" below the directory which is
   specified in "WITH_LIBXMLINC", "WITH_LIBPNGINC", "WITH_LIBTIFFINC",
   "WITH_OPENSSLINC", "WITH_ZLIBINC" or "WITH_LIBICONV".  Moreover, note that
   the following filenames must be used for the corresponding lib files:

     libxml2:
       "iconv_d.lib"    - debug version
       "iconv_o.lib"    - release version (optimized)
       "libxml2_d.lib"  - debug version
       "libxml2_o.lib"  - release version (optimized)

     libpng:
       "libpng_d.lib"   - debug version
       "libpng_o.lib"   - release version (optimized)

     libtiff:
       "libtiff_d.lib"  - debug version
       "libtiff_o.lib"  - release version (optimized)

     openssl:
       "libeay32_d.lib" - debug version
       "libeay32_o.lib" - release version (optimized)
       "ssleay32_d.lib" - debug version
       "ssleay32_o.lib" - release version (optimized)

     zlib:
       "zlib_d.lib"     - debug version
       "zlib_o.lib"     - release version (optimized)

     libiconv:
       "libiconv_d.lib" - debug version
       "libiconv_o.lib" - release version (optimized)
       "libchset_d.lib" - debug version
       "libchset_o.lib" - release version (optimized)

   The debug versions of all libraries must be compiled for the multithread
   debug version of the runtime (/MTd), the release version must be compiled
   for the non-debug multithread runtime (/MT).  Precompiled versions of all
   libraries can be downloaded from http://dicom.offis.de/dcmtk#lib-win.)
7. Go "Configure" a second time.  (CMake will adjust the configuration
   according to the displayed specifications.)
8. Go "OK" or "Generate".  (CMake will generate new project files in the
   corresponding directories.  These files will be adjusted according to the
   displayed specifications, i.e. support for the external libraries will be
   turned on or off.)

Having performed these steps, the Microsoft Visual Studio IDE can be started,
DCMTK's workspace file can be opened, and one or more of DCMTK's subprojects
can be built.  In case you want to build all libraries and applications, mark
the "ALL_BUILD" subproject and build it.  The "INSTALL" subproject installs
the executables, libraries, include, support and documentation files to the
directory specified by the variable "CMAKE_INSTALL_PREFIX" (very similar to
"make install-all" on Unix systems).

Compilation and installation of the various command line applications
(including the test programs) can be disabled by setting the "BUILD_APPS"
option to "OFF" before configuring and generating the project files.  By
default, all command line applications are built and installed.

Please note that other Windows compilers, e.g. Borland C++ Builder, are
currently not actively supported.  However, they may work.

Known limitations of DCMTK on the Windows platform.

1. The dcmqrscp tool cannot spark multiple processes.  Every association must
   be handled completely before a new association is possible.
2. On Windows 95, dcmqrscp always uses exclusive file locking (the LockFileEx
   API call is available on Windows NT only).  This is no problem if only a
   single process exists.
3. Most applications will only work if the computer has configured TCP/IP, a
   network name and a TCP/IP address.  If SLIP or PPP is used the applications
   can only work if a connection to a provider exists (since the IP addresses
   and hostnames are given dynamically).
4. Visual C++ contains two different implementations of I/O streams which
   should never be mixed within one application because this may cause
   application errors that are hard to find.  The old, now deprecated
   implementation uses the traditional cfront header files <iostream.h> etc.
   The new implementation uses <iostream> etc. as defined in ANSI/ISO C++.
   DCMTK can be configured to use either of the two interfaces.  This behavior
   can be changed in "config/include/dcmtk/config/osconfig.h" in the build
   directory where the symbol USE_STD_CXX_INCLUDES is declared.

   NOTE: Previous releases of DCMTK (3.5.1 and older) used the old interface
         when compiled with Visual C++ 6.0.  When updating software that uses
         DCMTK as a library, make sure that the use of the iostream library is
         consistent throughout the complete application!

5. DCMTK does not compile when UNICODE or _UNICODE is defined because the
   VisualStudio compiler then uses the Unicode version instead of the ANSI
   version for all Windows API functions (i.e. type wchar_t instead of char
   for all character string parameters and return values).


Unix with CMake
---------------

Starting with DCMTK 3.6.0, CMake can also be used for non-Windows systems.

NOTE: This is not (yet) the recommended way since this mechanism is not as
      mature and stable as the above described approach using GNU autoconf.
      Please feel free to test it and report any issue.  Due to this, it is only
      sparsely documented.  See the previous section on building the DCMTK with
      CMake on Windows platforms, but note that details may differ.


CMake and shared libraries
--------------------------

The CMake build system allows building shared libraries instead of static
libraries.  On Windows systems, these are dynamic link libraries (.dll).
On Unix systems, these are shared objects (.so).  To enable this, set the
"BUILD_SHARED_LIB" option to "ON".

Additionally, it is possible to produce a single shared library for the whole
toolkit.  This mode is controlled by the "BUILD_SINGLE_SHARED_LIBRARY" option.
If you don't want the whole toolkit in a single shared library, the
"DCMTK_MODULES" cache variable can be modified to select a subset of the
available modules.  Please note that this option is marked as advanced and thus
is hidden by default.  Also, when building a single shared library, applications
and tests cannot be built.

Please note that support for shared libraries is still pretty new in DCMTK and
thus not that mature.


Default value for CMAKE_BUILD_TYPE
----------------------------------

CMAKE_BUILD_TYPE is set to value "Release" if none is specified by the
selected build file generator. For those generators that support multiple
configuration types (e.g. Debug, Release), CMAKE_CONFIGURATION_TYPES holds
possible values.  For other generators this value is empty, and for those
generators the build type is controlled at CMake time by CMAKE_BUILD_TYPE.

To disable the CMAKE_BUILD_TYPE default value, set CMAKE_BUILD_TYPE to value
"None" during CMake configuration, e.g. use "-DCMAKE_BUILD_TYPE:STRING=None"
on the command line.  This may be useful if the compiler flags should be
controlled manually (e.g. as defined in environment variables like CXXFLAGS)
and no CMake defaults related to the selected configuration type kick in.


DCMTKConfig.cmake AND DCMTKTargets.cmake
----------------------------------------

CMake permits to write files that describe the DCMTK build configuration
(DCMTConfig.cmake) as well as all targets (executables and libraries) that have
been produced (DCMTKTargets.cmake).  Those files can be utilized by external
projects by using CMake' find_package() mechanism in "CONFIG" mode in order to
adapt their own build configuration, and directly make use of all available
target libraries and executables.

On systems using CMake versions equal or greater than 2.8.8, these files are
written during installation to the installation directory's subfolder
/cmake on Windows systems, and /lib/cmake/dcmtk on Unix-like systems.
Additionally, these files are already written to the main directory of CMake's
build tree during the build, with all content (e.g. the include paths within
DCMTConfig.cmake) pointing to the correct values for the build tree.  Thus even
a DCMTK build tree can be used by external projects that process these two
files.

On systems using CMake versions lower than 2.8.8, only a simplified
DCMTKConfig.cmake is created, which is only available in the install tree.
DCMTKTargets.cmake is not created at all.


HTML DOCUMENTATION AND MAN PAGES
================================

Most DCMTK modules have been documented with Doxygen (www.doxygen.org), a free
source code documentation system similar to Javadoc.  Unix users who have
Doxygen installed can create a hypertext documentation with "make html" in the
"dcmtk-3.6.0" or "doxygen" directory; Windows and other CMake users should
build the "DOXYGEN" subproject.  A project file for Microsoft's HTML Help
Workshop can also be generated allowing to create a single CHM file (compressed
HTML) from the documentation.  Other output formats (e.g. LaTeX) can be enabled
by changing the configuration file in the "doxygen" directory.

At the current time, dcmimage, dcmimgle, dcmjpeg, dcmpstat, dcmrt, dcmsign,
dcmsr, dcmtls, dcmwlm and ofstd are completely documented, dcmdata, dcmjpls,
dcmnet and oflog are almost completely documented.  See FAQ entry: "Where is
rest of the documentation?"

On Unix platforms, man pages for all command line tools are installed during
the "make install" step.  In order to use them, just add the directory (e.g.
"/usr/local/share/man") to the MANPATH environment variable and try
"man dcmdump" to check whether it works.

In order to generate plain text files from the man pages call "make text" in
the "doxygen" directory.  The output files are stored in "doxygen/man2text".


COMPILE-TIME FLAGS AND ENVIRONMENT VARIABLES
============================================

The behavior of several DCMTK tools and libraries can be modified by a number
of compile-time flags (macros).  Those macros which are not automatically
handled by the configure mechanism are documented in "config/docs/macros.txt"
(or "/usr/local/share/doc/dcmtk/macros.txt").

There is also a number of environment variables which affect DCMTK's behavior.
These are documented in "config/docs/envvars.txt" (or "/usr/local/share/doc/
dcmtk/envvars.txt").


RUNNING THE TEST SUITE
======================

DCMTK comes with a test suite that verifies that the toolkit works as expected.
The tests are contained in a module's "tests" subdirectory.

When using configure for building DCMTK, all tests can be run via "make check".
If a test fails, make will stop and the failure reason of the test which failed
should be visible.

You can also run the test suite with CMake.  However, the steps needed for
running the test suite depend on the generator used.  The Visual Studio
generators will create a "RUN_TESTS" subproject.  Building this project will
call CTest and run all tests.  When using the Makefile generator, "make test"
runs the test suite.  Other generators should use a similar approach.

For closer inspection, individual tests can be run directly.  The Makefiles
will build the test runner for each module as "<module>/tests/tests".  CMake
will add the module name as a prefix to this file's name, e.g. "ofstd_tests".
For more information, call this program with the --help option.


---------

Have fun.

M. Eichelberg, J. Riesmeier, M. Onken, U. Schlachter, J. Schlamelcher
DCMTK Development Team, Oldenburg, Germany.

Last revised: 2015-09-18 (Riesmeier)