Warning, /EICrecon/docs/design/cmake.md is written in an unsupported language. File is not indexed.
0001 # plugins CMake API
0002
0003 There is a copy/paste CMake file that should automatically create plugin out of sources.
0004
0005 - plugin name is taken from a directory name
0006 - there should be /</plugin name/>/.cc file with `void InitPlugin(JApplication *app)` function
0007
0008
0009 ### Create a plugin:
0010
0011 E.g. if you want to create a plugin named `my_plugin`
0012
0013 - Create a directory `my_plugin`
0014 - Create a file `my_plugin.cc` which will have `InitPlugin` function
0015 - Create `CMakeLists.txt` with the content below
0016 - Add all others files (cmake GLOB is used)
0017
0018 ## Recommended cmake:
0019
0020 Recommended CMake for a plugin:
0021
0022 ```cmake
0023 cmake_minimum_required(VERSION 3.16)
0024
0025 get_filename_component(PLUGIN_NAME ${CMAKE_CURRENT_LIST_DIR} NAME)
0026
0027 # Function creates ${PLUGIN_NAME}_plugin and ${PLUGIN_NAME}_library targets
0028 # Setting default includes, libraries and installation paths
0029 plugin_add(${PLUGIN_NAME} WITH_STATIC_LIBRARY)
0030
0031 # The macro grabs sources as *.cc *.cpp *.c and headers as *.h *.hh *.hpp
0032 # Then correctly sets sources for ${_name}_plugin and ${_name}_library targets
0033 # Adds headers to the correct installation directory
0034 plugin_glob_all(${PLUGIN_NAME})
0035
0036 # Find dependencies
0037 # Uncomment below as needed:
0038 # plugin_add_dd4hep(${PLUGIN_NAME})
0039 # plugin_add_acts(${PLUGIN_NAME})
0040 # plugin_add_cern_root(${PLUGIN_NAME})
0041 plugin_add_event_model(${PLUGIN_NAME})
0042
0043 # Add include directories (works same as target_include_directories)
0044 # plugin_include_directories(${PLUGIN_NAME} SYSTEM PUBLIC ... )
0045
0046 # Add libraries (works similar target_include_directories but for plugin targets)
0047 # plugin_link_libraries(${PLUGIN_NAME} ... )
0048
0049
0050 ```
0051
0052 ## CMake macros:
0053
0054 There are `plugin_...` macros that are slim wrappers trying to minimize an amount of boilerplate
0055 code of each plugin cmake scripts. Macros mimic CMake functions like `target_link_libraries` => `plugin_link_libraries`.
0056
0057
0058 #### plugin_add
0059
0060 ```cmake
0061 # Function creates ${PLUGIN_NAME}_plugin target
0062 # Sets default includes, libraries and installation paths
0063 plugin_add(my_plugin)
0064 ```
0065
0066 It is possible to also automatically create a static library from a plugin
0067 sources in addition to the plugin itself. Adding `WITH_STATIC_LIBRARY` to
0068 `plugin_add`. All other `plugin_xxx` functions will know about the second target then.
0069
0070 ```cmake
0071 # Now function will create 2 targets and ${PLUGIN_NAME}_plugin ${PLUGIN_NAME}_library
0072 # one can add WITH_STATIC_LIBRARY flag to also create a static library with plugin sources
0073 plugin_add(my_plugin WITH_STATIC_LIBRARY)
0074 ```
0075
0076 If `WITH_STATIC_LIBRARY` flag is given, all `plugin_...` macros will work on both targets:
0077 a plugin and a static library.
0078
0079 #### plugin_glob_all
0080
0081 The macro grabs sources as *.cc *.cpp *.c and headers as *.h *.hh *.hpp
0082 Then correctly sets sources for ${plugin_name}_plugin and ${plugin_name}_library
0083 targets (if library is enabled).
0084 Adds headers to the correct installation directory
0085
0086 ```cmake
0087 plugin_glob_all(my_plugin)
0088 ```
0089
0090 #### plugin_sources
0091
0092 Same as target_sources both for library (if enabled) and a plugin.
0093 If library creation is enabled, the function automatically removes
0094 `/</plugin-name/>/.cc` file from library sources
0095
0096 ```cmake
0097 plugin_sources(my_plugin File1.cc File2.cc)
0098 ```
0099
0100 ### plugin_include_directories
0101
0102 Runs target_include_directories for both a plugin and a library (if enabled)
0103
0104 ```cmake
0105 #example
0106 plugin_include_directories(${PLUGIN_NAME} SYSTEM PUBLIC ${ROOT_INCLUDE_DIRS})
0107 ```
0108
0109 ### plugin_link_libraries
0110 Runs target_link_libraries for both a plugin and a library (if enabled)
0111
0112 ```cmake
0113 # example
0114 plugin_link_libraries(${PLUGIN_NAME} ${JANA_LIB})
0115 ```
0116
0117 ### plugin_add_|PACKAGE|
0118
0119 The next snippets combine boiler code for common libraries.
0120 They also try to use packages that are already found.
0121 Consider using them instead of find_packge(...)+plugin_link_libraries+plugin_include_directories
0122
0123
0124 - plugin_add_event_model - podio, edm4hep, edm4eic
0125 - plugin_add_acts - ACTS with version check
0126 - plugin_add_cern_root - CERN ROOT
0127 - plugin_add_dd4hep - dd4hep + Geant4
0128
0129
0130 ```cmake
0131 # podio, edm4hep, edm4eic
0132 plugin_add_event_model(${PLUGIN_NAME})
0133
0134 # acts with common components
0135 plugin_add_acts(${PLUGIN_NAME})
0136
0137 # common cern ROOT libraries & include dirs
0138 plugin_add_cern_root(${PLUGIN_NAME})
0139
0140 # dd4hep
0141 plugin_add_dd4hep(${PLUGIN_NAME})
0142 ```
