|
| 1 | +.. _development_guide_new_pkg: |
| 2 | + |
| 3 | +------------------------ |
| 4 | +Developing a New Package |
| 5 | +------------------------ |
| 6 | + |
| 7 | +TDB |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +.. _development_guide_new_pkg_architecture: |
| 12 | + |
| 13 | +Architecture of a New Package |
| 14 | +============================= |
| 15 | + |
| 16 | +Every new package should have the following architecture: |
| 17 | + |
| 18 | +.. code-block:: |
| 19 | +
|
| 20 | + /package_name |
| 21 | + /include |
| 22 | + /package_name |
| 23 | + header_files(.hpp) |
| 24 | + /launch |
| 25 | + /src |
| 26 | + implementation_files(.cpp) |
| 27 | + main_files(.cpp) |
| 28 | + /tests |
| 29 | + CMakeLists.txt |
| 30 | + test_files(.cpp) |
| 31 | + CmakeLists.txt |
| 32 | + package.xml |
| 33 | + Readme.md |
| 34 | + .gitignore |
| 35 | +
|
| 36 | +
|
| 37 | +
|
| 38 | +.. _development_guide_new_pkg_code_style: |
| 39 | + |
| 40 | +Code Style |
| 41 | +========== |
| 42 | + |
| 43 | +Aerostack2 follows the `ROS 2 code style and language versions <https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html>`_. |
| 44 | + |
| 45 | + |
| 46 | + |
| 47 | +.. _development_guide_new_pkg_code_style_c++: |
| 48 | + |
| 49 | +C++ |
| 50 | +--- |
| 51 | + |
| 52 | +Code should follows the `google c++ style guide <https://google.github.io/styleguide/cppguide.html>`_. |
| 53 | + |
| 54 | +Every file should start with the Licence text, which looks like this: |
| 55 | + |
| 56 | +.. code-block:: c++ |
| 57 | + |
| 58 | + /********************************************************************************************* |
| 59 | + * \file [file name] |
| 60 | + * \brief [brief description of the file] |
| 61 | + * \authors [name of the author] |
| 62 | + * \copyright Copyright (c) 2021 Universidad Politécnica de Madrid |
| 63 | + * All Rights Reserved |
| 64 | + * |
| 65 | + * Redistribution and use in source and binary forms, with or without |
| 66 | + * modification, are permitted provided that the following conditions are met: |
| 67 | + * |
| 68 | + * 1. Redistributions of source code must retain the above copyright notice, |
| 69 | + * this list of conditions and the following disclaimer. |
| 70 | + * 2. Redistributions in binary form must reproduce the above copyright notice, |
| 71 | + * this list of conditions and the following disclaimer in the documentation |
| 72 | + * and/or other materials provided with the distribution. |
| 73 | + * 3. Neither the name of the copyright holder nor the names of its contributors |
| 74 | + * may be used to endorse or promote products derived from this software |
| 75 | + * without specific prior written permission. |
| 76 | + * |
| 77 | + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 78 | + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, |
| 79 | + * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| 80 | + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR |
| 81 | + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 82 | + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 83 | + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; |
| 84 | + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, |
| 85 | + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE |
| 86 | + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, |
| 87 | + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 88 | + **********************************************************************************************/ |
| 89 | + |
| 90 | +Documentation will be generate using `Doxygen <https://www.doxygen.nl/manual/docblocks.html>`_. |
| 91 | +Therefore, header files should include a comment over every definition in order to generate the documentation properly. |
| 92 | +The comments made in the current nodes are writing using Javadoc style. |
| 93 | + |
| 94 | +Please, do not use std::cout or similar functions to show messages in command line. Instead, use logging macros like RCLCPP_INFO from ROS logging library. |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | +.. _development_guide_new_pkg_code_style_python: |
| 99 | + |
| 100 | +Python |
| 101 | +------ |
| 102 | + |
| 103 | +Code should follow the `PEP 8 <https://peps.python.org/pep-0008/>`_ and `PEP 257 <https://peps.python.org/pep-0257/>`_ guidelines. |
| 104 | + |
| 105 | +.. _development_guide_new_pkg_test: |
| 106 | + |
| 107 | +Test |
| 108 | +==== |
| 109 | + |
| 110 | +To be used in Aerostack2, every package must pass, at least, the Code Style tests. Additional functional tests might be added to a package to provide a validation of its functionalities. |
| 111 | + |
| 112 | + |
| 113 | +.. _development_guide_new_pkg_test_style: |
| 114 | + |
| 115 | +Code Style Test |
| 116 | +--------------- |
| 117 | + |
| 118 | +Aerostack2 uses `ament_lint <https://github.com/ament/ament_lint>`_ to perform style checks over the packages files. |
| 119 | + |
| 120 | +For configuring style tests, this must be added on the ``CMakeList.txt`` of your package: |
| 121 | + |
| 122 | +.. code-block:: cmake |
| 123 | +
|
| 124 | + if(BUILD_TESTING) |
| 125 | +
|
| 126 | + find_package(ament_lint_auto REQUIRED) |
| 127 | + ament_lint_auto_find_test_dependencies() |
| 128 | +
|
| 129 | + endif() |
| 130 | +
|
| 131 | +Also, these packages must be added to the ``package.xml`` |
| 132 | + |
| 133 | +.. code-block:: |
| 134 | +
|
| 135 | + <test_depend>ament_lint_auto</test_depend> |
| 136 | + <test_depend>ament_lint_common</test_depend> |
| 137 | +
|
| 138 | +The tests that are performed as part of ament_lint_common can be found `here <https://github.com/ament/ament_lint/blob/humble/ament_lint_common/doc/index.rst>`_. |
| 139 | + |
| 140 | +Some test dependencies are also required and can be installed by running: |
| 141 | + |
| 142 | +.. code-block:: bash |
| 143 | +
|
| 144 | + apt-get install python3-rosdep python3-pip python3-colcon-common-extensions python3-colcon-mixin ros-dev-tools -y |
| 145 | + apt-get install python3-flake8-builtins python3-flake8-comprehensions python3-flake8-docstrings python3-flake8-import-order python3-flake8-quotes -y |
| 146 | +
|
| 147 | +The package can now be compiled running: |
| 148 | + |
| 149 | +.. code-block:: bash |
| 150 | +
|
| 151 | + as2 build <package_name> |
| 152 | +
|
| 153 | +And to run the tests, execute: |
| 154 | + |
| 155 | +.. code-block:: bash |
| 156 | +
|
| 157 | + as2 test -v <package_name> |
| 158 | +
|
| 159 | +The ``-v`` flag will print all the details of the test run, including information about the tests that did not pass and the specific erros that occurred. |
| 160 | + |
| 161 | +.. _development_guide_new_pkg_test_style_CLI: |
| 162 | + |
| 163 | +Running Individual Tests on CLI |
| 164 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 165 | + |
| 166 | +Ament_lint includes a series of CLI commands with which the tests can be run separately. This might be helpful for fixing the package and eliminate the errors. |
| 167 | +These CLI tools can be found on the folder of the specific test on the `ament_lint repository <https://github.com/ament/ament_lint>`_. |
| 168 | + |
| 169 | +· Running and Passing 'ament_uncrustify' |
| 170 | +"""""""""""""""""""""""""""""""""""""""""" |
| 171 | + |
| 172 | +The test ``ament_uncrustify`` can be launched by running: |
| 173 | + |
| 174 | +.. code-block:: bash |
| 175 | +
|
| 176 | + ament_uncrustify --reformat <path/to/package/directory>/* |
| 177 | +
|
| 178 | +Or simply by running the next command from the directory of your package: |
| 179 | + |
| 180 | +.. code-block:: bash |
| 181 | +
|
| 182 | + ament_uncrustify --reformat |
| 183 | +
|
| 184 | +Either way, the ``--reformat`` flag will automatically reformat the files in which erros have been found, apart from notifying which are these files. |
| 185 | + |
| 186 | +· Running and Passing 'ament_copyright' |
| 187 | +"""""""""""""""""""""""""""""""""""""""""" |
| 188 | + |
| 189 | +The test ``ament_copyright`` can be launched by running the next command from your package directory: |
| 190 | + |
| 191 | +.. code-block:: bash |
| 192 | +
|
| 193 | + ament_copyright --add-missing "Universidad Politécnica de Madrid" bsd_3clause |
| 194 | +
|
| 195 | +The flag ``--add-missing`` will add the Licence text to all the files that do not include one. |
| 196 | + |
| 197 | +· Running and Passing 'ament_pep257' |
| 198 | +"""""""""""""""""""""""""""""""""""""" |
| 199 | + |
| 200 | +The test ``ament_pep257`` can be launched by running the next command from your package directory: |
| 201 | + |
| 202 | +.. code-block:: bash |
| 203 | +
|
| 204 | + ament_pep257 |
| 205 | +
|
| 206 | +The third-party autoformatter `docformatter <https://github.com/PyCQA/docformatter>`_ can be used to help passing this test. It can be installed executing |
| 207 | + |
| 208 | +.. code-block:: bash |
| 209 | +
|
| 210 | + pip install --upgrade docformatter |
| 211 | +
|
| 212 | +and launched over the ``.py`` files by running: |
| 213 | + |
| 214 | +.. code-block:: bash |
| 215 | +
|
| 216 | + for file in $(find <path/to/package/directory> -name "*.py"); do |
| 217 | + python-lint "$file" |
| 218 | + done |
| 219 | +
|
| 220 | +This may NOT fix all the errors, but it will eliminate some of them. |
| 221 | + |
| 222 | +· Running and Passing 'ament_cppcheck' |
| 223 | +"""""""""""""""""""""""""""""""""""""""" |
| 224 | + |
| 225 | +The test ``ament_cppcheck`` can be launched by running the next command from your package directory: |
| 226 | + |
| 227 | +.. code-block:: bash |
| 228 | +
|
| 229 | + ament_cppcheck |
| 230 | +
|
| 231 | +You may encounter the following error when running the test alone: |
| 232 | + |
| 233 | +.. code-block:: bash |
| 234 | +
|
| 235 | + cppcheck 2.7 has known performance issues and therefore will not be used, set the AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS environment variable to override this. |
| 236 | +
|
| 237 | +This can be fixed by setting the ``AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS`` to whatever that evaluates to 'True', just as the error message indicates: |
| 238 | + |
| 239 | +.. code-block:: bash |
| 240 | +
|
| 241 | + export AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS=true |
| 242 | +
|
| 243 | +
|
| 244 | +.. _development_guide_new_pkg_test_functional: |
| 245 | + |
| 246 | +Code Functional Test |
| 247 | +-------------------- |
| 248 | + |
| 249 | +In aerostack2 we use googletest (GTest) library to perform unit tests across the packages. |
| 250 | +GTest complete documentation about how to write your own unit tests can be found at: |
| 251 | +https://github.com/google/googletest |
| 252 | + |
| 253 | +In order to compile this tests some lines must be added into a **NEW** ``CMakeLists.txt`` file located in a ``tests/`` folder. |
| 254 | + |
| 255 | +.. code-block:: cmake |
| 256 | +
|
| 257 | + # Add gtest dependencies and install them if they are not already installed |
| 258 | +
|
| 259 | + find_package(gtest QUIET) |
| 260 | + if (${Gtest_FOUND}) |
| 261 | + MESSAGE(STATUS "Found Gtest.") |
| 262 | + else (${Gtest_FOUND}) |
| 263 | + MESSAGE(STATUS "Could not locate Gtest.") |
| 264 | + include(FetchContent) |
| 265 | + FetchContent_Declare( |
| 266 | + googletest |
| 267 | + URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip |
| 268 | + ) |
| 269 | + # For Windows: Prevent overriding the parent project's compiler/linker settings |
| 270 | + set(gtest_force_shared_crt ON CACHE BOOL "" FORCE) |
| 271 | + FetchContent_MakeAvailable(googletest) |
| 272 | +
|
| 273 | + endif(${Gtest_FOUND}) |
| 274 | +
|
| 275 | + include(GoogleTest) |
| 276 | +
|
| 277 | + enable_testing() |
| 278 | + # find all *.cpp files in the tests directory |
| 279 | +
|
| 280 | + file(GLOB TEST_SOURCES tests/*.cpp ) |
| 281 | +
|
| 282 | + # create a test executable for each test file |
| 283 | + foreach(TEST_SOURCE ${TEST_SOURCES}) |
| 284 | +
|
| 285 | + get_filename_component(_src_filename ${TEST_SOURCE} NAME) |
| 286 | + string(LENGTH ${_src_filename} name_length) |
| 287 | + math(EXPR final_length "${name_length}-4") # remove .cpp of the name |
| 288 | + string(SUBSTRING ${_src_filename} 0 ${final_length} TEST_NAME) |
| 289 | + |
| 290 | + add_executable(${TEST_NAME}_test ${TEST_SOURCE}) |
| 291 | + ament_target_dependencies(${TEST_NAME}_test ${PROJECT_DEPENDENCIES}) |
| 292 | + target_link_libraries(${TEST_NAME}_test gtest_main ${PROJECT_NAME}) |
| 293 | +
|
| 294 | + # add the test executable to the list of executables to build |
| 295 | + gtest_discover_tests(${TEST_NAME}_test) |
| 296 | +
|
| 297 | + endforeach() |
| 298 | +
|
| 299 | +In order to link this ``./tests/CMakeLists.txt`` file into the ``CMakeLists.txt`` file of the package, the following line must be added: |
| 300 | + |
| 301 | +.. code-block:: cmake |
| 302 | +
|
| 303 | + if(BUILD_TESTING) |
| 304 | + # all the other tests |
| 305 | + include(./tests/CMakeLists.txt) |
| 306 | + endif() |
| 307 | +
|
| 308 | +
|
| 309 | +To run these tests: |
| 310 | + |
| 311 | +.. code-block:: bash |
| 312 | +
|
| 313 | + $ colcon test |
| 314 | +
|
| 315 | +.. _development_guide_new_pkg_test_coverage: |
| 316 | + |
| 317 | +Code Coverage Test |
| 318 | +------------------ |
| 319 | + |
| 320 | +TDB |
0 commit comments