sot-doc  1.1.0
Documentation entry point for the Stack-Of-Tasks
doc/CatkinBuildTools.md
1 # Using catkin tools and vcs for the SoT {#memo_catkin_tools}
2 
3 \section memo_catkin_tools_intro Introduction
4 
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.
7 
8 Two solutions are possible:
9 
10  * Installing the SoT third party dependency from robotpkg binaries.
11  * Installing the SoT third party dependency from robotpkg sources.
12 
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.
15 
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.
18 
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.
22 
23 The last solution is to use docker.
24 
25 \subsection memo_catkin_tools_quick_start Quick start
26 
27 \subsubsection memo_catkin_tools_quick_start_required Required packages
28 
29 
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 :
31 
32  sudo apt install ccache libncurses5-dev pax texlive-latex-extra doxygen assimp-utils python3-notify2 python3-lark-parser
33 
34 Some ros packages are required as well. For ros melodic you can run:
35 
36  sudo apt install ros-melodic-octomap ros-melodic-orocos-kinematics-dynamics ros-melodic-four-wheel-steering-msgs ros-melodic-urdf-geometry-parser
37 
38 For kinetic, run:
39 
40  sudo apt install ros-kinetic-octomap ros-kinetic-orocos-kinematics-dynamics ros-kinetic-four-wheel-steering-msgs ros-kinetic-urdf-geometry-parser
41 
42 \subsubsection memo_catkin_tools_quick_start_depends Install dependencies
43 
44 To install the necessary SoT software dependency in ```/path_to_target_dir``` you can simply try:
45 
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
49 
50 This will install the binairies in ```/path_to_target_dir``` and store the sources in ```/path_to_robotpkg_src```.
51 
52 Other options to install the source dependencies are given in \ref memo_preparing_environment.
53 
54 \subsubsection memo_catkin_tools_quick_start_setnv Setup your environment
55 
56  source setup-sot.sh -p /path_to_target_dir -r
57  source setup-sot.sh -p /path_to_sot_ws/install -r
58 
59 \subsubsection _catkin_tools_quick_create_ws Create your workspace
60 
61 You will then need some tools: one for version control, the other for your workspace
62 
63  sudo apt install python3-vcstool python3-catkin-tools
64 
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):
66 
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
70 
71 \subsection memto_catkin_tools_quick_start_explanations Quick start explanations
72 
73 The previous script is doing the following steps:
74 
75  mkdir -p /path_to_sot_ws
76  cd /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
80 
81 To build everything you can simply type:
82 
83  catkin build
84 
85 The cmake arguments are explained in more details in \ref memo_catkin_tools_compiling
86 
87 \section memo_catkin_tools_vcs Handling the repositories (VCS)
88 
89 
90 \subsection memo_catkin_tools_vcs_checkingout Checking out the SoT infra-structure
91 
92 The set of repositories can be handled using the [vcs software]
93 (https://github.com/dirk-thomas/vcstool)
94 
95 The repositories for the SoT can be specified in a file sot_talos.repos as follows:
96 
97  repositories:
98  others/robotpkg_helpers:
99  type: git
100  url: https://github.com/stack-of-tasks/robotpkg_helpers.git
101  version: master
102  src/dynamic-graph:
103  type: git
104  url: https://github.com/stack-of-tasks/dynamic-graph.git
105  version: master
106  src/dynamic-graph-python:
107  type: git
108  url: https://github.com/stack-of-tasks/dynamic-graph-python.git
109  version: master
110  src/dynamic_graph_bridge:
111  type: git
112  url: https://github.com/stack-of-tasks/dynamic_graph_bridge.git
113  version: master
114  src/dynamic_graph_bridge_msgs:
115  type: git
116  url: https://github.com/stack-of-tasks/dynamic_graph_bridge_msgs.git
117  version: master
118  src/jrl-walkgen:
119  type: git
120  url: https://github.com/stack-of-tasks/jrl-walkgen.git
121  version: master
122  src/roscontrol_sot:
123  type: git
124  url: https://github.com/stack-of-tasks/roscontrol_sot.git
125  version: master
126  src/sot-core:
127  type: git
128  url: https://github.com/stack-of-tasks/sot-core.git
129  version: master
130  src/sot-doc:
131  type: git
132  url: https://github.com/stack-of-tasks/sot-doc.git
133  version: master
134  src/sot-dynamic-pinocchio:
135  type: git
136  url: https://github.com/stack-of-tasks/sot-dynamic-pinocchio.git
137  version: master
138  src/sot-pattern-generator:
139  type: git
140  url: https://github.com/stack-of-tasks/sot-pattern-generator.git
141  version: master
142  src/sot-talos:
143  type: git
144  url: https://github.com/stack-of-tasks/sot-talos.git
145  version: master
146  src/sot-talos-balance:
147  type: git
148  url: https://github.com/loco-3d/sot-talos-balance.git
149  version: master
150  src/sot-tools:
151  type: git
152  url: https://github.com/stack-of-tasks/sot-tools.git
153  version: master
154  src/sot-torque-control:
155  type: git
156  url: https://github.com/stack-of-tasks/sot-torque-control.git
157  version: master
158  src/talos_data:
159  type: git
160  url: https://github.com/stack-of-tasks/talos_data.git
161  version: master
162  src/talos_metapkg_ros_control_sot:
163  type: git
164  url: https://github.com/stack-of-tasks/talos_metapkg_roscontrol_sot.git
165  version: master
166  src/tsid:
167  type: git
168  url: https://github.com/stack-of-tasks/tsid.git
169  version: master
170 
171 To import all the repositories:
172 
173  vcs import --recursive < sot_talos.repos
174 
175 
176 You can create your own file by going in the src directory of your workspace, and then type:
177 
178  vcs export --repos > sot_talos.repos
179 
180 
181 \subsection memo_catkin_tools_vcs_status Getting the current status of the repos
182 In the src directory of the workspace
183 
184  vcs status -quiet
185 
186 \subsection memo_catkin_tools_vcs_status Updating the repos
187 In the root directory of the worspace
188 
189  vcs pull
190 
191 This will pull the current branch from its upstream remote server.
192 
193 
194 \section memo_catkin_tools_compiling Compiling and testing the packages (catkin)
195 
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:
199 
200  cd /path_to_sot_ws
201  catkin config --install --cmake-args -DCMAKE_BUILD_TYPE=DEBUG
202 
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.
205 
206 A more involved example is the following:
207 
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} --
216 
217 
218 \subsection memo_catkin_tools_compiling_compiling Compiling
219 
220 \subsubsection memo_catkin_tools_compiling_all Compiling everything
221 
222  catkin build
223 
224 
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
227 package:
228 
229 
230  catkin build dynamic-graph-python
231 
232 
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
235 package:
236 
237 
238  catkin build dynamic-graph-python --no-deps
239 
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
242 package:
243 
244  catkin build sot-core --no-deps --make-args doc
245 
246 \subsection memo_catkin_tools_clean_all Clean all the build part
247 
248  catkin clean
249 
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:
252 
253 
254  catkin test dynamic-graph-python
255 
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:
258 
259 
260  catkin test dynamic-graph-python --no-deps
261 
262 
263 \subsection memo_catkin_tools_compute_coverage Computing coverage
264 
265 You need to add to the CXX_FLAGS and the LD_FLAGS the value --coverage:
266 
267 
268  catkin config --append --cmake-args -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_LD_FLAGS="--coverage"
269 
270 
271 Then run the test:
272 
273  catkin test dynamic-graph-python
274 
275 
276 And in the workspace root directory you need to run:
277 
278  gcovr -r . --html --html-details -o ./logs/coverage/index.html
279 
280 
281 To get the output of the coverage:
282 
283  firefox ./logs/coverage/index.html
284 
285 
286 \section memo_preparing_environment Installing dependencies
287 
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.
291 
292 \subsection subsec_preparing_env_from_rpkg_bash Quick start
293 
294 To install the necessary SoT software dependency in '''/path_to_target_dir``` you can simply try:
295 
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
299 
300 The robotpkg source directory will be stored in ```/path_to_robotpkg_src```
301 
302 
303 \subsection subsec_preparing_env_from_rpkg_only Robotpkg Only
304 
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```.
307 
308 \subsection subsec_preparing_env_from_rpkg_helpers Robotpkg helpers repository
309 
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:
312 
313 Clone the following repository :
314 
315  git clone robotpkg_helpers https://github.com/olivier-stasse/robotpkg_helpers
316 
317 Modify the following JSON file:
318 
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",
327  "rc_pkgs":
328  {},
329  "ssh_git_openrobots": false,
330  "targetpkgs": ["talos-simulation","pinocchio","py-pinocchio","py-eigenpy",
331  "simple-humanoid-description","eiquadprog","parametric-curves"]
332  }
333 
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.
336 
337 \subsection subsec_preparing_env_chaining_ws Chaining workspaces
338 
339 To chain the workspace you can either follow this tutorial
340 
341  http://wiki.ros.org/catkin/Tutorials/workspace_overlaying
342 
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)
345 
346  source setup-sot.sh -p /path_to_target_dir -r
347  source setup-sot.sh -p /path_to_sot_ws/install -r