Skip to content

Commit

Permalink
format 2 documentation: step 3 (ros#440)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jack-oquin
jack-oquin committed May 13, 2014
1 parent df11e42 commit 89bd5ca
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 48 deletions.
32 changes: 19 additions & 13 deletions doc/howto/format2/building_executables.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

This comment has been minimized.

Sign in to view

Copy link
@dirk-thomas

dirk-thomas May 13, 2014

If it is recommended to prefix the target name with the package name the doc should mention how to override the executable/library name to not contain that prefix (and use that in the following examples).

This comment has been minimized.

Sign in to view

Copy link
@jack-oquin

jack-oquin May 13, 2014

Author Owner

I am not sure exactly what you are recommending.

What more would you like to say?

This comment has been minimized.

Sign in to view

Copy link
@dirk-thomas

dirk-thomas May 13, 2014

While it makes sense to prefix the targets with the package name it also makes sense to not use a prefix when the executable is places in the package specific folder (and later ran through rosrun).

Therefore if recommending to prepend the package name you might also want to mention how to not use the prefix for the executable name - aka setting a different name then implicitly using the target name (set_target_properties() and OUTPUT_NAME).

This comment has been minimized.

Sign in to view

Copy link
@jack-oquin

jack-oquin May 13, 2014

Author Owner

I want to avoid telling people all their possible options. Those are endless.

The goal of all the how-to pages is providing a few sensible examples that actually work.

Would it be better to ignore the catkin workspace naming problems? I didn't even realize it was a problem until recently.

This comment has been minimized.

Sign in to view

Copy link
@dirk-thomas

dirk-thomas May 13, 2014

I would suggest either mentioning both or none.

This comment has been minimized.

Sign in to view

Copy link
@jack-oquin

jack-oquin May 13, 2014

Author Owner

I am still not sure exactly what you want.

I think explaining OUTPUT_NAME is more than is necessary.

Would you prefer going to back to the simpler your_node naming? I don't mind doing it that way.

This comment has been minimized.

Sign in to view

Copy link
@dirk-thomas

dirk-thomas May 13, 2014

I meant that the doc should either:

  • recommend prefixing the targets with the project name and mention OUTPUT_NAME to keep the executable names sane or
  • do not recommend to use the package name as a prefix

This comment has been minimized.

Sign in to view

Copy link
@jack-oquin

jack-oquin May 13, 2014

Author Owner

OK, I'll go back to the your_node notation. With "your_" as a prefix it's probably unique enough. 😄

Headers
:::::::
Expand All @@ -22,40 +27,41 @@ 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 <how_to_do_common_tasks_2>` 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
src/file4.cpp
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})
Expand All @@ -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
Expand Down
27 changes: 15 additions & 12 deletions doc/howto/format2/building_libraries.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
:::::::
Expand All @@ -29,16 +32,16 @@ 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 <how_to_do_common_tasks_2>` describe how to
resolve header dependencies in more detail.

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::

Expand All @@ -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})
Expand All @@ -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})
Expand Down
21 changes: 9 additions & 12 deletions doc/howto/format2/building_msgs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,26 @@ package.xml
:::::::::::

Your ``package.xml`` must declare a ``<build_depend>`` on
``message_generation``, and a ``<run_depend>`` on
``message_generation``, and a ``<exec_depend>`` on
``message_runtime``::

<build_depend>message_generation</build_depend>
<run_depend>message_runtime</run_depend>
<exec_depend>message_runtime</exec_depend>

Your messages services, or actions will probably include fields
defined in other ROS messages, like std_msgs_. Declare them like
this::

<build_depend>std_msgs</build_depend>
<run_depend>std_msgs</run_depend>
<depend>std_msgs</depend>

Both ``<build_depend>`` and ``<run_depend>`` 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 ``<depend>`` 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::
<build_depend>actionlib_msgs</build_depend>
<run_depend>actionlib_msgs</run_depend>
<depend>actionlib_msgs</depend>


CMakeLists.txt
Expand Down Expand Up @@ -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::
Expand Down
20 changes: 9 additions & 11 deletions doc/howto/format2/dynamic_reconfiguration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_::

<build_depend>dynamic_reconfigure</build_depend>
<run_depend>dynamic_reconfigure</run_depend>
<depend>dynamic_reconfigure</depend>

CMakeLists.txt
::::::::::::::
Expand All @@ -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
Expand Down

0 comments on commit 89bd5ca

Please sign in to comment.