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")