DCMTKThirdPartyLibrary

Build third party libraries for DCMTK via ExternalProject and custom scripts using Visual Studio, since it is a strong pain to do that by hand.

Required Cache Variables

These cache variables change the behavior of the commands provided by this Module and need to be set to appropriate values before using them. Most of them will be determined automatically via find_XXX as far as possible, but the user may be required to change them as needed:

VCVARS_FILE

This variable will be set based on the used CMake Generator and the resulting compiler detected/provided as CMAKE_C_COMPILER. If detecting the appropriate VCVARS_FILE fails, the user must set in himself.

CYGWIN_BASH

This variable will be initialized via find_program() searching for cygwin.bat etc. and then for a bash.exe close to its location. The result should refer to the bash.exe of a Cygwin installation that will be used to run commands (e.g. make) inside Cygwin.

PERL_EXECUTABLE

This variable will be initialized via find_package() and should refer to an installation of Perl e.g. Strawberry Perl that will be used for configuring libraries that provide Perl based configure scripts.

PATCH_COMMAND

This variable will be initialized via find_program() and should refer to an executable that will be used for applying patches to library source code.

NASM_COMMAND

This variable will be initialized via find_program() using Program Files resp. Program Files (x86) as a HINT depending on whether the chosen compiler targets 32 bit or 64 bit Windows. It should refer to the appropriate installation of The Netwide Assembler for compiling assembly code for the target platform. For newer versions of NASM/Windows, make sure to start the installer as administrator, since otherwise it will be installed to the user’s AppData folder, will not be detected by CMake automatically and potentially lead to problems if both Win32 and Win64 NASM are installed.

Optional Cache Variables

The following variables may modify the module’s behavior (e.g. for detecting the above mentioned variables) but are not required to be set for using the module:

CYGWIN_INSTALL_PATH

This variable will be initialized via find_path() (searching for cygwin.bat or cygwin64.bat) and will be used when searching for CYGWIN_BASH. It is not required if CYGWIN_BASH is set manually.

Read-Only Variables

These read only variables may be used to query certain information for performing the individual builds. They should NOT be modified via set etc.:

TARGET_PLATFORM

This READ ONLY variable will be set to the target platform of the chosen compiler based on the selected CMake Generator etc. Currently possible values are Win64, IA64 and Win32.

TARGET_64BITS

This READ ONLY variable will be set to TRUE in case the target platform is compatible to 64 bit Windows (i.e. Win64 and IA64). It will be set to FALSE otherwise.

CMAKE_WITH_VCVARS_SCRIPT

This READ ONLY variable will refer to a generated batch script that can be used as a drop in replacement for CMAKE_COMMAND, taking the same arguments but ensuring that the appropriate environment is setup using VCVARS_FILE before running CMAKE_COMMAND.

NMAKE_WITH_VCVARS_SCRIPT

This READ ONLY variable will refer to a generated batch script that can be used to run nmake after ensuring that the appropriate environment is setup using VCVARS_FILE. The first argument will be the working directory (use . to keep it unchanged) while additional arguments will be passed to nmake.

CYGWIN_MAKE_SCRIPT

This READ ONLY variable will refer to a generated CMake script that can be executed in CMake script mode (CMAKE_COMMAND -P) for executing make within a CYGWIN_BASH session. It requires the variable SOURCE_DIR to be defined (i.e. via -DSOURCE_DIR:PATH=...) as it will be used as the working directory for running the make command.

CYGWIN_INSTALL_SCRIPT

This READ ONLY variable will refer to a generated CMake script that can be executed in CMake script mode (CMAKE_COMMAND -P) for executing make install within a CYGWIN_BASH session. It requires the variables SOURCE_DIR and INSTALL_DIR to be defined (i.e. via -DINSTALL_DIR:PATH=...) as the former will be used as the working directory for running make and the latter will be used as make DESTDIR=${INSTALL_DIR} install to set the target directory for the installation.

Primary Commands

The following commands provide the core functionality of the DCMTKThirdPartyLibrary module:

DCMTKThirdPartyLibrary_ADD

The DCMTKThirdPartyLibrary_ADD command is used to prepare several CMake cache variables describing a third party library that can then be used in a call to DCMTKThirdPartyLibrary_BUILD_CMake() or DCMTKThirdPartyLibrary_BUILD_CUSTOM() for downloading the source code of a third party library:

DCMTKThirdPartyLibrary_ADD(<NAME>
    <DOWNLOAD_URL>
    <DEFAULT_VERSION>
    <DEFAULT_HASH>
    [<GROUPS>...])

The library <NAME> will be downloaded from <DOWNLOAD_URL> in the version specified as <DEFAULT_VERSION>. The downloaded package will be verified using the hash given as <DEFAULT_HASH> (e.g. “MD5=…”).

The three above mentioned arguments will be stored into the respective CMake cache variables <NAME>_URL, <NAME>_VERSION and <NAME>_HASH, such that a user may replace those values, i.e. to build a different version of the library. If <NAME>_URL contains the string <VERSION>, it will be replaced by the value of <NAME>_VERSION for downloading the library source code.

All additional arguments will be interpreted as GROUPS. A group is essentially a CMake variable referencing several third party libraries via their name, which may for example be used to package certain libraries into one package using DCMTKThirdPartyLibrary_ADD_PACKAGE().

DCMTKThirdPartyLibrary_BUILD_CMake

The DCMTKThirdPartyLibrary_BUILD_CMake command is used to setup an external CMake project for compiling a third party library:

DCMTKThirdPartyLibrary_BUILD_CMake(<NAME>
    [CMAKE_CACHE_ARGS <ARGS>...]
    [CMAKE_CACHE_ARGS_MD <ARGS>...]
    [CMAKE_CACHE_ARGS_MT <ARGS>...]
    ['any additional arguments for ExternalProject_ADD'])

It will use ExternalProject_ADD to create project <NAME>, downloading the source code from the configured URL and verifying the hash(e.g. “MD5=…”). It will use ExternalProject_ADD_STEP to build the library in four different configurations: Debug and Release builds both in combination with /MT and /MD. It will use the same CMake Generator (and Platform if given, e.g. IA64) that was configured for the calling project.

Additional options are:

CMAKE_CACHE_ARGS

a list of initial cache arguments that will be set for the project in all configurations

CMAKE_CACHE_ARGS_MD

a list of initial cache arguments that will be set for the project when using /MD

CMAKE_CACHE_ARGS_MT

a list of initial cache arguments that will be set for the project when using /MT

All additional arguments will be forwarded to ExternalProject_ADD unchanged.

DCMTKThirdPartyLibrary_BUILD_CUSTOM

The DCMTKThirdPartyLibrary_BUILD_CUSTOM command is used to setup an external project for compiling a third party library that uses a custom configuration and build system:

DCMTKThirdPartyLibrary_BUILD_CUSTOM(<NAME>
    [BUILD_IN_SOURCE 1]
    [CONFIGURE_COMMAND <ARGS>...]
    [BUILD_COMMAND <ARGS>...]
    [INSTALL_COMMAND <ARGS>...]
    ['any additional arguments for ExternalProject_ADD'])

It will use ExternalProject_ADD to create project <NAME>, downloading the source code from the configured URL and verifying the hash(e.g. “MD5=…”). It will use ExternalProject_ADD_STEP to build the library in four different configurations: Debug and Release builds both in combination with /MT and /MD. This is realized by configuring the provided commands before passing them to ExternalProject_ADD and ExternalProject_ADD_STEP.

Additional options are:

BUILD_IN_SOURCE 1

same as for ExternalProject_ADD, this option will setup the project to be built inside the source directory. To still build the project in all four different configurations, one additional step target will be added that will create four identical copies of the source directory after the download and patch steps but before the first configure step.

CONFIGURE_COMMAND

The command and arguments that will be executed for configuring the project. Strings like <SOURCE_DIR> will be replaced with the actual value as usual by ExternalProject. In addition the string <CONFIG> will be replaced with MD, MDD`, ``MT and MTD as appropriate while the string <-CONFIG> will be removed in case the config is MD and otherwise replaced with -MDD, -MT and -MTD as needed. Additional variable expansion will be performed after replacing <CONFIG> and <-CONFIG>, such that the string "\${CONFIGURE_SCRIPT_<CONFIG>}" (note the escaped '$' symbol) may be used to address the values of four different variables ${CONFIGURE_SCRIPT_MD}, ${CONFIGURE_SCRIPT_MDD}, ${CONFIGURE_SCRIPT_MT} and ${CONFIGURE_SCRIPT_MTD} as appropriate.

BUILD_COMMAND

The command and arguments that will be executed for compiling the project. Strings like <BUILD_DIR> will be replaced with the actual value as usual by ExternalProject. In addition the string <CONFIG> will be replaced with MD, MDD`, ``MT and MTD as appropriate while the string <-CONFIG> will be removed in case the config is MD and otherwise replaced with -MDD, -MT and -MTD as needed. Additional variable expansion will be performed after replacing <CONFIG> and <-CONFIG>, such that the string "\${MAKE_SCRIPT_<CONFIG>}" (note the escaped '$' symbol) may be used to address the values of four different variables ${MAKE_SCRIPT_MD}, ${MAKE_SCRIPT_MDD}, ${MAKE_SCRIPT_MT} and ${MAKE_SCRIPT_MTD} as appropriate.

INSTALL_COMMAND

The command and arguments that will be executed installing the project Strings like <INSTALL_DIR> will be replaced with the actual value as usual by ExternalProject. In addition the string <CONFIG> will be replaced with MD, MDD`, ``MT and MTD as appropriate while the string <-CONFIG> will be removed in case the config is MD and otherwise replaced with -MDD, -MT and -MTD as needed. Additional variable expansion will be performed after replacing <CONFIG> and <-CONFIG>, such that the string "\${INSTALL_SCRIPT_<CONFIG>}" (note the escaped '$' symbol) may be used to address the values of four different variables ${INSTALL_SCRIPT_MD}, ${INSTALL_SCRIPT_MDD}, ${INSTALL_SCRIPT_MT} and ${INSTALL_SCRIPT_MTD} as appropriate.

All additional arguments will be forwarded to ExternalProject_ADD unchanged.

DCMTKThirdPartyLibrary_ADD_PACKAGE

The DCMTKThirdPartyLibrary_ADD_PACKAGE command is used create a package containing one or more third party libraries built via DCMTKThirdPartyLibrary_BUILD_CMake() or DCMTKThirdPartyLibrary_BUILD_CUSTOM():

DCMTKThirdPartyLibrary_ADD_PACKAGE(<PACKAGE_NAME>
    <MT>
    <CPACK_GENERATOR>
    <LIBRARIES>...)

The command will create a package named <PACKAGE_NAME> and include the third party libraries referred to by the <LIBRARIES> argument. You may use a previously defined library GROUP to pass as such.

The argument <MT> will be used to determine whether the binaries created with /MT and /MTd or the ones created with /MD and /MDd will be packaged.

The <CPACK_GENERATOR> argument will be passed to CPack unchanged, for choosing the type of package that will be created, e.g. ZIP.

Library Specific Commands

The following commands provide library specific functionality, e.g. wrappers around configure_file that prepare the required variables:

DCMTKThirdPartyLibrary_GENERATE_LIBICONV_CONFIGURE_SCRIPT

The DCMTKThirdPartyLibrary_GENERATE_LIBICONV_CONFIGURE_SCRIPT command is used to prepare a CMake script file that can then be used to configure the iconv library for building with the chosen Visual Studio compiler:

DCMTKThirdPartyLibrary_GENERATE_LIBICONV_CONFIGURE_SCRIPT(<SCRIPTFILE>
    <CFLAGS>)

It will generate <SCRIPTFILE> based on the template file ConfigureLibiconv.cmake.in using configure_file providing the following variables:

HOST

"x86_64-w64-mingw32" in case the chosen compiler targets 64 bit

Windows, "i686-w64-mingw32" otherwise.

CFLAGS

as provided via the <CFLAGS> argument.

CXXFLAGS

as provided via the <CFLAGS> argument since libiconv only uses the C compiler anyway and both the C compiler and the C++ compiler will be cl.exe with Visual Studio.

WINDRES_RC

the full path to the provided windres-rc.sh script that will adapt the Windres arguments for Visual Studio’s rc.exe.

CYGWIN_BASH

using the value from the CMake Cache variable.

The generated script file requires the CMake variable SOURCE_DIR to be set at runtime, i.e. must be launched via ${CMAKE_COMMAND} -DSOURCE_DIR:PATH=... -P <SCRIPTFILE>. See the script template file ConfigureLibiconv.cmake.in for more information.

DCMTKThirdPartyLibrary_GENERATE_LIBXML2_CONFIGURE_SCRIPT

The DCMTKThirdPartyLibrary_GENERATE_LIBXML2_CONFIGURE_SCRIPT command is used to prepare a CMake script file that can then be used to configure libxml2 for building with the chosen Visual Studio compiler:

DCMTKThirdPartyLibrary_GENERATE_LIBXML2_CONFIGURE_SCRIPT(<SCRIPTFILE>
    <INCLUDE> <LIB> <CRUNTIME> <DEBUG>)

It will generate <SCRIPTFILE> based on the template file ConfigureLibxml2.cmake.in using configure_file providing the following variables:

INCLUDE

as provided via the <INCLUDE> argument, additional include directories (i.e. for including libiconv).

LIB

as provided via the <LIB> argument, additional linker search paths (i.e. for linking libiconv).

CRUNTIME

as provided via the <CRUNTIME> argument, the Visual Studio runtime option to use, e.g. /MD or /MT.

DEBUG

as provided via the <DEBUG> argument, whether to create a debug build or not. Possible values are yes and no.

The generated script file requires the CMake variables SOURCE_DIR and INSTALL_DIR to be set at runtime, i.e. must be launched via ${CMAKE_COMMAND} -DSOURCE_DIR:PATH=... -DINSTALL_DIR:PATH=... -P <SCRIPTFILE> See the script template file ConfigureLibxml2.cmake.in for more information.

DCMTKThirdPartyLibrary_GENERATE_OPENSSL_CONFIGURE_SCRIPT

The DCMTKThirdPartyLibrary_GENERATE_OPENSSL_CONFIGURE_SCRIPT command is used to prepare a CMake script file that can then be used to configure OpenSSL for building with the chosen Visual Studio compiler:

DCMTKThirdPartyLibrary_GENERATE_OPENSSL_CONFIGURE_SCRIPT(
    <SCRIPTFILE> <MT> <DEBUG>)

It will generate <SCRIPTFILE> based on the template file ConfigureOpenssl.cmake.in using configure_file providing the following variables:

MT

as provided via the <MT> argument, whether to built OpenSSL with /MT or /MD (TRUE=/MT).

DEBUG

as provided via the <DEBUG> argument, whether to build OpenSSL in debug mode. TRUE` will turn ``/MT into /MTd and /MD into /MDd respectively.

CONFIG

either --release or --debug, depending on the value of the <DEBUG> argument.

PLATFORM

"VC-WIN64A", "VC-WIN64I" or "VC-WIN32" depending on the value of TARGET_PLATFORM as appropriate for the OpenSSL Configure Perl scrip platform string.

NASM_COMMAND

using the value from the CMake Cache variable.

PERL_COMMAND

using the value from the CMake Cache variable.

The generated script file requires the CMake variables SOURCE_DIR and INSTALL_DIR to be set at runtime, i.e. must be launched via ${CMAKE_COMMAND} -DSOURCE_DIR:PATH=... -DINSTALL_DIR:PATH=... -P <SCRIPTFILE> See the script template file ConfigureOpenssl.cmake.in for more information.

Helper/Utility Commands

The following commands provide miscellaneous functionality and are for example used to implement above mentioned commands:

DCMTKThirdPartyLibrary_GENERATE_VCVARS_BATCHFILE

The DCMTKThirdPartyLibrary_GENERATE_VCVARS_BATCHFILE command is used to prepare a Windows command prompt batch script that prepares the environment for using the selected compiler and related tools before runnig a user provided command:

DCMTKThirdPartyLibrary_GENERATE_VCVARS_BATCHFILE(
    <SCRIPTFILE> <WORKDIR> <COMMAND> <ARGS>)

The command will create <SCRIPTFILE> using configure_file. The generated script will call the batch file referred to by the variable VCVARS_FILE, use cd to change the working directory to <WORKDIR> and then run the command given by <COMMAND> and provide the string given as <ARGS> as its arguments. The command will convert the paths denoted by <SCRIPTFILE>, <WORKDIR> and <COMMAND> to the Windows path syntax (\ instead of /) and pass them to configure_file as VCVARS_WIN, WORKDIR_WIN and COMMAND_WIN resp.

All other arguments will be ignored.

DCMTKThirdPartyLibrary_MAKE_SCRIPT_FILENAMES

The DCMTKThirdPartyLibrary_MAKE_SCRIPT_FILENAMES command is used to generate different file names for the different configuration options /MD, /MDd, /MT and /MTd:

DCMTKThirdPartyLibrary_MAKE_SCRIPT_FILENAMES(<VAR> <NAME>)

The command will create four different variables using <VAR> as their prefix, e.g. TEST_MD, TEST_MDD, TEST_MT and TEST_MTD for the prefix TEST. It will set those variables to a file name (and path) based on the string provided as <NAME>, that is, the substring <CONFIG> occurring inside <NAME> will be replaced with the respective flag, e.g. MD or MTd.

All other arguments will be ignored.

DCMTKThirdPartyLibrary_PREPARE_BUILD

Replaces the <VERSION> substring inside the download URL (if any) and marks whether a library is built using custom scripts or CMake:

DCMTKThirdPartyLibrary_PREPARE_BUILD(<NAME> <CUSTOM>)

The argument <NAME> specifies the third party library to setup and <CUSTOM> can be either TRUE or FALSE denoting whether the library will be built using custom scripts or using CMake.

All other arguments will be ignored.

DCMTKThirdPartyLibrary_GET_MSVC_VERSION

Determine the Visual Studio version number based on the value of MSVC_VERSION:

DCMTKThirdPartyLibrary_GET_MSVC_VERSION(<VAR>)

The command implements a simple mapping table to help with Visual Studio version number idiosyncrasy. It maps the value of MSVC_VERSION and stores the result into the variable referred to by <VAR>.

All other arguments will be ignored.

DCMTKThirdPartyLibrary_MARK_AS_USED

The command is used to tell CMake that the passed variables are used by the project, such that no warning messages are emitted if the user passes them in a call to cmake -D:

DCMTKThirdPartyLibrary_MARK_AS_USED(<VARIABLES>...)

The variables referred to by <VARIABLES> will be marked as used.

DCMTKThirdPartyLibrary_SCRIPTROOT

READ ONLY variable containing the full path to the related configuration and script templates.