Documentation¶
Reason root help¶
reason: Reasonable CMake for C++
Available properties:
- REASON_USE_COTIRE (BOOL): whether to use cotire or not (https://github.com/sakra/cotire)
- REASON_VERBOSE (BOOL): Show debug information
- REASON_BRIEF_PATH (BOOL): Use '~' to replace "${CMAKE_SOURCE_DIR}"
- REASON_EXCLUDE_PULL_DEPENDENCY (LIST):
Do not automatically pull the include dirs and links of the dependency into any target that links to it
i.e. You created a target called 'foo', and it includes 'foo_include' directory and links 'pthread'.
All of a sudden that you'd like to manually deal with dependencies of 'foo', and asks `reason.cmake` to
not to include 'foo_include' and links 'pthread' automatically.
Then, you should add a line of code as following:
list(APPEND REASON_EXCLUDE_PULL_DEPENDENCY "foo")
default: empty
Available commands:
- reason_message
- reason_add_executable
- reason_add_interface_library
- reason_add_library
- reason_add_multiple_tests
- reason_install
- reason_pack_deb
Show command's own help, i.e:
reason(HELP) # show this help
reason_message(HELP) # show `reason_message` command's help
reason_add_executable(HELP) # show `reason_add_executable` command's help
...
reason_add_executable¶
reason_add_executable: reasonable add_executable
params:
- TARGET (STRING): The target name
- FN (STRING): The custom `add_executable` function to use (optional)
- MODE (STRING): The modes you would like to specify reason to build,
currently available: [cuda]
- INC_DIRS (LIST) : Extra include directories (optional)
- SRCS (LIST) : Source files of the library
- LINKS (LIST) : Extra libraries the library should link against (optional)
- DEFINES (LIST) : Extra compile definitions for target
description:
simply wrap 'add_executable', 'target_include_directories', and 'target_link_libraries'
setup rpath, and use cotire if possible
example:
1. Simple, mostly used
reason_add_executable(TARGET demo1 SRCS "src/main.cpp" INC_DIRS "include" LINKS mylib_d)
2. executable with extra compile definitions
reason_add_executable(TARGET demo1 SRCS "src/main.cpp" INC_DIRS "include" DEFINES NDEBUG MY_FLAG=1)
3. Customized 'add_executable' function, i.e. `dummy_add_executable`
reason_add_executable(TARGET demo1 SRCS "src/main.cpp" INC_DIRS "include" LINKS mylib_d FN dummy_add_executable)
4. Use reason to build CUDA project
reason_add_executable(MODE cuda TARGET demo1 SRCS "src/main.cu" INC_DIRS "include" LINKS my_cuda_util_s)
reason_add_interface_library¶
reason_add_interface_library: reasonable add interface/header-only library
params:
- TARGET (STRING): The target name
- INC_DIRS (LIST) : include directories
- HDR_SRCS (LIST) : the header sources (if listed, use them as `target_source`,
else recursive find all files in 'INC_DIRS')
- DEFINES (LIST) : Extra compile definitions for target (optional)
description:
'reason_add_interface_library' will help you create header-only library as target "${TARGET}"
it automatically pulls the include directory if is LINK-ed as dependency with 'target_link_libraries'
or reason's links.
example:
1. Simply use all the files in INC_DIRS
add_interface_library(TARGET "foo" INC_DIRS "include")
2. Specify the header files
add_interface_library(TARGET "foo" INC_DIRS "include"
HDR_SRCS "include/foo/hdr1.hpp" "include/foo/hdr2.hpp")
reason_add_library¶
reason_add_library: reasonable add_library
params:
- STATIC (BOOL) : Whether to build static library (the built static lib is named after "${TARGET}_s")
- SHARED (BOOL) : Whether to build shared library (the built shared lib is named after "${TARGET}_d")
- TARGET (STRING): The target name
- FN (STRING): The custom `add_executable` function to use (optional)
- MODE (STRING): The modes you would like to specify reason to build,
currently available: [cuda]
- INC_DIRS (LIST) : Extra include directories
- SRCS (LIST) : Source files of the library
- LINKS (LIST) : Extra libraries the library should link against
- DEFINES (LIST) : Extra compile definitions for target
description:
'reason_add_library' will build static and shared libraries using '${TARGET}_s' and '${TARGET}_d' as their
corresponding names, if STATIC or SHARED is defined.
The shared library is versioned following the project's version
You do not need to include the 'INC_DIRS' after libraries are built when linking them since cmake
automatically inferred the include directories for you. @see example 4
example:
1. Build both static and shared libraries
project(foo VERSION 1.2.3)
reason_add_library(TARGET foo STATIC SHARED
INC_DIRS "include1" "include2" SRCS "src/foo1.cpp" "src/foo2.cpp"
LINKS ncurses pthread)
- 'libfoo_s.a' and 'libfoo_d.so' are built (shared library is versioned [major.minor]
following the project version)
'libfoo_d.so' --> 'libfoo_d.so.1' --> 'libfoo_d.so.1.2'
- 'include1' and 'include2' directory in ${CMAKE_CURRENT_LIST_DIR} are included
for target foo (target only include, does not pollute other targets)
- links 'libncurses.so' and '-pthread'
2. Build only static library
reason_add_library(TARGET foo STATIC INC_DIRS "include" SRCS "src/foo.cpp")
- Only 'libfoo_s.a' is built
3. Build only shared library
reason_add_library(TARGET foo SHARED INC_DIRS "include" SRCS "src/foo.cpp")
- Only 'libfoo_d.so' is built, and correctly versioned
4. Build and linked by others
reason_add_library(TARGET foo STATIC INC_DIRS "my_foo_include" SRCS "src/foo.cpp")
# ... other cmake code ...
add_executable(main 'src/main.cpp') # where you might do `#include <foo.hpp>`
target_link_libraries(main foo_s) # cmake will automatically include 'my_foo_include' directory for you
5. Build with extra compile definitions
reason_add_library(TARGET foo STATIC SHARED INC_DIRS "include" SRCS "src/foo.cpp" DEFINES NDEBUG MY_FLAG=1
6. Customized 'add_library' function, i.e. `dummy_add_library`
reason_add_library(TARGET foo STATIC SHARED INC_DIRS "include" SRCS "src/foo.cpp" FN dummy_add_library)
7. Use reason to build CUDA project
reason_add_library(MODE cuda TARGET demo1 SRCS "src/main.cu" INC_DIRS "include" LINKS my_cuda_util_s)
reason_install¶
reason_install: reasonable install
params:
- TARGETS (LIST): The target names, including all executables, libraries both static and shared
- INC_DIRS (LIST): Include directories to install
description:
Automatically generates cmake's config file for you. You might use 'find_package' or 'include'
in CMakeLists.txt of other projects to find this package.
exemple:
1. Project with headers
reason_install(TARGETS "demo1" INC_DIRS "include")
2. Project with no headers
reason_install(TARGETS "demo2")