1 # Using colcon tools and vcs for the SoT {#memo_colcon_tools}
3 Colcon is the preferred way to compile the SoT as it is shipped with the newest ROS releases and available on several non Linux platforms.
5 \section memo_colcon_tools_intro Introduction
7 This memo explains how to create and handle a super build (set of packages) workspace of the SoT with [colcon](https://colcon.readthedocs.io/en/released/) tools.
8 Colcon can be installed independently from ROS using pip.
10 As explained in \ref memo_colcon_tools_intro there is several solutions to install a source base environment.
12 \subsection memo_colcon_tools_quick_start Quick start
14 \subsubsection memo_colcon_tools_quick_start_depends Install third party dependencies of the SoT packages
16 To install the necessary SoT software third party dependencies in '''/path_to_target_dir``` you can simply try:
18 wget -O install-dep-thru-rpkg.sh https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/bash/install-dep-thru-rpkg.sh
19 chmod +x ./install-dep-thru-rpkg.sh
20 ./install-dep-thru-rpkg.sh -p /path_to_target_dir -s /path_to_robotpkg_src
22 This will donwload, set, compile and install the binairies in ```/path_to_target_dir``` and store the sources in ```/path_to_robotpkg_src```.
23 It is heavily based on the tool [robotpkg](https://robotpkg.openrobots.org)
25 Other options to install the source dependencies are given in \ref memo_preparing_environment.
27 \subsubsection memo_colcon_tools_quick_start_setnv Setup your environment
29 source setup-sot.sh -p /path_to_target_dir -r
30 source setup-sot.sh -p /path_to_sot_ws/install -r
32 \subsubsection memo_colcon_tools_quick_create_ws Create your workspace
34 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):
36 wget -O install-sot-catkin-ws.sh https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/bash/install-sot-catkin-ws.sh
37 chmod +x ./install-sot-catkin-ws.sh
38 ./install-sot-catkin-ws.sh -p /path_to_sot_ws
40 \subsection memto_catkin_tools_quick_start_explanations Quick start explanations
42 The previous script is doing the following steps:
44 mkdir -p /path_to_sot_ws
46 wget -O sot_talos.repos https://raw.githubusercontent.com/stack-of-tasks/sot-doc/master/config/sot_talos.repos
47 vcs import --recursive < sot_talos.repos
48 # configure your catkin environment
50 To build everything you can simply type:
52 colcon build --merge-install
54 The cmake arguments are explained in more details in \ref memo_colcon_tools_compiling
56 \section memo_colcon_tools_vcs Handling the repositories (VCS)
58 This section is already described
60 \section memo_colcon_tools_compiling Compiling and testing the packages (catkin)
62 \subsection memo_colcon_tools_compiling_settings Setting the cmake args
63 For instance we want to force the system to be in debug mode
64 and to set some variables we can use the following command:
67 colcon build --merge-install --packages-select sot-dynamic-pinocchio --cmake-args ' -DPYTHON_EXECUTABLE=/usr/local/opt/python@3.8/bin/python3' ' -DCMAKE_BUILD_TYPE=RELEASE' ' -DCMAKE_CXX_COMPILER=/usr/bin/c++' ' -DCMAKE_CXX_STANDARD=14'
69 It forces the package sot-dynamic-pinocchio to be installed in the install folder,
70 forces the CMake package to be compiled in RELEASE mode,
71 and the python executable is
73 /usr/local/opt/python@3.8/bin/python3
75 \subsection memo_colcon_tools_compiling_compiling Compiling
77 \subsubsection memo_colcon_tools_compiling_all Compiling everything
79 colcon build --merge-install
82 \subsubsection memo_colcon_tools_compiling_a_pkg Compiling a specific package with its dependencies
83 For instance the following command is compiling the dynamic-graph-python
87 colcon build --merge-install --packages-up-to dynamic-graph-python
90 \subsubsection memo_colcon_tools_compiling_a_pkg_nodeps Compiling a specific package without its dependencies
91 For instance the following command is compiling the dynamic-graph-python
95 colcon build --merge-install --packages-select dynamic-graph-python
97 \subsubsection memo_colcon_tools_compiling_a_pkg_doc Generating the documentation
98 For instance the following command is generating the documentation for the sot-core
101 colcon build --merge-install --packages-select sot-core --make-args doc
103 \subsection memo_colcon_tools_clean_all Clean all the build part
107 \subsection memo_colcon_tools_run_tests Running tests
108 Example running the test programs of the package dynamic-graph-python in the workspace root directory:
111 colcon test --packages-select dynamic-graph-python
113 Note: make sure that the install directory is specified in the environment variables LD_LIBRARY_PATH and PYTHONPATH for instance.
114 By default *all* dependent packages will also run the tests. To prevent this it is highly recommended to use:
117 colcon test --packages-select dynamic-graph-python
120 \subsection memo_colcon_tools_compute_coverage Computing coverage
122 You need to add to the CXX_FLAGS and the LD_FLAGS the value --coverage:
125 colcon build --cmake-args -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_LD_FLAGS="--coverage"
130 colcon test dynamic-graph-python
133 And in the workspace root directory you need to run:
135 gcovr -r . --html --html-details -o ./logs/coverage/index.html
138 To get the output of the coverage:
140 firefox ./logs/coverage/index.html