1 # Using catkin tools and vcs for the SoT {#memo_catkin_tools}
3 \section memo_catkin_tools_intro Introduction
5 This memo explains how to create and handle a super build (set of packages) workspace of the SoT with catkin tools.
6 catkin tools should not confused with catkin_make. They can be installed independently from ROS.
8 Two solutions are possible:
10 * Installing the SoT third party dependency from robotpkg binaries.
11 * Installing the SoT third party dependency from robotpkg sources.
13 The first solution is the fastest and is recommended to stay up-to-date with the core development team.
14 The disadvantage is that the software environment might be unstable if the binary packages are updated continously.
16 To have a stable environment it is possible to freeze the binary packages coming from robotpkg (by imposing the version)
17 or to use the second solution.
19 Practically it is possible to have both the binary packages in ```/opt/openrobots```
20 to follow the latest development and to have the source packages in ```/home/user/own_stable_install```
21 develop your own functionnalities.
23 The last solution is to use docker.
25 \subsection memo_catkin_tools_quick_start Quick start
27 \subsubsection memo_catkin_tools_quick_start_required Required packages
30 Running the following script will install the necessary SoT software dependency, but first you will need a few packages to be able to run it. To install them, run :
32 sudo apt install ccache libncurses5-dev pax texlive-latex-extra doxygen assimp-utils python3-notify2 python3-lark-parser
34 Some ros packages are required as well. For ros melodic you can run:
36 sudo apt install ros-melodic-octomap ros-melodic-orocos-kinematics-dynamics ros-melodic-four-wheel-steering-msgs ros-melodic-urdf-geometry-parser
40 sudo apt install ros-kinetic-octomap ros-kinetic-orocos-kinematics-dynamics ros-kinetic-four-wheel-steering-msgs ros-kinetic-urdf-geometry-parser
42 \subsubsection memo_catkin_tools_quick_start_depends Install dependencies
44 To install the necessary SoT software dependency in ```/path_to_target_dir``` you can simply try:
46 wget -O install-dep-thru-rpkg.sh https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/bash/install-dep-thru-rpkg.sh
47 chmod +x ./install-dep-thru-rpkg.sh
48 ./install-dep-thru-rpkg.sh -p /path_to_target_dir -s /path_to_robotpkg_src
50 This will install the binairies in ```/path_to_target_dir``` and store the sources in ```/path_to_robotpkg_src```.
52 Other options to install the source dependencies are given in \ref memo_preparing_environment.
54 \subsubsection memo_catkin_tools_quick_start_setnv Setup your environment
56 source setup-sot.sh -p /path_to_target_dir -r
57 source setup-sot.sh -p /path_to_sot_ws/install -r
59 \subsubsection _catkin_tools_quick_create_ws Create your workspace
61 You will then need some tools: one for version control, the other for your workspace
63 sudo apt install python3-vcstool python3-catkin-tools
65 Once this is done,to create your SoT workspace using the file [sot_talos.repos](https://github.com/stack-of-tasks/sot-doc/blob/master/config/sot_talos.repos):
67 wget -O install-sot-catkin-ws.sh https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/bash/install-sot-catkin-ws.sh
68 chmod +x ./install-sot-catkin-ws.sh
69 ./install-sot-catkin-ws.sh -p /path_to_sot_ws
71 \subsection memto_catkin_tools_quick_start_explanations Quick start explanations
73 The previous script is doing the following steps:
75 mkdir -p /path_to_sot_ws
77 wget -O sot_talos.repos https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/config/sot_talos.repos
78 vcs import --recursive < sot_talos.repos
79 # configure your catkin environment
81 To build everything you can simply type:
85 The cmake arguments are explained in more details in \ref memo_catkin_tools_compiling
87 \section memo_catkin_tools_vcs Handling the repositories (VCS)
90 \subsection memo_catkin_tools_vcs_checkingout Checking out the SoT infra-structure
92 The set of repositories can be handled using the [vcs software]
93 (https://github.com/dirk-thomas/vcstool)
95 The repositories for the SoT can be specified in a file sot_talos.repos as follows:
98 others/robotpkg_helpers:
100 url: https://github.com/stack-of-tasks/robotpkg_helpers.git
104 url: https://github.com/stack-of-tasks/dynamic-graph.git
106 src/dynamic-graph-python:
108 url: https://github.com/stack-of-tasks/dynamic-graph-python.git
110 src/dynamic_graph_bridge:
112 url: https://github.com/stack-of-tasks/dynamic_graph_bridge.git
114 src/dynamic_graph_bridge_msgs:
116 url: https://github.com/stack-of-tasks/dynamic_graph_bridge_msgs.git
120 url: https://github.com/stack-of-tasks/jrl-walkgen.git
124 url: https://github.com/stack-of-tasks/roscontrol_sot.git
128 url: https://github.com/stack-of-tasks/sot-core.git
132 url: https://github.com/stack-of-tasks/sot-doc.git
134 src/sot-dynamic-pinocchio:
136 url: https://github.com/stack-of-tasks/sot-dynamic-pinocchio.git
138 src/sot-pattern-generator:
140 url: https://github.com/stack-of-tasks/sot-pattern-generator.git
144 url: https://github.com/stack-of-tasks/sot-talos.git
146 src/sot-talos-balance:
148 url: https://github.com/loco-3d/sot-talos-balance.git
152 url: https://github.com/stack-of-tasks/sot-tools.git
154 src/sot-torque-control:
156 url: https://github.com/stack-of-tasks/sot-torque-control.git
160 url: https://github.com/stack-of-tasks/talos_data.git
162 src/talos_metapkg_ros_control_sot:
164 url: https://github.com/stack-of-tasks/talos_metapkg_roscontrol_sot.git
168 url: https://github.com/stack-of-tasks/tsid.git
171 To import all the repositories:
173 vcs import --recursive < sot_talos.repos
176 You can create your own file by going in the src directory of your workspace, and then type:
178 vcs export --repos > sot_talos.repos
181 \subsection memo_catkin_tools_vcs_status Getting the current status of the repos
182 In the src directory of the workspace
186 \subsection memo_catkin_tools_vcs_status Updating the repos
187 In the root directory of the worspace
191 This will pull the current branch from its upstream remote server.
194 \section memo_catkin_tools_compiling Compiling and testing the packages (catkin)
196 \subsection memo_catkin_tools_compiling_settings Setting the cmake args
197 For instance we want to force the system to be in debug mode
198 and to set some variables we can use the following command:
201 catkin config --install --cmake-args -DCMAKE_BUILD_TYPE=DEBUG
203 It forces the package to be installed in the install folder,
204 and forces all the CMake aware packages to be compiled in DEBUG mode.
206 A more involved example is the following:
208 local_cmake_args="--cmake-args -DCMAKE_BUILD_TYPE=DEBUG "
209 local_cmake_args="${local_cmake_args} -DPYTHON_STANDARD_LAYOUT:BOOL=ON"
210 local_cmake_args="${local_cmake_args} -DPYTHON_DEB_LAYOUT:BOOL=OFF"
211 local_cmake_args="${local_cmake_args} -DSETUPTOOLS_DEB_LAYOUT:BOOL=OFF"
212 local_cmake_args="${local_cmake_args} -DCMAKE_CXX_FLAGS=\"-std=c++1\""
213 catkin_config_args="--install -w /path_to_sot_ws"
214 catkin_config_args="${catking_config_args} ${local_cmake_args}"
215 catkin config ${catkin_config_args} --
218 \subsection memo_catkin_tools_compiling_compiling Compiling
220 \subsubsection memo_catkin_tools_compiling_all Compiling everything
225 \subsubsection memo_catkin_tools_compiling_a_pkg Compiling a specific package with its dependencies
226 For instance the following command is compiling the dynamic-graph-python
230 catkin build dynamic-graph-python
233 \subsubsection memo_catkin_tools_compiling_a_pkg_nodeps Compiling a specific package without its dependencies
234 For instance the following command is compiling the dynamic-graph-python
238 catkin build dynamic-graph-python --no-deps
240 \subsubsection memo_catkin_tools_compiling_a_pkg_doc Generating the documentation
241 For instance the following command is generating the documentation for the sot-core
244 catkin build sot-core --no-deps --make-args doc
246 \subsection memo_catkin_tools_clean_all Clean all the build part
250 \subsection memo_catkin_tools_run_tests Running tests
251 Example running the test programs of the package dynamic-graph-python in the workspace root directory:
254 catkin test dynamic-graph-python
256 Note: make sure that the install directory is specified in the environment variables LD_LIBRARY_PATH and PYTHONPATH for instance.
257 By default *all* dependent packages will also run the tests. To prevent this it is highly recommended to use:
260 catkin test dynamic-graph-python --no-deps
263 \subsection memo_catkin_tools_compute_coverage Computing coverage
265 You need to add to the CXX_FLAGS and the LD_FLAGS the value --coverage:
268 catkin config --append --cmake-args -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_LD_FLAGS="--coverage"
273 catkin test dynamic-graph-python
276 And in the workspace root directory you need to run:
278 gcovr -r . --html --html-details -o ./logs/coverage/index.html
281 To get the output of the coverage:
283 firefox ./logs/coverage/index.html
286 \section memo_preparing_environment Installing dependencies
288 They are several ways to install the dependencies of the SoT from sources in a target directory ```/path_to_target_dir```
289 We gave here two methods to install the necessary software environment for the Stack-of-Tasks.
290 To illustrate the process the Talos humanoid robot related packages are used.
292 \subsection subsec_preparing_env_from_rpkg_bash Quick start
294 To install the necessary SoT software dependency in '''/path_to_target_dir``` you can simply try:
296 wget -O install-dep-thru-rpkg.sh https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/bash/install-dep-thru-rpkg.sh
297 chmod +x ./install-dep-thru-rpkg.sh
298 ./install-dep-thru-rpkg.sh -p /path_to_target_dir -s /path_to_robotpkg_src
300 The robotpkg source directory will be stored in ```/path_to_robotpkg_src```
303 \subsection subsec_preparing_env_from_rpkg_only Robotpkg Only
305 You can install the package management system [robotpkg](http://robotpkg.openrobots.org/) as detailed in \ref installation_from_source .
306 During the procedure make sure that prefix is set to ```/path_to_target_dir```.
308 \subsection subsec_preparing_env_from_rpkg_helpers Robotpkg helpers repository
310 An intermediate solution between the two previous solution is to use a tool which configure robotpkg.
311 It is done through the following steps:
313 Clone the following repository :
315 git clone robotpkg_helpers https://github.com/olivier-stasse/robotpkg_helpers
317 Modify the following JSON file:
319 {"arch_dist_files": "arch_distfiles",
320 "archives": "archives",
321 "ramfs_mnt_pt": "openrobots",
322 "repo_robotpkg_wip": "https://git.openrobots.org/robots/robotpkg/robotpkg-wip.git",
323 "repo_robotpkg_main": "https://git.openrobots.org/robots/robotpkg.git",
324 "robotpkg_mng_root": "/integration_tests",
325 "robotpkg_mng_base": "/integration_tests/openrobots",
326 "robotpkg_mng_src": "/integration_tests/test-openrobots-src",
329 "ssh_git_openrobots": false,
330 "targetpkgs": ["talos-simulation","pinocchio","py-pinocchio","py-eigenpy",
331 "simple-humanoid-description","eiquadprog","parametric-curves"]
334 You can set the variable ```robotpkg_mng_base``` to ```/path_to_target_dir```. This where all the binaries, libraries, ros packages and documentation will be installed.
335 The variable ```robotpkg_mng_src``` specifies where the robotpkg sources are stored.
337 \subsection subsec_preparing_env_chaining_ws Chaining workspaces
339 To chain the workspace you can either follow this tutorial
341 http://wiki.ros.org/catkin/Tutorials/workspace_overlaying
343 with the workspace where all the SoT packages are located, or make an alias calling the script
344 [setup-sot.sh](https://github.com/stack-of-tasks/sot-doc/blob/master/bash/setup-sot.sh)
346 source setup-sot.sh -p /path_to_target_dir -r
347 source setup-sot.sh -p /path_to_sot_ws/install -r