INSTALL

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


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 4.2.1 (most of the
development for this release was done using GNU C++ 6.3.0 on Debian Linux).
The software is also known to compile using the SUNPro C++ compiler, Clang and
Microsoft Visual Studio.

Compatibility with other C++ compilers is unknown, however, we have tried to
keep language demands to a minimum (newer C++ features such as Exceptions and
RTTI have been avoided and fall back implementations for all used STL classes
are provided).

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 "Microsoft Windows with CMake" below for more information).

The current (minor) release successfully compiles on the following operating
system / hardware / compiler combinations:

   Windows 7       / Intel x86    / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 7       / Intel x86    / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 7       / amd64|x86_64 / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 7       / amd64|x86_64 / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2008 Express (VS 9)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2012 Express (VS 11)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2013 Express (VS 12)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2017 Community (VS 15)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2019 Community (VS 16)
   Windows 10      / Intel x86    / MinGW gcc 9.2.0 (i686-w64-mingw32)
   Windows 10      / Intel x86    / MinGW gcc 10.2.0 (i686-w64-mingw32)
   Windows 10      / Intel x86    / MinGW Clang 10.0.1 (i686-w64-mingw32)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2012 Express (VS 11)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2013 Express (VS 12)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2017 Community (VS 15)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2019 Community (VS 16)
   Windows 10      / amd64|x86_64 / MinGW gcc 9.2.0 (x86_64-w64-mingw32)
   Windows 10      / amd64|x86_64 / MinGW gcc 10.2.0 (x86_64-w64-mingw32)
   Windows 10      / amd64|x86_64 / MinGW Clang 10.0.1 (x86_64-w64-mingw32)

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

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

   FreeBSD 12.2    / amd64|x86_64 / Clang 10.0.1
   Linux 3.2.0     / amd64|x86_64 / GNU gcc 4.4.7     (Debian 7.11)
   Linux 3.10.0    / amd64|x86_64 / Clang 3.4.2       (CentOS 7.9)
   Linux 3.10.0    / amd64|x86_64 / GNU gcc 4.8.5     (CentOS 7.9)
   Linux 3.13.0    / amd64|x86_64 / Clang 3.9.1       (Linux Mint 17.3)
   Linux 3.13.0    / amd64|x86_64 / GNU gcc 4.8.5     (Linux Mint 17.3)
   Linux 3.13.0    / amd64|x86_64 / GNU gcc 5.5.0     (Linux Mint 17.3)
   Linux 3.13.0    / amd64|x86_64 / GNU gcc 6.5.0     (Linux Mint 17.3)
   Linux 3.13.0    / amd64|x86_64 / GNU gcc 7.5.0     (Linux Mint 17.3)
   Linux 3.13.0    / amd64|x86_64 / GNU gcc 8.4.0     (Linux Mint 17.3)
   Linux 4.19.0    / Intel x86    / Clang 7.0.1       (Debian 10)
   Linux 4.19.0    / Intel x86    / GNU gcc 8.3.0     (Debian 10)
   Linux 4.19.0    / amd64|x86_64 / Clang 7.0.1       (Debian 10)
   Linux 4.19.0    / amd64|x86_64 / GNU gcc 8.3.0     (Debian 10)
   Linux 4.19.41   / amd64|x86_64 / GNU 8.3.0         (Alpine 3.9.4 with musl libc)
   Linux 5.4.0     / amd64|x86_64 / Clang 9.0.1       (Ubuntu 20.04)
   Linux 5.4.0     / amd64|x86_64 / Clang 10.0.0      (Ubuntu 20.04)
   Linux 5.4.0     / amd64|x86_64 / GNU gcc 9.3.0     (Ubuntu 20.04)
   Linux 5.4.0     / amd64|x86_64 / GNU gcc 10.2.0    (Ubuntu 20.04)
   Linux 5.8.0     / amd64|x86_64 / GNU gcc 10.2.0    (Ubuntu 20.10)
   Linux 5.8.0     / amd64|x86_64 / Clang 11.0.0      (Ubuntu 20.10)
   MacOS X 10.15   / amd64|x86_64 / Apple Clang 11.0.0
   MacOS X 10.15   / amd64|x86_64 / GNU gcc 9.2.0
   NetBSD 9.0      / amd64|x86_64 / Clang 9.0.1
   NetBSD 9.0      / amd64|x86_64 / GNU gcc 7.4.0
   OpenBSD 6.8     / amd64|x86_64 / Clang 10.0.1
   OpenBSD 6.8     / amd64|x86_64 / GNU gcc 4.2.1
   OpenBSD 6.8     / amd64|x86_64 / GNU gcc 8.4.0
   OpenIndiana     / Intel x86    / GNU gcc 8.3.0     (OpenIndiana 2019.04)
   Solaris 11.3    / Intel x86    / GNU gcc 4.8.2
   Solaris 11.3    / Intel x86    / SunPro CC 5.14    (Oracle Developer Studio 12.5)
   Solaris 11.3    / Intel x86    / SunPro CC 5.15    (Oracle Developer Studio 12.6)

Cross Compiling
---------------

The current DCMTK release can be cross-compiled targeting the following
platforms:

   Android         / arm64        / GNU gcc 8.3.0     (API 24, ABI arm64-v8a)

Cross compiling support with running configuration and unit tests is currently
only provided using CMake and requires the use of the Android emulator or Wine
when targeting Android or Windows respectively.  Other versions of Android will
most likely also work, but the above mentioned one is currently the only one
that is being regularly tested.

Other Platforms
---------------

The previous minor release DCMTK 3.6.5 was also tested on the following
platforms that may still work, but were not tested again for this minor release:

   Android         / arm64        / GNU gcc 6.3.0     (API 24, ABI arm64-v8a)
   FreeBSD 12.0    / amd64|x86_64 / Clang 6.0.1
   Linux 5.0.0     / amd64|x86_64 / gcc 8.3.0         (Ubuntu Linux)
   Linux 5.3.7     / amd64|x86_64 / Clang 9.0.0       (Arch Linux)
   Linux 5.3.7     / amd64|x86_64 / GNU gcc 9.2.0     (Arch Linux)
   OpenBSD 6.5     / amd64|x86_64 / Clang 7.0.1
   OpenBSD 6.5     / amd64|x86_64 / GNU gcc 4.2.1
   Windows 10      / Intel x86    / MinGW gcc 7.4.0 (i686-w64-mingw32)
   Windows 10      / amd64|x86_64 / MinGW gcc 8.2.1 (x86_64-w64-mingw32)

The previous minor release DCMTK 3.6.4 was also tested on the following
platforms that may still work, but were not tested again for this minor release:

   Linux 3.2.0     / amd64|x86_64 / GNU gcc 4.8.4     (Debian 7.11)
   Linux 3.16.0    / armv7|armhf  / GNU gcc 4.9.4     (Debian 8)
   Linux 4.19.4    / amd64|x86_64 / Clang 7.0.0       (Arch Linux)
   Linux 4.19.4    / amd64|x86_64 / GNU gcc 8.2.1     (Arch Linux)
   NetBSD 8.0      / amd64|x86_64 / Clang 5.0.2
   NetBSD 8.0      / amd64|x86_64 / GNU gcc 5.5.0
   Windows 7       / Intel x86    / Microsoft Visual C++ 2005 Express (VS 8)
   Windows 10      / Intel x86    / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2015 Community (VS 14)
   Windows 10      / amd64|x86_64 / Microsoft Visual C++ 2017 Community (VS 15)

The previous minor release DCMTK 3.6.3 was also tested on the following
platforms that may still work, but were not tested again for this minor release:

   Linux 3.16.0    / amd64|x86_64 / Clang 3.5.0       (Debian 8.8)
   Linux 3.2.0     / amd64|x86_64 / GNU gcc 4.7.2     (Debian 7.11)
   Linux 4.10.0    / amd64|x86_64 / GNU gcc 6.3.0     (Ubuntu 17.04)
   Linux 4.10.0    / amd64|x86_64 / Clang 4.0.0       (Ubuntu 17.04)
   MacOS X 10.10.4 / amd64|x86_64 / Apple Clang 6.0
   Windows 7       / amd64|x86_64 / CygWin 2.8.0      (gcc 6.3.0)
   OpenIndiana     / Intel x86    / Clang 4.0.0       (OpenIndiana 2017.04)

The previous release DCMTK 3.6.2 was also tested on the following platforms
that may still work, but were not tested again for this minor release:

   QNX 6.5         / Intel x86    / GNU gcc 4.4.2 (see note *1)
   Windows 8.1     / Intel x86    / Microsoft Visual C++ 2008 Express (VS 9)
   Windows 8.1     / Intel x86    / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 8.1     / Intel x86    / Microsoft Visual C++ 2012 Express (VS 11)
   Windows 8.1     / Intel x86    / Microsoft Visual C++ 2015 Express (VS 14)
   Windows 8.1     / Intel x86    / Microsoft Visual C++ 2017 Community (VS 15)
   Windows 8.1     / amd64|x86_64 / Microsoft Visual C++ 2010 Express (VS 10)
   Windows 8.1     / amd64|x86_64 / Microsoft Visual C++ 2012 Express (VS 11)
   Windows 8.1     / amd64|x86_64 / Microsoft Visual C++ 2015 Express (VS 14)
   Windows 8.1     / amd64|x86_64 / Microsoft Visual C++ 2017 Community (VS 15)

Cross compilers:

   Windows 7       / Intel x86    / MinGW gcc 4.9.1 (Linux host)
   Windows 7       / amd64|x86_64 / MinGW gcc 4.9.1 (Linux host)

Earlier releases of the DCMTK are known to also compile on further platforms
which are not available to us for testing purposes any more, e.g. AIX, HP-UX,
IRIX, NeXTStep, OSF/1, Solaris/SunOS, Ultrix.  Also the Intel C++ Compiler and
other compilers might still work but we haven't tested them this time.

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

(*1) QNX 6.5 requires to remove or disable the define "HAVE_IEEEFP_H" in
     "config/include/dcmtk/config/osconfig.h" after running the configure
     process but before starting the compilation.


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

Starting with release 3.4.2, DCMTK supports encrypted network transmissions
using the Transport Layer Security (TLS) protocol as defined in DICOM part 15.
DCMTK relies on the OpenSSL toolkit (www.openssl.org) for the underlying
cryptographic routines and the TLS protocol implementation.

This release of DCMTK requires OpenSSL release 1.0.1 or newer.  We recommend
the use of OpenSSL 1.0.2 or newer, however, since some  optional functions
recommended by RFC 7525 / BCP 195 are only available  starting with this
OpenSSL release.  Furthermore, users should make care that the most recent
OpenSSL patch level is applied.  This release of DCMTK is known to compile with
the OpenSSL releases 1.0.1 to 1.1.1i.

Note: DCMTK 3.6.6 is explicitly NOT approved for use with the upcoming
OpenSSL 3.0.0 library, which is currently in "alpha" status. OpenSSL 3.0
will NOT work correctly with the dcmsign module, as it requires some additional
code to load the RIPEMD160 routines, which have been moved to the so-called
"legacy provider" that is not active by default; the required modifications
will be included in the next DCMTK release.

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

Known Issues
------------

The ABI of various DCMTK libraries changes when DCMTK is build with/without
OpenSSL. This may result in hard to debug bugs e.g. when using the command line
tools that depend on at least one of those libraries while mixing a non OpenSSL
build with an OpenSSL enabled build of DCMTK (for example when installing an
OpenSSL enabled DCMTK on top of a DCMTK installation without OpenSSL support).
We have introduced a CMake variable called DCMTK_TLS_LIBRARY_POSTFIX as a
workaround. If you plan on mixing OpenSSL and non OpenSSL enabled builds (or
can't be sure that your builds wont be mixed by somebody else), we suggest
setting DCMTK_TLS_LIBRARY_POSTFIX to some different string for the different
builds (e.g. an empty string for the non OpenSSL build and "-openssl" for the
other). This way, all affected libraries will be named including the chosen
postfix, effectively preventing the unintended mixing and, therefore,
preventing the bugs.


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.8 to 1.2.11, although other releases may work as well.

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.8.2 to
4.1.0, 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 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.50 to 1.6.37, although other releases may work as well.

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.9.4 to 2.9.10, although other releases may work as well.

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 CMake, 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.  See discussion on CMake below.

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.


Character Set Conversion Support
================================

Starting with release 3.6.2, DCMTK supports the conversion between different
character encodings, e.g. UTF-8 and ISO Latin 1.  For this purpose, DCMTK relies
on one of the following alternatives to be available for being used as the
underlying implementation: libiconv, the ICU library or the iconv functionality
included in the C standard library.

DCMTK detects the availability of these implementations and (in case multiple
ones are available) chooses one of them automatically as follows: the libiconv
implementation is currently preferred since its integration is most mature.  If
it is not available, the ICU implementation is the next best choice.  Otherwise
the iconv implementation from the C standard library will be selected (if the
used C standard library provides it).  This choice can be overridden via the
"--enable-charconv" argument (Autoconf) or "DCMTK_ENABLE_CHARSET_CONVERSION"
(CMake).  Selecting an implementation that is not available will be ignored,
i.e. the user choice will be overridden.

LIBICONV SUPPORT
----------------

The libiconv toolkit (www.gnu.org/s/libiconv/) may be used as DCMTK's underlying
character set conversion implementation.  This release of DCMTK is known to
compile with the libiconv release 1.15, although other releases may work as
well.

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.

ICU SUPPORT
-----------

DCMTK supports the International Components for Unicode (ICU) library as an
alternative to the above mentioned libiconv.  This release of DCMTK is known to
compile with the ICU releases 59.1 to 68.1.0, although other releases may work
as well.

The ICU may be easier to integrate on some more modern Linux distributions
(e.g. Arch Linux) and Windows than the libiconv but (due to the way it is
currently integrated) lacks support for converting the following character sets:

  ISO 2022 IR 87
  ISO 2022 IR 159

Furthermore, the ICU-based implementation currently does not support
transliteration.

When using CMake, if support for character set conversion using ICU is desired,
a compiled version of the ICU libraries and include files must be available
during compilation of DCMTK.  See discussion on CMake below.

Support for iconv provided in the C standard library
----------------------------------------------------

DCMTK allows using the iconv implementation provided as part of the C standard
library on some platforms.  Building DCMTK with this implementation may be
easier and reduce additional runtime dependencies, but this option should be
used with caution: the iconv implementations from different C standard libraries
may vary with regards to the supported character sets and functionalities.

If possible, the libiconv implementation should be preferred.  Most importantly
some iconv implementations provided by the C standard library do not support
conversion to whatever character set the terminal is currently using, which we
consider essential and, therefore, strongly suggest not to use those
implementations (there is a new configure test for the issue, which allows to
query support for this on API level).

Known Issues
------------

If both the iconv implementation from the C standard library and the libiconv
are available in the default search paths, the wrong <iconv.h> might be included
independently from the user choice (--enable-charconv resp.
DCMTK_ENABLE_CHARSET_CONVERSION).

DCMTK currently has no mechanism to force including a certain <iconv.h> instead,
so this has to be achieved by manually modifying the include paths and/or
DCMTK's code.  Some platforms (e.g. Arch Linux) even rename the <iconv.h>
provided as part of libiconv to <libiconv.h> or the like to avoid name
collisions.  In this case, the user has to modify DCMTK's source code to include
the correct file, since we currently don't provide a configuration test for it.


Using the native STL
====================

DCMTK can be configured to use the STL (Standard Template Library) features
provided by the compiler / runtime environment instead of its own fallback
implementations that are used by default.

This can be achieved with the "--enable-stl" argument (Autoconf) or by setting
"DCMTK_ENABLE_STL" to "ON" (CMake).  This will, however, not forcibly enable
using the native STL features but instead trigger running several configuration
tests for detecting whether the individual features work as expected/required
by DCMTK.  It is for example known that the implementations of std::list and
std::vector provided by some versions of Visual Studio 2005 have a serious bug
that might lead to segmentation fault and std::error_code is currently not
implemented correctly on any version of Visual Studio we know about.

It is furthermore possible to enable or disable individual STL features
independently of the setting provided by "--enable-stl" or "DCMTK_ENABLE_STL"
respectively: use "--enable-stl-<feature>", "--disable-stl-<feature>" and/or
"DCMTK_ENABLE_STL_<FEATURE> (ON/OFF)" as appropriate, e.g.
"--disable-stl-vector" or "-DDCMTK_ENABLE_STL_STRING=ON".


SUPPORT FOR MODERN C++ STANDARDS
================================

DCMTK can be configured to use several features of modern C++ standards (e.g.
C++11 move semantics, variadic templates and the like) instead of its own
workarounds and fallback implementations.  This can be achieved using CMake's
variables "CMAKE_CXX_STANDARD" and "CMAKE_CXX_STANDARD_REQUIRED".
The previous mechanism only handled C++11 and is available on old versions of
CMake (versions prior 3.1.3): set "DCMTK_ENABLE_CXX11" to "ON".  For Autoconf,
use the "--enable-cxx11" argument.  Both the "DCMTK_ENABLE_CXX11" variable and
Autoconf support are now deprecated and will be removed in a future release.

Enabling e.g. C++11 will change some parts of DCMTK's API, so a C++11 build of
DCMTK is potentially incompatible with a classic build of DCMTK.  This setting
is, therefore, stored in "config/include/dcmtk/config/osconfig.h" and verified
when compiling DCMTK itself or any program that includes it.

Setting CMAKE_CXX_STANDARD to '11' or some newer C++ standard will not forcibly
enable DCMTK to use the respective features but instead trigger running some
configuration tests and only truly enable the features that are really
supported (e.g. std::error_code is still not implemented as intended on newer
versions of Visual Studio, so we keep using DCMTK's own implementation there).

Please note that this setting does not depend on enabling the STL features but
not all combinations (e.g. enabling C++11 but disabling std::string) may work.


BUILDING
========

CMake is now the default tool for configuring a DCMTK build. 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 https://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.

DCMTK 3.6.6 requires CMake version 2.8.5 or later.  We recommend using the
latest stable release of CMake (currently version 3.19.2) since newer versions
of CMake often provide better output in case of errors and are generally easier
to use (for example by providing better support for detecting the availability
of third party libraries).  If possible, use the CMake version your operating
system provides with its package manager.

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

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

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

The CMake build system allows for 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_LIBS" 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.

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 fixated by CMake and cannot be changed otherwise.
Please note that Visual Studio ignores CMAKE_BUILD_TYPE and always starts off
using "Debug", so you should best change it to "Release" manually before
starting the build process.

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

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

Using CMake is the only supported way to compile DCMTK for Windows.  For being
able to do so, perform the following steps to install CMake on your machine:

1. Go to https://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 or ICU) 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.6".
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-msvc15".
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 (e.g. "Visual Studio 15 2017 Win64").
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.9.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.6.37"

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

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

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

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

   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:
       "dcmtkcrypto_d.lib" - debug version
       "dcmtkcrypto_o.lib" - release version (optimized)
       "dcmtkssl_d.lib"    - debug version
       "dcmtkssl_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 ICU is integrated using CMake's "find_package()" mechanism, which is
   somewhat different to the handmade scripts employed for the other libraries.
   If you want to use the ICU instead of libiconv, you have to include it by
   setting the appropriate variables for the "FindICU" module, see
   https://cmake.org/cmake/help/latest/module/FindICU.html .

   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 https://www.dcmtk.org/dcmtk#lib-win.

   In the CMake GUI, there are a few more settings that can be modified
   to affect the way DCMTK is compiled. The most important of these are:

    - DCMTK_OVERWRITE_WIN32_COMPILER_FLAGS: By default, DCMTK will compile
      using the default compiler options selected by CMake. When this macro
      is enabled, these default options are modified based on the value
      of the DCMTK_COMPILE_WIN32_MULTITHREADED_DLL setting (see below).
      Default: ON.
    - DCMTK_COMPILE_WIN32_MULTITHREADED_DLL: Controls the Windows build
      model. When this setting is ON, DCMTK compiled with the
      "Multithreaded DLL" build model (/MD or /MDd); when the setting is
      OFF, DCMTK is compiled with the "Multithreaded" build model
      (/MT or /MTd). This setting is ignored unless the
      DCMTK_OVERWRITE_WIN32_COMPILER_FLAGS option is ON.
      Default: OFF.
    - BUILD_SHARED_LIBS: Build the DCMTK libraries as shared libraries.
      This setting overrides the value of the options
      DCMTK_OVERWRITE_WIN32_COMPILER_FLAGS and
      DCMTK_COMPILE_WIN32_MULTITHREADED_DLL, which are both set to ON.
      Default: OFF.
    - BUILD_SINGLE_SHARED_LIBRARY: Build a single shared library for the
      whole toolkit. This setting overrides the value of the option
      BUILD_SHARED_LIBS, which is set to ON. Default: OFF.

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.


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

One key difference when using CMake for building on Unix like systems is that we
use the "find_package()" mechanism for all external libraries and not just the
ICU.  Most Unix like systems provide a package manager or even if not at least
have a consistent approach for where the libraries and include files are
installed such that the CMake "find_package()" mechanism typically finds them
out of the box.

If that does not work or you want to use a different version of a library than
the one in the default search paths, you should look at the documentation of the
respective "find_package()" module to find out which variables need to be
modified, e.g. "FindZLIB" to control which version of the zlib will be used:
https://cmake.org/cmake/help/latest/module/FindZLIB.html .

The typical way to build DCMTK on Unix like systems with CMake is as follows
(if not using the GUI, in that case look at the description for Windows above):

    mkdir dcmtk-3.6.6-build
    cd dcmtk-3.6.6-build
    cmake ../dcmtk-3.6.6
    make -j8
    make DESTDIR=../dcmtk-3.6.6-install install

The above commands assume that the DCMTK source code was extracted to the
current working directory into a folder named dcmtk-3.6.6.  DCMTK will be
configured using CMake with the default options, detecting and including all
available support libraries and then compiled using eight CPU cores
('make -j8', adjust as needed).  The result will be installed to the directory
"dcmtk-3.6.6-install" next to the source code directory.

If you want to modify your build configuration, like enabling or disabling
some features of DCMTK (e.g. PNG support), or if you need to modify the
predefined build-variables, you can use the curses based cmake configuration
tool 'ccmake'.  First, create the initial build setup (system check) and then
call ccmake:

    mkdir dcmtk-3.6.6-build
    cd dcmtk-3.6.6-build
    cmake ../dcmtk-3.6.6
    ccmake ../dcmtk-3.6.6

Now you can modify the configuration values.  Please see the help on the bottom
of the screen.  When finished, press 'c' to generate a new build configuration,
then quit ccmake.  Now you can continue to build by calling 'make' etc.

If you already know the variable names, types and values to set, you can skip
the 'ccmake' step above and can call 'cmake' directly with the values set.
Example for a build with TCP wrapper disabled:

    mkdir dcmtk-3.6.6-build
    cd dcmtk-3.6.6-build
    cmake -DDCMTK_WITH_WRAP:BOOL=FALSE ../dcmtk-3.6.6
    ...

The format is NAME:TYPE=VALUE.  Use 'ccmake' to find out the variable names and
their types (BOOL with TRUE/FALSE or STRING).  Some of the more important
variables are:

    - BUILD_APPS: Build the DCMTK command line tools? Default: ON.
    - BUILD_SHARED_LIBS: Build the DCMTK libraries as shared libraries?
      Default: OFF.
    - CMAKE_BUILD_TYPE: Debug or Release build, default: Release.
    - CMAKE_INSTALL_PREFIX: Installation prefix, default: /usr/local.
    - DCMTK_ENABLE_BUILTIN_DICTIONARY: Activate the built-in DICOM data
      dictionary? Default: ON on Windows, OFF on Linux/Posix.
    - DCMTK_ENABLE_CXX11: Assume the compiler is C++11 compliant. Default: OFF.
    - DCMTK_ENABLE_STL: Replace DCMTK's OFString, OFList, OFVector etc. by
      the STL classes std::string, std::list, std::vector etc. Default: OFF.
    - OPENSSL_ROOT_DIR: Directory where OpenSSL is installed.
      Default: search in standard directories for headers and libraries.


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.6" 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, dcmect, dcmfg, dcmiod, dcmimage, dcmimgle, dcmjpeg,
dcmpmap, dcmpstat, dcmrt, dcmseg, dcmsign, dcmsr, dcmtls, dcmtract, 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".


DICOM DATA DICTIONARY
=====================

Almost all DCMTK tools and libraries require the so-called DICOM data dictionary
(i.e. information from part 6 of the DICOM standard) to be available in order
to map the attribute tags to their associated Value Representation (VR), Value
Multiplicity (VM) and attribute name (official keyword).  The data dictionary
can either be loaded from file (default on Unix systems) or be built into the
respective tool / dcmdata library (default on Windows systems).  The default
behavior can be changed using appropriate configuration options.

Details can be found in the documentation file at "dcmdata/docs/datadict.txt"
(or "/usr/local/share/doc/dcmtk/datadict.txt").


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 that 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 that 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.  Some tests are
marked as exhaustive and are only run if explicitly enabled, see below.

When using Autoconf 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.  Additionally, you may run the exhaustive unit tests by
typing "make check-exhaustive".

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.  Additionally, you may run the exhaustive unit tests by
typing "make test-exhaustive".  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.


BUILDING (Unix with Autoconf)
=============================

Configuring a DCMTK build with GNU Autoconf has been deprecated with DCMTK
release 3.6.6 and will be removed in future releases.  In the current release,
the "configure" script in DCMTK's top-level main directory has been removed
as the final warning for users of the Autoconf toolchain.  If you prefer to
build DCMTK with Autoconf, however, this is still possible.  Perform the
following steps from the top-level (dcmtk-3.6.6) directory to compile and
install the software:

Step 0:
    cd config
    ./rootconf
    cd ..

Step 0 creates the configure script in DCMTK's top-level directory.

Step 1:
    ./configure --ignore-deprecation

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 --ignore-deprecation --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.1.1i", then you should start configure
as:

    ./configure --ignore-deprecation
                --with-opensslinc=/usr/local/apps/openssl-1.1.1i

Configure will assume that the OpenSSL include files are installed in
"/usr/local/apps/openssl-1.1.1i/include" and will expect the library in
"/usr/local/apps/openssl-1.1.1i/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 --ignore-deprecation
                --with-libzlibinc=/usr/local/apps/zlib-1.2.11
                --with-libtiffinc=/usr/local/apps/libtiff-4.1.0
                --with-libpnginc=/usr/local/apps/libpng-1.6.37
                --with-libxmlinc=/usr/local/apps/libxml2-2.9.10
                --with-libwrapinc=/usr/local/apps/tcp_wrappers-7.6
                --with-libiconvinc=/usr/local/apps/libiconv-1.16
           <or>
                --with-libicuinc=/usr/local/apps/icu-68.1.0

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-private-tags   enable private tag dictionary
  --disable-private-tags  don't enable private tag dictionary (default)
  --enable-external-dict  enable loading of external dictionary (default)
  --disable-external-dict don't load external dictionary
  --enable-builtin-dict   enable loading of built-in dictionary
  --disable-builtin-dict  don't load built-in dictionary (default)
  --disable-rpath         do not hardcode runtime library paths
  --enable-charconv=TYPE  enable character set conversion support
                          (libiconv/libicu/stdlibc/auto=default)
  --disable-charconv      disable character set conversion support
  --enable-cxx11          use C++11
  --disable-cxx11         do not use C++11 (default)
  --enable-stl            use C++ STL
  --disable-stl           do not use C++ STL (default)

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 with Autoconf
------------------------------------------------------------

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 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 https://forum.dcmtk.org/faq for more hints.

---------

Have fun.

M. Eichelberg, J. Riesmeier, M. Onken, J. Schlamelcher, P. Arizpe Gomez
DCMTK Development Team, Oldenburg, Germany.

Last revised: 2021-02-25 (Riesmeier)