catkin_ What did package do

Reference resources ：
https://answers.ros.org/question/58498/what-is-the-purpose-of-catkin_depends/
https://docs.ros.org/en/api/catkin/html/dev_guide/generated_cmake_api.html#catkin-package

We're in some ros The feature pack CMakeLists You can often see in the document catkin_package

catkin_package(
  CATKIN_DEPENDS
    diagnostic_updater
    dynamic_reconfigure
    geometry_msgs
    nav_msgs
    rosbag
    roscpp
    sensor_msgs
    std_srvs
    tf2
    tf2_msgs
    tf2_ros
  INCLUDE_DIRS include
  LIBRARIES amcl_sensors amcl_map amcl_pf
)

catkin_package It's for downstream （ Packages that use this package ） The use of , It is used for Export dependencies to other packages , These dependencies may be the public header files provided by this package to other packages 、 library , Or other packages that this package depends on .

It has 5 An option ：

## The catkin_package macro generates cmake config files for your package
## Declare things to be passed to dependent projects
## INCLUDE_DIRS: uncomment this if you package contains header files
## LIBRARIES: libraries you create in this project that dependent projects also need
## CATKIN_DEPENDS: catkin_packages dependent projects also need
## DEPENDS: system dependencies of this project that dependent projects also need
## CFG_EXTRAS: Additional configuration options
catkin_package(...

DEPENDS and CATKIN_DEPENDS To tell catkin Which dependencies of your package need to be , Pass to use find_package(...) Find your package's package .

for example , Suppose you call find_package(Boost REQUIRED), And in the header file of your installation #include <boost/function.hpp>. To enable a package that depends on your package to build and connect your header files , They need to be in their own include The path contains Boost Of include Catalog , You also need to connect Boost The library of .

Because you have exported the dependency in the header file , They should be able to rely on you . That is, they no longer need find_package(Boost REQUIRED) , Because they are built using your package , Instead of using it directly Boost.

Your package depends on Boost This fact is an implementation detail , So when some packages pass find_package(...) When looking for your bag , They can indirectly get the right Boost Dependence . The way to make this mechanism work is in your catkin_package(...) Add in call DEPENDS Boost. In the internal ,catkin take find_package(Boost), And to ${your_pkg_LIBRARIES} add to ${Boost_LIBRARIES} , towards ${your_pkg_INCLUDE_DIRS} add to ${Boost_INCLUDE_DIRS}. So other packages , Just link ${your_pkg_INCLUDE_DIRS} 、${your_pkg_LIBRARIES} You can get the passed dependencies .

We should pay attention ,catkin Pass the exact package name you told it to find_package() To find the package , Then try to use the package's _LIBRARIES and _INCLUDE_DIRS Variable . however find_package(...) The form of the resulting variable is not always the same , because CMake This operation is not enforced . For example, when find_package(...) Python when ,find_package(PythonLibs REQUIRED) The result variable of is in the form of PYTHON_INCLUDE_PATH,find_package(OpenGL REQUIRED) The result variable is OPENGL_INCLUDE_DIR. Except that the variable prefix becomes different （PythonLibs -> PYTHON）, Suffixes have also become nonstandard （PYTHON_INCLUDE_PATH and OPENGL_INCLUDE_DIR vs *_INCLUDE_DIRS）. In this case, you need to use INCLUDE_DIRS Options and LIBRARIES Options. . in addition , Own exposed header file 、 The library should also pass the option INCLUDE_DIRS、LIBRARIES Pass out （ See the following example foo）.

CATKIN_DEPENDS Options and DEPENDS The options are very similar , But you can only place... In its list catkin Package . take catkin The advantage of setting dependency as a separate option is that it allows catkin Perform some additional checks , Then warn you what's wrong .

cmake_minimum_required(VERSION 2.8.3)
project(foo)

find_package(Boost REQUIRED COMPONENTS
  system
  thread
)

find_package(PythonLibs REQUIRED)
find_package(OpenGL REQUIRED)

find_package(catkin REQUIRED COMPONENTS
  rosconsole
  roscpp
)

include_directories(
  include
  ${catkin_INCLUDE_DIRS}
  ${OPENGL_INCLUDE_DIR}
  ${PYTHON_INCLUDE_PATH}
)

catkin_package(
  INCLUDE_DIRS include ${OPENGL_INCLUDE_DIR}
  LIBRARIES foo ${OPENGL_LIBRARIES}
  CATKIN_DEPENDS roscpp
  DEPENDS Boost
)

...

In this example, you can see me find_package(Boost...) And pass it to catkin_package() Of DEPENDS part , Because it generates compatible CMake The variable of . I find_package(PythonLibs...) And use it internally , But you don't have to pass it on to catkin_package(), Because I didn't include it in any of my exported header files . I find_package(OpenGL...) , Because it is not compatible CMake The variable of , So I passed it to catkin_package() Of NCLUDE_DIRS and LIBRARIES part . Last , I find_package(catkin ... rosconsole roscpp, And used internally , But I may only be .c* The file uses rosconsole, So I don't have to pass it , therefore catkin_package() Of CATKIN_DEPENDS Part I just need to put roscpp.

Finally, but , If a package has direct use, like Boost Such dependencies , Then they should make sure to use find_package(...) Find it explicitly , Instead of implicitly relying on it through other packages . For example , If package foo take Boost Export as a dependency , Another package bar Depend on foo, But it is also used internally Boost, that bar Even when no dependencies are shown Boost It can also be compiled normally . But later foo May decide to refactor and delete it for Boost Dependence , So now bar Will not compile , Because it no longer has the ability to pass foo That's right Boost The implicit dependency of .

We just discussed above catkin_package Use of , There is no detail on how it works .catkin_package After the call, it will be in The installation directory /share/<project_name>/cmake Generate under directory cmake config Pattern lookup file ：<project_name>Config.cmake, <project_name>-version.cmake. In this way, other packages call find_package These configuration files will be loaded when , So as to get the necessary dependence .

Generated xxConfig.cmake The file mainly deals with the above options , library 、 The header file , rely on , Append search results to <project_name>_LIBRARY_DIRS,<project_name>__INCLUDE_DIRS Variable .

Appendix one xxConfig.cmake Examples of documents , It is based on catkin/cmake/template/pkgConfig.cmake.in template-generated . My bag is called test.

# generated from catkin/cmake/template/pkgConfig.cmake.in

# append elements to a list and remove existing duplicates from the list
# copied from catkin/cmake/list_append_deduplicate.cmake to keep pkgConfig
# self contained
macro(_list_append_deduplicate listname)
  if(NOT "${ARGN}" STREQUAL "")
    if(${listname})
      list(REMOVE_ITEM ${listname} ${ARGN})
    endif()
    list(APPEND ${listname} ${ARGN})
  endif()
endmacro()

# append elements to a list if they are not already in the list
# copied from catkin/cmake/list_append_unique.cmake to keep pkgConfig
# self contained
macro(_list_append_unique listname)
  foreach(_item ${ARGN})
    list(FIND ${listname} ${_item} _index)
    if(_index EQUAL -1)
      list(APPEND ${listname} ${_item})
    endif()
  endforeach()
endmacro()


# pack a list of libraries with optional build configuration keywords
# copied from catkin/cmake/catkin_libraries.cmake to keep pkgConfig
# self contained
macro(_pack_libraries_with_build_configuration VAR)
  set(${VAR} "")
  set(_argn ${ARGN})
  list(LENGTH _argn _count)
  set(_index 0)
  while(${_index} LESS ${_count})
    list(GET _argn ${_index} lib)
    if("${lib}" MATCHES "^(debug|optimized|general)$")
      math(EXPR _index "${_index} + 1")
      if(${_index} EQUAL ${_count})
        message(FATAL_ERROR "_pack_libraries_with_build_configuration() the list of libraries '${ARGN}' ends with '${lib}' which is a build configuration keyword and must be followed by a library")
      endif()
      list(GET _argn ${_index} library)
      list(APPEND ${VAR} "${lib}${CATKIN_BUILD_CONFIGURATION_KEYWORD_SEPARATOR}${library}")
    else()
      list(APPEND ${VAR} "${lib}")
    endif()
    math(EXPR _index "${_index} + 1")
  endwhile()
endmacro()

# unpack a list of libraries with optional build configuration keyword prefixes
# copied from catkin/cmake/catkin_libraries.cmake to keep pkgConfig
# self contained
macro(_unpack_libraries_with_build_configuration VAR)
  set(${VAR} "")
  foreach(lib ${ARGN})
    string(REGEX REPLACE "^(debug|optimized|general)${CATKIN_BUILD_CONFIGURATION_KEYWORD_SEPARATOR}(.+)$" "\\1;\\2" lib "${lib}")
    list(APPEND ${VAR} "${lib}")
  endforeach()
endmacro()


if(test_CONFIG_INCLUDED)
  return()
endif()
set(test_CONFIG_INCLUDED TRUE)

# set variables for source/devel/install prefixes
if("FALSE" STREQUAL "TRUE")
  set(test_SOURCE_PREFIX /data/src/utils/test)
  set(test_DEVEL_PREFIX /data/devel_buzzard_isolated/test)
  set(test_INSTALL_PREFIX "")
  set(test_PREFIX ${test_DEVEL_PREFIX})
else()
  set(test_SOURCE_PREFIX "")
  set(test_DEVEL_PREFIX "")
  set(test_INSTALL_PREFIX /data/install_buzzard_isolated)
  set(test_PREFIX ${test_INSTALL_PREFIX})
endif()

# warn when using a deprecated package
if(NOT "" STREQUAL "")
  set(_msg "WARNING: package 'test' is deprecated")
  # append custom deprecation text if available
  if(NOT "" STREQUAL "TRUE")
    set(_msg "${_msg} ()")
  endif()
  message("${_msg}")
endif()

# flag project as catkin-based to distinguish if a find_package()-ed project is a catkin project
set(test_FOUND_CATKIN_PROJECT TRUE)

if(NOT "include " STREQUAL " ")
  set(test_INCLUDE_DIRS "")
  set(_include_dirs "include")
  if(NOT " " STREQUAL " ")
    set(_report "Check the issue tracker '' and consider creating a ticket if the problem has not been reported yet.")
  elseif(NOT " " STREQUAL " ")
    set(_report "Check the website '' for information and consider reporting the problem.")
  else()
    set(_report "Report the problem to the maintainer 'Jiaheng Hong <[email protected]>' and request to fix the problem.")
  endif()
  foreach(idir ${_include_dirs})
    if(IS_ABSOLUTE ${idir} AND IS_DIRECTORY ${idir})
      set(include ${idir})
    elseif("${idir} " STREQUAL "include ")
      get_filename_component(include "${test_DIR}/../../../include" ABSOLUTE)
      if(NOT IS_DIRECTORY ${include})
        message(FATAL_ERROR "Project 'test' specifies '${idir}' as an include dir, which is not found.  It does not exist in '${include}'.  ${_report}")
      endif()
    else()
      message(FATAL_ERROR "Project 'test' specifies '${idir}' as an include dir, which is not found.  It does neither exist as an absolute directory nor in '/data/install_buzzard_isolated/${idir}'.  ${_report}")
    endif()
    _list_append_unique(test_INCLUDE_DIRS ${include})
  endforeach()
endif()

set(libraries "")
foreach(library ${libraries})
  # keep build configuration keywords, target names and absolute libraries as-is
  if("${library}" MATCHES "^(debug|optimized|general)$")
    list(APPEND test_LIBRARIES ${library})
  elseif(TARGET ${library})
    list(APPEND test_LIBRARIES ${library})
  elseif(IS_ABSOLUTE ${library})
    list(APPEND test_LIBRARIES ${library})
  else()
    set(lib_path "")
    set(lib "${library}-NOTFOUND")
    # since the path where the library is found is returned we have to iterate over the paths manually
    foreach(path /data/install_buzzard_isolated/lib;/data/install_buzzard_isolated/lib)
      find_library(lib ${library}
        PATHS ${path}
        NO_DEFAULT_PATH NO_CMAKE_FIND_ROOT_PATH)
      if(lib)
        set(lib_path ${path})
        break()
      endif()
    endforeach()
    if(lib)
      _list_append_unique(test_LIBRARY_DIRS ${lib_path})
      list(APPEND test_LIBRARIES ${lib})
    else()
      # as a fall back for non-catkin libraries try to search globally
      find_library(lib ${library})
      if(NOT lib)
        message(FATAL_ERROR "Project '${PROJECT_NAME}' tried to find library '${library}'.  The library is neither a target nor built/installed properly.  Did you compile project 'test'?  Did you find_package() it before the subdirectory containing its code is included?")
      endif()
      list(APPEND test_LIBRARIES ${lib})
    endif()
  endif()
endforeach()

set(test_EXPORTED_TARGETS "")
# create dummy targets for exported code generation targets to make life of users easier
foreach(t ${test_EXPORTED_TARGETS})
  if(NOT TARGET ${t})
    add_custom_target(${t})
  endif()
endforeach()

set(depends "glog_vendor;grpc_vendor")
foreach(depend ${depends})
  string(REPLACE " " ";" depend_list ${depend})
  # the package name of the dependency must be kept in a unique variable so that it is not overwritten in recursive calls
  list(GET depend_list 0 test_dep)
  list(LENGTH depend_list count)
  if(${count} EQUAL 1)
    # simple dependencies must only be find_package()-ed once
    if(NOT ${test_dep}_FOUND)
      find_package(${test_dep} REQUIRED NO_MODULE)
    endif()
  else()
    # dependencies with components must be find_package()-ed again
    list(REMOVE_AT depend_list 0)
    find_package(${test_dep} REQUIRED NO_MODULE ${depend_list})
  endif()
  _list_append_unique(test_INCLUDE_DIRS ${${test_dep}_INCLUDE_DIRS})

  # merge build configuration keywords with library names to correctly deduplicate
  _pack_libraries_with_build_configuration(test_LIBRARIES ${test_LIBRARIES})
  _pack_libraries_with_build_configuration(_libraries ${${test_dep}_LIBRARIES})
  _list_append_deduplicate(test_LIBRARIES ${_libraries})
  # undo build configuration keyword merging after deduplication
  _unpack_libraries_with_build_configuration(test_LIBRARIES ${test_LIBRARIES})

  _list_append_unique(test_LIBRARY_DIRS ${${test_dep}_LIBRARY_DIRS})
  list(APPEND test_EXPORTED_TARGETS ${${test_dep}_EXPORTED_TARGETS})
endforeach()

set(pkg_cfg_extras "")
foreach(extra ${pkg_cfg_extras})
  if(NOT IS_ABSOLUTE ${extra})
    set(extra ${test_DIR}/${extra})
  endif()
  include(${extra})
endforeach()

xxConfig-version.cmake file ：

# generated from catkin/cmake/template/pkgConfig-version.cmake.in
set(PACKAGE_VERSION "1.0.0")

set(PACKAGE_VERSION_EXACT False)
set(PACKAGE_VERSION_COMPATIBLE False)

if("${PACKAGE_FIND_VERSION}" VERSION_EQUAL "${PACKAGE_VERSION}")
  set(PACKAGE_VERSION_EXACT True)
  set(PACKAGE_VERSION_COMPATIBLE True)
endif()

if("${PACKAGE_FIND_VERSION}" VERSION_LESS "${PACKAGE_VERSION}")
  set(PACKAGE_VERSION_COMPATIBLE True)
endif()

Be careful ：This function must be called before declaring any targets with add_library() or add_executable()

An option is omitted from the above without explanation ,CFG-EXTRAS, Here's an additional explanation .
To be written .