From 35ce14ab43f311cae9544e2d05b331c727033a69 Mon Sep 17 00:00:00 2001
From: Matthias Maier Fix plain text after finalizing!
After finding the deal.II project, we fetch a set of cached variables
- with the link to detailed explanation of the macro below
Every
- Finally, the last two lines define the executable that is to be
- produced and its source code. The link to detailed explanation of the macro below This section covers some advanced topics for a user
- This section covers some advanced topics for a user
+ For complex projects it is desirable to organize source code and header
+files in subdirectories. Assume the following project structure with a
+library "mylib" and an executable "mycode":
+
+
+Please note that
+CMake defines the following variables for access to important directories:
+
+CMakeLists.txt
CMakeLists.txt
CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
@@ -107,27 +113,23 @@ DEAL_II_SETUP_TARGET(mycode)
DEAL_II_INITIALIZE_CACHED_VARIABLES()
macro. You
+ with the
+ DEAL_II_INITIALIZE_CACHED_VARIABLES
macro. You
can inspect these for instance with ccmake
.
CMakeLists.txt
must contain a project definition,
which we do next.
DEAL_II_SETUP_TARGET
macro
- will set up necessary incllude directories, compile defintions and the
- link interface.
+ Finally, the last two lines define the executable that is to be produced
+ and its source code. The
+ DEAL_II_SETUP_TARGET
macro will set up necessary
+ incllude directories, compile defintions and the link interface.
Adding multiple executable targets
@@ -261,8 +263,102 @@ ADD_CUSTOM_TARGET(run COMMAND mycode
Advanced
-CMakeLists.txt
CMakeLIists.txt
file.CMakeLists.txt
file.Source directory layout
+
+
+mylib/source/*.cc
+mylib/include/*.h
+
+mycode/source/*.cc
+mycode/include/*.h
+
+
+In this case the top level CMakeLists.txt
file may be:
+
+# top level CMakeLists.txt
+CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
+FIND_PACKAGE(deal.II 8.0 REQUIRED)
+
+DEAL_II_INITIALIZE_CACHED_VARIABLES()
+PROJECT(myproject)
+
+ADD_SUBDIRECTORY(mylib)
+ADD_SUBDIRECTORY(mycode)
+
+The ADD_SUBDIRECTORY
statement will include the CMakeLists.txt
+file in the specified subdirectory. In our case:
+
+
+# mylib/CMakeLists.txt
+
+INCLUDE_DIRECTORIES(include)
+
+ADD_LIBRARY(mylib
+ source/mylib1.cc
+ source/mylib2.cc
+ )
+
+DEAL_II_SETUP_TARGET(mylib)
+
+
+We have to add the directory include
for the header files to
+the current include directories with the INCLUDE_DIRECTORIES
+statement (see this section for
+details). The corresponding configuration file for the executable looks
+like:
+
+
+# mycode/CMakeLists.txt
+
+INCLUDE_DIRECTORIES(
+ include
+ ${CMAKE_SOURCE_DIR}/mylib/include
+ )
+
+ADD_EXECUTABLE(mycode source/mycode.cc)
+DEAL_II_SETUP_TARGET(mycode)
+
+TARGET_LINK_LIBRARIES(mycode mylib)
+
+
+CMakeLists.txt
files have directory scope.
+Any manipulation of properties and variables have only effect in the
+current directory (and subdirectories, included with
+ADD_SUBDIRECTORY
. The level above will not be affected.
+Therefore, we have to specify the include directories for "mylib" again in
+the subdirectory mycode
- this time with full path
+${CMAKE_SOURCE_DIR}/mylib/include
.
+
+CMAKE_SOURCE_DIR
+ - the source directory (i.e. the directory of the top level
+ CMakeLists.txt file)
+
+CMAKE_BINARY_DIR
+ - the (top level) build directory
+
+CMAKE_CURRENT_SOURCE_DIR
+ - the current source directory, i.e. location of the currently processed
+ CMakeLists.txt file (top level or included via ADD_SUBDIRECTORY)
+
+CMAKE_CURRENT_BINARY_DIR
+ - the build (sub)directory corresponding to CMAKE_CURRENT_SOURCE_DIR
+
+
+
ELSE()
and ENDIF()
.
have a look at the
CMake
documentation for a complete list. Important examples are:
-Link!
IF(${variable}) - the body will be evaluated if the variable "variable" is defined and @@ -360,37 +455,148 @@ source file you have to touch aCMakeLists.txt
file or to run- -
DEAL_II_SETUP_TARGET
revisitedWell, write this!
++The
+DEAL_II_SETUP_TARGET
macro is responsible for setting up a +target to compile and link against deal.II. It will append the +INCLUDE_DIRECTORIES
property with the location of the deal.II +include directories, and the compile definitions and linker flags property +COMPILE_DEFINITIONS
andLINK_FLAGS
by their +respective values (depending on build type and available debug and/or +optimized flavor of the library). ++Except in the case of an object library, the specified target will be set +up to link against deal.II (and its transitive link interface) as well. +
-
DEAL_II_INITIALIZE_CACHED_VARIABLES
revisitedWell, write this!
++The
DEAL_II_INITIALIZE_CACHED_VARIABLES
macro is responsible +for setting up cached variables and has to invoked before the +PROJECT
call: ++FIND_PACKAGE(deal.II 8.0 REQUIRED) + +DEAL_II_INITIALIZE_CACHED_VARIABLES() +PROJECT(myproject) ++The macro will set an uninitializedCMAKE_BUILD_TYPE
variable +toDebug
(orRelease
if the debug library is not +available). IfCMAKE_BUILD_TYPE
is specified it will +automatically be reset if the given value is unsupported by the deal.II +installation. + ++Furthermore, this macro sets the C++ compiler and the compile flags to +default values (the same values that were used to compile deal.II itself). +These are
CMAKE_CXX_COMPILER
andCMAKE_CXX_FLAGS
, +as well as - depending on the configuration - +DEAL_II_FLAGS_DEBUG
, orDEAL_II_FLAGS_RELEASE
, or +both. +Customizing include directories and compile definitions
-Well, write this!
++You can specify custom include directories and compile definitions prior to +a target definition on a per directory basis (have a look at the CMake +documentation for further details): + +
+INCLUDE_DIRECTORIES(include1 include2) + +ADD_DEFINITIONS(-DFOO -DBAR="BAZ") +ADD_EXECUTABLE(...) # or ADD_LIBRARY(...) ++External libraries
-Well, write this!
++For external libraries that provide a CMake project configuration or where +a CMake find module is available, including this external library in your +project is more or less straightforward. E.g. to require an external +project "foo" at least of version 8.0 write: +
+FIND_PACKAGE(foo 8.0 REQUIRED) ++Alternatively, the version number andREQUIRED
keyword can be +omitted. (Depending on the external library) the project configuration or +find macro will usually define variables likeFOO_INCLUDE_DIRS
+andFOO_LIBRARIES
that can be directly used in your +CMakeLists.txt
file: + ++INCLUDE_DIRECTORIES(${FOO_INCLUDE_DIRS}) +ADD_EXECUTABLE(mycode mycode.cc) +DEAL_II_SETUP_TARGET(mycode) + +TARGET_LINK_LIBRARIES(mycode ${FOO_LIBRARIES}) ++The first statement will set up the include directories for the following +targets as explained above. The last statement with +TARGET_LINK_LIBRARIES
will add the libraries in the +FOO_LIBRARIES
variable to the link interface of the target +mycode
. +The "run" target revisited
-Well, write this!
+The simple run statement as explained above will run the generated executable in the +build directory. Sometimes it is more desirable to run the executable in a +dedicated
run
directory within in the build directory which is +a copy of a skeletonrun
folder from the source directory: + ++# Copy folder run from the source to the build directory: +FILE(COPY ${CMAKE_SOURCE_DIR}/run DESTINATION ${CMAKE_BINARY_DIR}) +ADD_EXECUTABLE(mycode mycode.cc) +SET_PROPERTY(TARGET mycode + PROPERTY RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/run + ) +ADD_CUSTOM_TARGET(run + COMMAND mycode + WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/run + ) ++Here, we modify theRUNTIME_OUTPUT_DIRECTORY
property of our +target so that the executable is linked inside our designated +run
folder, so that it is conveniently available as an +executable inside the run folder. Furthermore, we specify a +WORKING_DIRECTORY
for therun
target, so that +make run
invokes the executable inside the intendet run +directory. +Install a project
+If you want the
make install
to install your project to +CMAKE_INSTALL_PREFIX
(that may be set on command line or in +the cache during the configuration stage), add appropriate +INSTALL
statements. To install e.g. a project consisting of a +library and an executable as well as a run folder: + ++# [...] all the target definitions + +INSTALL(TARGETS mylib DESTINATION lib) +INSTALL(TARGETS mycode DESTINATION bin) + +INSTALL(DIRECTORY run DESTINATION share/mycode/run) +Autopilot style CMakeLists.txt
@@ -401,7 +607,7 @@ source file you have to touch aCMakeLists.txt
file or to run versions, running the code and cleaning, the easiest way to write aCMakeLists.txt
file may be to use an "autopilot" style macro. Here is a minimalistic example for the - step-1 tutorial program (plain text version) that can be used for simple projects: @@ -479,7 +685,7 @@ $ cmake . There are two additional configuration options (in addition toTARGET
andTARGET_SRC
) that can be set via variables beforeDEAL_II_INVOKE_AUTOPILOT()
is called - (plain text version): + (plain text version):# (Optional) @@ -507,12 +713,107 @@ SET(TARGET_RUN will set the following variables and macros; all of the formDEAL_II_*
: --A long list with detailed explanation... -- ++# +# General package information: +# + +DEAL_II_PACKAGE_NAME +DEAL_II_PACKAGE_VERSION - the full package version string, e.g. "8.1.pre" +DEAL_II_PACKAGE_VENDOR +DEAL_II_PACKAGE_DESCRIPTION + +DEAL_II_VERSION - version string without suffix, e.g. "8.1" +DEAL_II_VERSION_MAJOR - the major number, e.g. "8" +DEAL_II_VERSION_MINOR - the minor version number, e.g. "1" + +DEAL_II_BUILD_TYPE - the configured build type, e.g. "DebugRelease" +DEAL_II_BUILD_TYPES - an all caps list of available configurations, + e.g. "DEBUG;RELEASE" + +# +# Information about component locations: +# + +DEAL_II_PATH +DEAL_II_CMAKE_MACROS_RELDIR +DEAL_II_COMMON_RELDIR +DEAL_II_DOCREADME_RELDIR +DEAL_II_DOCHTML_RELDIR +DEAL_II_EXAMPLES_RELDIR +DEAL_II_EXECUTABLE_RELDIR +DEAL_II_INCLUDE_RELDIR +DEAL_II_LIBRARY_RELDIR +DEAL_II_PROJECT_CONFIG_RELDIR + +DEAL_II_BUILD_DIR - true if deal.II was picked up from a build + dir, false if the configuration is from an installation + +# +# Compiler and linker configuration +# + +DEAL_II_CXX_COMPILER - the compiler used to compile deal.II + +DEAL_II_CXX_FLAGS - compile flags for all configurations +DEAL_II_CXX_FLAGS_DEBUG - _additional_ compile flags for the debug configuration +DEAL_II_CXX_FLAGS_RELEASE - _additional_ compile flags for the release configuration + +DEAL_II_LINKER_FLAGS - link flags for all configurations +DEAL_II_LINKER_FLAGS_DEBUG - _additional_ link flags for debug configuration +DEAL_II_LINKER_FLAGS_RELEASE - _additional_ link flags for release configuration +DEAL_II_USER_DEFINITIONS - compile definitions for all configurations +DEAL_II_USER_DEFINITIONS_DEBUG - _additional_ compile definitions for debug configuration +DEAL_II_USER_DEFINITIONS_RELEASE - _additional_ compile definitions for release configuration +DEAL_II_STATIC_EXECUTABLE - true if the link interface is set up to + compile resulting executables statically + +# +# Information about include directories and libraries +# + +DEAL_II_INCLUDE_DIRS + +DEAL_II_LIBRARIES_DEBUG - a list of the full link interface for the debug configuration +DEAL_II_LIBRARIES_RELEASE - a list of the full link interface for the release configuration +DEAL_II_LIBRARIES - full list of libraries with "debug" and "optimized" keywords + +# +# Information about library targets +# + +DEAL_II_TARGET_CONFIG - the target config file + +DEAL_II_TARGET_DEBUG - the name of the debug target that is available after inclusion + of the target config file +DEAL_II_TARGET_RELEASE - the name of the release target +DEAL_II_TARGET - full list of targets with "debug" and "optimized" keywords + +# +# Feature configuration: The following booleans are set to "ON" or "OFF" depending +# on the current feature configuration: +# + +DEAL_II_WITH_64BIT_INDICES +DEAL_II_WITH_ARPACK +DEAL_II_WITH_BOOST +DEAL_II_WITH_FUNCTIONPARSER +DEAL_II_WITH_HDF5 +DEAL_II_WITH_LAPACK +DEAL_II_WITH_METIS +DEAL_II_WITH_MPI +DEAL_II_WITH_MUMPS +DEAL_II_WITH_NETCDF +DEAL_II_WITH_P4EST +DEAL_II_WITH_PETSC +DEAL_II_WITH_SLEPC +DEAL_II_WITH_THREADS +DEAL_II_WITH_TRILINOS +DEAL_II_WITH_UMFPACK +DEAL_II_WITH_ZLIB +Legacy Make.global_options
-- 2.39.5