================================== 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 2.95 (most of the development was done using GNU C++ 3.2 on Linux 2.4). The software is also known to compile using the SUNPro 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 between 100 and 250 Mb of disk space to compile all the software. SUPPORTED SYSTEMS ================= Microsoft Windows ----------------- The DCMTK software can be compiled under a native Windows 9x/Me/NT/2000/XP environment (see section "BUILDING (Win32)" below for more information). The current release successfully compiles on the following systems: Windows NT 4.0 / Intel x86 / Microsoft Visual C++ 6.0 (Service Pack 6) Windows XP / 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 / Microsoft Visual C++ .NET 2005 (Visual Studio 8) The dcmqrscp and wlmscpfs tools have been ported to Windows, but do not 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 4.11 / Intel x86 / GNU gcc 2.95.4 FreeBSD 6.0 / Intel x86 / GNU gcc 3.4.4 HP-UX 10.20 / HP PA-RISC / GNU gcc 2.95.3 IRIX 5.3 / SGI Indy / GNU gcc 2.95.2 (see note *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 / x86_64 / GNU gcc 4.0 (Fedora Core 4) 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 OpenBSD 3.8 / Intel x86 / GNU gcc 3.3.5 propolice QNX 6.2.1 / Intel x86 / GNU gcc 2.95.3 (see note *7) 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 9 / Sun Sparc / SunPro CC 5.2 (Sun WorkShop 6 update 1) Solaris 10 / Intel x86 / SunPro CC 5.8 (Sun Studio 11) 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) Earlier releases are known to also compile on the following platforms which are not available to us for testing purposes any more: 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 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 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) NeXTStep 3.3 / Intel x86 / NeXT/GNU gcc 2.5.8 (see note *1) OSF/1 4.0 / DEC Alpha / Compaq C++ V6.3-002 (see note *6) OSF/1 4.0 / DEC Alpha / GNU gcc 2.95.3 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) SunOS 4.1.3 / Sun Sparc / GNU gcc 2.7.2 Ultrix 4.4 / DEC MIPS / GNU gcc 2.95.2 (see notes *2,*3) Windows 9x / Intel x86 / Microsoft Visual C++ 5.0 Platform Notes -------------- (*1) 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. (*2) 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 in the CXXFLAGS setting in the file "config/Makefile.def", which is created by configure (see below). (*3) Requires -fpermissive when compiled with GNU gcc due to the X11R5 header files which are not ANSI compliant. (*4) IRIX 6 users are recommended to consult SGI's Notes on building Open Source software on IRIX, available from: http://toolbox.sgi.com/TasteOfDT/public/freeware/shared/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) Might require -O0 in order to compile "dcmsr/libsrc/dsrdoctr.cc". (*7) 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. 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.4 using GNU C++ 3.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 all 0.9.6, 0.9.7 and 0.9.8 OpenSSL releases. Due to security considerations we recommend that DCMTK should be compiled with OpenSSL 0.9.8a or newer. On Unix platforms, 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. On Windows platforms, 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 compiles without OpenSSL support. 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. Due to security considerations, we recommend that DCMTK should only be used with zlib 1.1.4 or newer. This release also compiles with zlib 1.2.3. On Unix platforms, 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. On Windows platforms, 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.5.7 to 3.7.4, although older releases may work as well. On Unix platforms, 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. On Windows platforms, 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 release 1.2.8, although older releases may work as well. On Unix platforms, 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. On Windows platforms, 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.xmlsoft.org) for this purpose. This release of DCMTK is known to compile with the libxml2 releases 2.5.7 to 2.6.26, although older or newer releases may work as well. On Unix platforms, 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. On Windows platforms, 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, and the libxml2 support must be switched on explicitly (using CMake, see below). By default, DCMTK compiles without libxml2 support. 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. On Unix platforms, 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 a ANSI C compatible header file. On Windows platforms, TCP wrappers are currently not supported. BUILDING (Unix) =============== 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 neccessary 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.5.3) 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 libraries will be installed (in Step 3) in the directory "/usr/local/dicom" in the bin and lib 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/bin" and "~/dicom/lib" 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 OpenSSL. For example, if you wish to enable the security enhancements, and OpenSSL is installed in "/usr/local/apps/openssl-0.9.8a", then you should start configure as: ./configure --with-opensslinc=/usr/local/apps/openssl-0.9.8a Configure will assume that the OpenSSL include files are installed in "/usr/local/apps/openssl-0.9.8a/include" and will expect the library in "/usr/local/apps/openssl-0.9.8a/lib". Appropriate options will be passed to the compiler and the linker. Support for zlib, libtiff, libpng, libxml2 and libwrap 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.3 --with-libtiffinc=/usr/local/apps/libtiff-3.7.4 --with-libpnginc=/usr/local/apps/libpng-1.2.8 --with-libxmlinc=/usr/local/apps/libxml-2.6.26 --with-libwrapinc=/usr/local/apps/tcp_wrappers-7.6 Different configure options can be combined in any order. configure --help will print a list of all existing configure options. 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-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 the "make install-lib". For the HTML documentation (see below) use "make install-html" (requires Doxygen to be installed). 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 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. 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 (Win32) ================ 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. 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 support of external libraries in DCMTK on Windows platforms, 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 new ".dsp" and ".dsw" files (or ".sln" for Visual C++ .NET 2003/2005) for all of DCMTK's projects from these files, depending on a configuration which can be adjusted manually by the user. 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/HTML/Download.html to download the latest release version of CMake for Windows. With regard to a certain CMake version, note that CMake 2.x or later can be used in conjunction with DCMTK. If you want to generate project files for Visual Studio 2005, you need CMake 2.2.x or newer. 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 and libxml2) through CMake, perform the following steps: 1. Go Start -> Programs -> CMake -> CMakeSetup 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 DCMTK is installed, e.g. "C:\dcmtk-3.5.3". 3. In the entry field "Where to build the binaries:" enter the directory in which DCMTK is installed, e.g. "C:\dcmtk-3.5.3". 4. In the combobox "Build for:" select the corresponding development environment which shall be used to compile DCMTK. 5. Go "Configure". (CMake will look for a corresponding compiler and read in all of DCMTK's "CMakeLists.txt" files. The variables in the "Cache Values" area will be displayed in red. These variables can now be set in order to turn the support for any of the external librares 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 "WITH_LIBXML" 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.5.7". The support of all other external libraries can be turned on in a similar way: libpng support: set "WITH_LIBPNG" to "ON" and set "WITH_LIBPNGINC" e.g. to "C:\libpng-1.2.8" libtiff support: set "WITH_LIBTIFF" to "ON" and set "WITH_LIBTIFFINC" e.g. to "C:\tiff-3.7.4" OpenSSL support: set "WITH_OPENSSL" to "ON" and set "WITH_OPENSSLINC" e.g. to "C:\openssl-0.9.8a" zlib support: set "WITH_ZLIB" to "ON" and set "WITH_ZLIBINC" e.g. to "C:\zlib-1.2.3" In order to turn the support of a certain external library off, set the value of the corresponding variable ("WITH_LIBXML", "WITH_LIBPNG", "WITH_LIBTIFF", "WITH_OPENSSL", or "WITH_ZLIB") 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", or "WITH_ZLIBINC"). (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", or "WITH_ZLIBINC". Moreover note that the following filenames must be used for the corresponding lib files: libxml: "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) 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). 7. Go "Configure" a second time. (CMake will adjust the configuration according to the displayed specifications. The variables in the "Cache Values" area will be displayed in grey). 8. Go "OK". (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 Developer 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. 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 and wlmscpfs tools 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 one 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 internet addresses and names are given dynamically). 4. Visual C++ contains two different implementations of iostreams which should never be mixed within one application because this may cause nasal daemons, i.e. 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 behaviour can be changed in "config/include/cfwin32.h" 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! 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. Users who have Doxygen installed can create a hypertext documentation with "make html" in the "dcmtk-3.5.3" or "doxygen" directory. A project file for Microsoft's HTML Help Workshop is also generated by default allowing to create a single CHM file (compressed HTML) from the documentation. Other output formats (e.g. LaTeX) can be enabled manually by changing the configuration file in the doxygen directory. At the current time, dcmimage, dcmimgle, dcmjpeg, dcmpstat, dcmsign, dcmsr, dcmtls, dcmwlm and ofstd are completely documented, dcmdata and dcmnet are partially documented. See FAQ entry: "Where is rest of the documentation?" DOC++ (docpp.sourceforge.net), another source code documentation system, is not actively supported any more. However, it may still work. 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/dicom/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 behaviour 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" There is also a number of environment variables which affect DCMTK's behaviour. These are documented in "config/docs/envvars.txt". --------- Have fun. Marco Eichelberg, Joerg Riesmeier, Thomas Wilkens, Michael Onken Kuratorium OFFIS e.V., Oldenburg, Germany. Last revised: 2005-12-20 (Eichelberg).