diff --git a/doc/howto/format2/building_executables.rst b/doc/howto/format2/building_executables.rst index f569f8dd9..f58057db8 100644 --- a/doc/howto/format2/building_executables.rst +++ b/doc/howto/format2/building_executables.rst @@ -4,7 +4,12 @@ Building and installing C++ executables --------------------------------------- For this example, suppose you have an executable build target named -``your_node``. +``your_package_node``. + +Although ROS node names are local to the package in which they are +defined, catkin target names must be unique within the catkin +workspace. So, it's best to include the package name in the target +name. Headers ::::::: @@ -22,20 +27,21 @@ needed only if that subdirectory of your source package contains headers used to compile your programs. All your catkin package header dependencies are resolved via ``${catkin_INCLUDE_DIRS}``. -Other :ref:`how_to_do_common_tasks_2` pages describe how to resolve -header dependencies in more detail. +Other :ref:`how-to pages ` describe how to +resolve header dependencies in more detail. Building :::::::: -To build ``your_node``, add this command to your ``CMakeLists.txt``, -listing all required C++ source files, but not the headers:: +To build ``your_package_node``, add this command to your +``CMakeLists.txt``, listing all required C++ source files, but not the +headers:: - add_executable(your_node src1.cpp src2.cpp src_etc.cpp) + add_executable(${PROJECT_NAME}_node src1.cpp src2.cpp src_etc.cpp) If the list of files is long, a CMake variable can help:: - set(YOUR_NODE_SOURCES + set(${PROJECT_NAME}_SOURCES src/file1.cpp src/file2.cpp src/file3.cpp @@ -43,19 +49,19 @@ If the list of files is long, a CMake variable can help:: src/file5.cpp src/file6.cpp src/file_etc.cpp) - add_executable(your_node ${YOUR_NODE_SOURCES}) + add_executable(${PROJECT_NAME}_node ${${PROJECT_NAME}_SOURCES}) If your program depends on libraries provided by other catkin packages, add this:: - add_executable(your_node ${YOUR_NODE_SOURCES}) - target_link_libraries(your_node ${catkin_LIBRARIES}) + add_executable(${PROJECT_NAME}_node ${${PROJECT_NAME}_SOURCES}) + target_link_libraries(${PROJECT_NAME}_node ${catkin_LIBRARIES}) If your program depends on additional non-catkin system libraries, include them in the ``target_link_libraries()``:: - add_executable(your_node ${YOUR_NODE_SOURCES}) - target_link_libraries(your_node + add_executable(${PROJECT_NAME}_node ${${PROJECT_NAME}_SOURCES}) + target_link_libraries(${PROJECT_NAME}_node ${catkin_LIBRARIES} ${Boost_LIBRARIES} ${GSTREAMER_LIBRARIES}) @@ -75,7 +81,7 @@ There are only a few core ROS commands like ``rosrun`` and List all your executables as TARGETS on an install command like this:: - install(TARGETS your_node + install(TARGETS ${PROJECT_NAME}_node RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}) .. _roslaunch: http://wiki.ros.org/roslaunch diff --git a/doc/howto/format2/building_libraries.rst b/doc/howto/format2/building_libraries.rst index 73cc0eec5..83e3f4f12 100644 --- a/doc/howto/format2/building_libraries.rst +++ b/doc/howto/format2/building_libraries.rst @@ -6,11 +6,14 @@ Building and installing C++ libraries and headers In catkin, libraries will be installed in a common directory shared by all the packages in that entire ROS distribution. So, make sure your library names are sufficiently unique not to clash with other packages -or system libraries. +or system libraries. Catkin target names must be unique within the +catkin workspace. So, it's best to include the package name in the +library target name. For this example, suppose you have a shared library build target named -``your_library``. On Linux, the actual file name will be something -like ``libyour_library.so``, perhaps with a version number suffix. +``your_package_library``. On Linux, the actual file name will be +something like ``libyour_package_library.so``, perhaps with a version +number suffix. Headers ::::::: @@ -29,8 +32,8 @@ only if that subdirectory of your source package contains headers used to compile your programs. All your catkin package header dependencies are resolved via ``${catkin_INCLUDE_DIRS}``. -Other :ref:`how_to_do_common_tasks_2` pages describe how to resolve -header dependencies in more detail. +Other :ref:`how-to pages ` describe how to +resolve header dependencies in more detail. Building :::::::: @@ -38,7 +41,7 @@ Building To build your library add this command to your ``CMakeLists.txt``, listing all required C++ source files, but not the headers:: - add_library(your_library libsrc1.cpp libsrc2.cpp libsrc_etc.cpp) + add_library(${PROJECT_NAME}_library libsrc1.cpp libsrc2.cpp libsrc_etc.cpp) If the list of source files is long, a CMake variable can help:: @@ -48,17 +51,17 @@ If the list of source files is long, a CMake variable can help:: libsrc3.cpp libsrc4.cpp libsrc_etc.cpp) - add_library(your_library ${YOUR_LIB_SOURCES}) + add_library(${PROJECT_NAME}_library ${YOUR_LIB_SOURCES}) If your library depends on libraries provided by other catkin packages, add this command:: - target_link_libraries(your_library ${catkin_LIBRARIES}) + target_link_libraries(${PROJECT_NAME}_library ${catkin_LIBRARIES}) If your library depends on additional non-catkin system libraries, include them in the ``target_link_libraries()``:: - target_link_libraries(your_library + target_link_libraries(${PROJECT_NAME}_library ${catkin_LIBRARIES} ${Boost_LIBRARIES} ${GSTREAMER_LIBRARIES}) @@ -74,12 +77,12 @@ all the packages in that entire ROS distribution. So, be careful what you name them. Add these commands to your ``CMakeLists.txt``, substituting all your -library build target names for ``your_library``:: +library build target names for ``${PROJECT_NAME}_library``:: catkin_package(INCLUDE_DIRS include - LIBRARIES your_library) + LIBRARIES ${PROJECT_NAME}_library) - install(TARGETS your_library + install(TARGETS ${PROJECT_NAME}_library ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION} RUNTIME DESTINATION ${CATKIN_GLOBAL_BIN_DESTINATION}) diff --git a/doc/howto/format2/building_msgs.rst b/doc/howto/format2/building_msgs.rst index aad9215aa..0517c2e6a 100644 --- a/doc/howto/format2/building_msgs.rst +++ b/doc/howto/format2/building_msgs.rst @@ -8,29 +8,26 @@ package.xml ::::::::::: Your ``package.xml`` must declare a ```` on -``message_generation``, and a ```` on +``message_generation``, and a ```` on ``message_runtime``:: message_generation - message_runtime + message_runtime Your messages services, or actions will probably include fields defined in other ROS messages, like std_msgs_. Declare them like this:: - std_msgs - std_msgs + std_msgs -Both ```` and ```` are recommended for -message dependencies. That example assumes ``std_msgs`` is the only -dependency. Be sure to mention all your message package dependencies -here, and substitute them all for ``std_msgs`` in the examples that -follow. +The ```` tag is recommended for message dependencies. That +example assumes ``std_msgs`` is the only dependency. Be sure to +mention all your message package dependencies here, and substitute +them all for ``std_msgs`` in the examples that follow. To generate actions, add ``actionlib_msgs`` as a dependency:: - actionlib_msgs - actionlib_msgs + actionlib_msgs CMakeLists.txt @@ -90,7 +87,7 @@ before any programs that depend on them. Every target that directly or indirectly uses one of your message headers must declare an explicit dependency:: - add_dependencies(your_program ${your_package_EXPORTED_TARGETS}) + add_dependencies(your_program ${${PROJECT_NAME}_EXPORTED_TARGETS}) If your build target also uses message or service headers imported from other catkin packages, declare those dependencies similarly:: diff --git a/doc/howto/format2/dynamic_reconfiguration.rst b/doc/howto/format2/dynamic_reconfiguration.rst index 7bd0aad07..7505378c7 100644 --- a/doc/howto/format2/dynamic_reconfiguration.rst +++ b/doc/howto/format2/dynamic_reconfiguration.rst @@ -26,11 +26,9 @@ The remainder of your scripts need not change. package.xml ::::::::::: -You need to declare both build and run-time dependencies on -dynamic_reconfigure_:: +You need to declare your dependency on dynamic_reconfigure_:: - dynamic_reconfigure - dynamic_reconfigure + dynamic_reconfigure CMakeLists.txt :::::::::::::: @@ -45,16 +43,16 @@ scripts:: generate_dynamic_reconfigure_options(cfg/YourNode.cfg) -Since you probably have build targets using the generated header, add -this to ensure it gets built before any targets needing them:: +Include dynamic_reconfigure_ in the CATKIN_DEPENDS exports list for +your package:: - add_dependencies(your_program ${your_package_EXPORTED_TARGETS}) - add_dependencies(your_library ${your_package_EXPORTED_TARGETS}) + catkin_package(CATKIN_DEPENDS dynamic_reconfigure ...) -Finally, include dynamic_reconfigure_ in the CATKIN_DEPENDS exports -list for your package:: +Since you probably have build targets using the generated header, add +this to ensure it gets built before any targets needing them:: - catkin_package(CATKIN_DEPENDS dynamic_reconfigure ...) + add_dependencies(your_program ${${PROJECT_NAME}_EXPORTED_TARGETS}) + add_dependencies(your_library ${${PROJECT_NAME}_EXPORTED_TARGETS}) .. _dynamic_reconfigure: http://wiki.ros.org/dynamic_reconfigure .. _roslib: http://wiki.ros.org/roslib