Basic structure

Assuming ${PROJ_ROOT} refers to the root repository directory,

${PROJ_ROOT}/CMakeLists.txt – The root cmake file. In general this should only be modified to update the version of WARPXM, as well as increase what version of CMake is required to build WARPXM.
- cmake – This is the base directory for all CMake helper modules.
  - warpxm-doc.cmake – This finds Doxygen and generates documentation targets. In general there is no reason to modify this.
  - Find*.cmake – These are files used for finding dependency modules which are not included in standard CMake installs. See the CMake documentation for how to write these for new dependencies.
  - warpxm-modules.cmake – This scans for all WARPXM dependencies, sets appropriate compiler flags, and creates a list of library dependencies WARPXM_LINK_TARGETS that targets should link to.
  - warpxm-test.cmake – This sets up the testing framework. In general this should not be modified.
- src/CMakeLists.txt – This is the main file for creating a list of WARPXM source files and internal header files. WARPXM source files currently assume all header files can be found directly in one of the base include directories. Currently there is a hack which will scan the src directory for header files and automatically add this directory to the include path. Actual source files are added in the CMakeLists.txt of subdirectories (e.g. apps/CMakeLists.txt) using the add_sources function.
- test/CMakeLists.txt – Base module for adding tests. This is only included if testing is enabled.
- examples/CMakeLists.txt – Base module for adding examples. This is only included if building examples is enabled.

Adding a new dependency

Depending on the dependency, there may already be a built-in CMake module finder available. If so, it can be included using find_package.

Once found, in general the dependency include directory and libraries must be included. Include directories can be added using the include_directories command. Library directories can be added using the link_directories command. Libraries which must be linked to should be appended to the WARPXM_LINK_TARGETS list. C/C++ compiler flags should be appended to CMAKE_C_FLAGS and CMAKE_CXX_FLAGS respectively. Refer to the module's documentation for specific details on what flags are set.

Basic usage:

# find required MyDependency with version 1.0.0 or newer
# assume MyDependency_INCLUDE_DIRS holds all include directories
# assume MyDependency_LIBRARY_DIRS holds all static/shared library directories
# assume MyDependency_LIBRARIES holds all library targets that must be linked to
# assume MyDependency_CXX_COMPILER_FLAGS holds C++ flags specific for MyDependency
 
find_package(MyDependency 1.0.0 REQUIRED)
 
include_directories(${MyDependency_INCLUDE_DIRS})
link_directories(${MyDependency_LIBRARY_DIRS})
list(APPEND WARPXM_LINK_TARGETS ${MyDependency_LIBRARIES})
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${MyDependency_CXX_COMPILER_FLAGS}")

Auto-downloading dependencies

Using ExternalProject_Add, dependencies may be downloaded, built, and installed with minimal user effort. It is highly recommended to refer to the official documentation as this tutorial assumes some knowledge of how to use ExternalProject_Add and other associated commands used.

[Optional] Add two variables determining what version of the project to download, and what version is required.
[Optional] Scan the system for the dependency using find_package. However, do not enable the REQUIRED flag.
Use ExternalProject_Add if the dependency couldn't be found. All internal project directories should set to ${DEPS_SOURCE_DIR}/* (* is specific for the particular dir), and INSTALL_DIR should be set to ${DEPS_INSTALL_DIR}. Refer to the dependencies' build instructions for how to configure/build the dependency. The target should be named dep_*, where * is the dependency name.
Ensure include directories, link directories, and any libraries to link to/compiler flags are set appropriately as shown above in the basic new dependency tutorial.
Append the external dependency project to _DEPS.

Some examples for adding common categories of dependencies:

# warpxm-modules.cmake
 
# MyDep1 is downloaded from an online archive, uses CMake
set(MyDep1_DOWNLOAD_VERSION "1.1.2" CACHE STRING "What version of MyDep1 to download if a local install couldn't be found.")
set(MyDep1_REQUIRED_VERSION "1.0.0")
 
find_package(MyDep1 ${MyDep1_REQUIRED_VERSION})
if(MyDep1_FOUND)
  # ... add include/link directories, libraries, etc.
else()
  message(STATUS "Building MyDep1 from external project")
  ExternalProject_Add(dep_mydep1
    PREFIX ${DEPS_SOURCE_DIR}/mydep1
    SOURCE_DIR ${DEPS_SOURCE_DIR}/mydep1/mydep1/
    BINARY_DIR ${DEPS_SOURCE_DIR}/mydep1/build
    DOWNLOAD_DIR ${DEPS_SOURCE_DIR}
    INSTALL_DIR ${DEPS_INSTALL_DIR}
    STAMP_DIR ${DEPS_SOURCE_DIR}/mydep1/stamp
    URL http://www.mydep1.org/files/mydep1_${MyDep1_DOWNLOAD_VERSION}.tar.gz
    CMAKE_COMMAND CC=${CMAKE_C_COMPILER} CXX=${CMAKE_CXX_COMPILER} ${CMAKE_COMMAND}
    CMAKE_ARGS -DMyDep1Flag=Important
    )
  include_directories(${DEPS_INSTALL_DIR}/include)
  link_directories(${DEPS_INSTALL_DIR}/lib)
  set(MyDep1_LIBRARIES mydep1)
  list(APPEND _DEPS dep_mydep1)
  list(APPEND WARPXM_LINK_TARGETS ${MyDep1_LIBRARIES})
endif()

# warpxm-modules.cmake
 
# MyDep2 is downloaded from a git repo, uses configure
set(Mydep2_DOWNLOAD_VERSION "1.1.2" CACHE STRING "What version of Mydep2 to download if a local install couldn't be found.")
set(Mydep2_REQUIRED_VERSION "1.0.0")
 
find_package(Mydep2 ${Mydep2_REQUIRED_VERSION})
if(Mydep2_FOUND)
  # ... add include/link directories, libraries, etc.
else()
  message(STATUS "Building Mydep2 from external project")
  ExternalProject_Add(dep_mydep2
    PREFIX ${DEPS_SOURCE_DIR}/mydep2
    SOURCE_DIR ${DEPS_SOURCE_DIR}/mydep2/mydep2/
    BINARY_DIR ${DEPS_SOURCE_DIR}/mydep2/build
    DOWNLOAD_DIR ${DEPS_SOURCE_DIR}
    INSTALL_DIR ${DEPS_INSTALL_DIR}
    STAMP_DIR ${DEPS_SOURCE_DIR}/mydep2/stamp
    GIT_REPOSITORY git@github.com/mydep2/mydep2.git
    CONFIGURE_COMMAND CC=${CMAKE_C_COMPILER} CXX=${CMAKE_CXX_COMPILER} ${DEPS_SOURCE_DIR}/configure --prefix=${DEPS_INSTALL_DIR} --use-my-flag=yes
    BUILD_COMMAND make
    INSTALL_COMMAND make install
    )
  include_directories(${DEPS_INSTALL_DIR}/include)
  link_directories(${DEPS_INSTALL_DIR}/lib)
  set(Mydep2_LIBRARIES mydep2)
  list(APPEND _DEPS dep_mydep2)
  list(APPEND WARPXM_LINK_TARGETS ${Mydep2_LIBRARIES})
endif()

Adding a test

TODO

Adding an example

TODO