Skip to content

Commit ed412f2

Browse files
committed
Documentation for running and passing ament_lint tests added.
1 parent 42cfe9e commit ed412f2

File tree

3 files changed

+424
-229
lines changed

3 files changed

+424
-229
lines changed
Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
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

Comments
 (0)