Skip to content

Commit 8aeda91

Browse files
fjanguitafjanguita
committed
First review comments applied
1 parent 6c336fb commit 8aeda91

File tree

2 files changed

+160
-91
lines changed

2 files changed

+160
-91
lines changed

‎docs/_09_development/_develop_guide/_develop_guide/_develop_new_pkg.rst

+148-90
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,105 @@
44
Developing a New Package
55
------------------------
66

7-
TDB
8-
9-
10-
117
.. _development_guide_new_pkg_architecture:
128

139
Architecture of a New Package
1410
=============================
1511

16-
Every new package should have the following architecture:
12+
Structure of a C++ Package
13+
--------------------------
14+
15+
Every new C++ package should have the following architecture:
16+
17+
.. code-block::
18+
19+
/package_name
20+
/include
21+
/package_name
22+
### header files ###
23+
node_name(.hpp)
24+
/launch
25+
/src
26+
### implementation_files ###
27+
node_name(.cpp)
28+
### main_files ###
29+
node_name_node(.cpp)
30+
/tests
31+
CMakeLists.txt
32+
### test_files ###
33+
gtest_test(.cpp)
34+
CmakeLists.txt
35+
package.xml
36+
README.md
37+
LICENSE
38+
CONTRIBUTING.md
39+
.gitignore
40+
41+
Structure of a Python Package
42+
-----------------------------
43+
44+
Every new Python package should have the following architecture:
1745

1846
.. code-block::
1947
2048
/package_name
21-
/include
2249
/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
50+
__init__.py
51+
### source_files ###
52+
file(.py)
53+
/launch
54+
/tests
55+
### test_files ###
56+
test(.py)
57+
setup.cfg
58+
setup.py
59+
package.xml
60+
README.md
61+
LICENSE
62+
CONTRIBUTING.md
63+
.gitignore
64+
65+
Structure of a Hybrid Package
66+
-----------------------------
67+
68+
A package that includes both Python and C++ files should have the following architecture:
3569

70+
.. code-block::
3671
72+
/package_name
73+
/package_name
74+
__init__.py
75+
### python_source_files ###
76+
file(.py)
77+
/include
78+
/package_name
79+
### C++ header files ###
80+
node_name(.hpp)
81+
82+
/launch
83+
/src
84+
### C++ implementation_files ###
85+
node_name(.cpp)
86+
### C++ main_files ###
87+
node_name_node(.cpp)
88+
/tests
89+
### test_files ###
90+
test(.py)
91+
CMakeList.txt
92+
package.xml
93+
README.md
94+
LICENSE
95+
CONTRIBUTING.md
96+
.gitignore
3797
3898
.. _development_guide_new_pkg_code_style:
3999

40100
Code Style
41101
==========
42102

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-
103+
Aerostack2 mainly follows the `ROS 2 code style and language versions <https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html>`_.
104+
There are, though, some exceptions, as ROS 2 claims to follow Goggle code style but uses snake_case
105+
instead of camelCase. Aerostack2 uses camelCase.
45106

46107

47108
.. _development_guide_new_pkg_code_style_c++:
@@ -55,37 +116,33 @@ Every file should start with the Licence text, which looks like this:
55116

56117
.. code-block:: c++
57118

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-
**********************************************************************************************/
119+
// Copyright 2024 Universidad Politécnica de Madrid
120+
//
121+
// Redistribution and use in source and binary forms, with or without
122+
// modification, are permitted provided that the following conditions are met:
123+
//
124+
// * Redistributions of source code must retain the above copyright
125+
// notice, this list of conditions and the following disclaimer.
126+
//
127+
// * Redistributions in binary form must reproduce the above copyright
128+
// notice, this list of conditions and the following disclaimer in the
129+
// documentation and/or other materials provided with the distribution.
130+
//
131+
// * Neither the name of the Universidad Politécnica de Madrid nor the names of its
132+
// contributors may be used to endorse or promote products derived from
133+
// this software without specific prior written permission.
134+
//
135+
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
136+
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
137+
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
138+
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
139+
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
140+
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
141+
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
142+
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
143+
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
144+
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
145+
// POSSIBILITY OF SUCH DAMAGE.
89146

90147
Documentation will be generate using `Doxygen <https://www.doxygen.nl/manual/docblocks.html>`_.
91148
Therefore, header files should include a comment over every definition in order to generate the documentation properly.
@@ -250,59 +307,66 @@ In aerostack2 we use googletest (GTest) library to perform unit tests across the
250307
GTest complete documentation about how to write your own unit tests can be found at:
251308
https://github.com/google/googletest
252309

310+
To use GTest, the next line must be added to your ``package.xml``
311+
312+
.. code-block::
313+
314+
<test_depend>ament_cmake_gtest</test_depend>
315+
253316
In order to compile this tests some lines must be added into a **NEW** ``CMakeLists.txt`` file located in a ``tests/`` folder.
254317

255318
.. code-block:: cmake
256319
257-
# Add gtest dependencies and install them if they are not already installed
320+
# Tests
321+
file(GLOB TEST_SOURCE "*_test.cpp")
322+
323+
if(TEST_SOURCE)
324+
foreach(TEST_FILE ${TEST_SOURCE})
325+
get_filename_component(TEST_NAME ${TEST_FILE} NAME_WE)
258326
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)
327+
add_executable(${PROJECT_NAME}_${TEST_NAME} ${TEST_FILE})
328+
ament_target_dependencies(${PROJECT_NAME}_${TEST_NAME} ${PROJECT_DEPENDENCIES})
329+
target_link_libraries(${PROJECT_NAME}_${TEST_NAME} ${PROJECT_NAME})
330+
endforeach()
331+
endif()
272332
273-
endif(${Gtest_FOUND})
333+
# GTest
334+
file(GLOB GTEST_SOURCE "*_gtest.cpp")
274335
275-
include(GoogleTest)
336+
if(GTEST_SOURCE)
337+
find_package(ament_cmake_gtest REQUIRED)
276338
277-
enable_testing()
278-
# find all *.cpp files in the tests directory
339+
foreach(TEST_SOURCE ${GTEST_SOURCE})
340+
get_filename_component(TEST_NAME ${TEST_SOURCE} NAME_WE)
279341
280-
file(GLOB TEST_SOURCES tests/*.cpp )
342+
ament_add_gtest(${PROJECT_NAME}_${TEST_NAME} ${TEST_SOURCE})
343+
ament_target_dependencies(${PROJECT_NAME}_${TEST_NAME} ${PROJECT_DEPENDENCIES})
344+
target_link_libraries(${PROJECT_NAME}_${TEST_NAME} gtest_main ${PROJECT_NAME})
345+
endforeach()
346+
endif()
281347
282-
# create a test executable for each test file
283-
foreach(TEST_SOURCE ${TEST_SOURCES})
348+
# Benchmark
349+
file(GLOB BENCHMARK_SOURCE "*_benchmark.cpp")
284350
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})
351+
if(BENCHMARK_SOURCE)
352+
find_package(benchmark REQUIRED)
293353
294-
# add the test executable to the list of executables to build
295-
gtest_discover_tests(${TEST_NAME}_test)
354+
foreach(BENCHMARK_FILE ${BENCHMARK_SOURCE})
355+
get_filename_component(BENCHMARK_NAME ${BENCHMARK_FILE} NAME_WE)
296356
357+
add_executable(${PROJECT_NAME}_${BENCHMARK_NAME} ${BENCHMARK_FILE})
358+
target_link_libraries(${PROJECT_NAME}_${BENCHMARK_NAME} ${PROJECT_NAME} benchmark::benchmark)
297359
endforeach()
360+
endif()
298361
299362
In order to link this ``./tests/CMakeLists.txt`` file into the ``CMakeLists.txt`` file of the package, the following line must be added:
300363

301364
.. code-block:: cmake
302365
366+
# Build tests if testing is enabled
303367
if(BUILD_TESTING)
304-
# all the other tests
305-
include(./tests/CMakeLists.txt)
368+
# all other tests
369+
add_subdirectory(tests)
306370
endif()
307371
308372
@@ -312,9 +376,3 @@ To run these tests:
312376
313377
$ colcon test
314378
315-
.. _development_guide_new_pkg_test_coverage:
316-
317-
Code Coverage Test
318-
------------------
319-
320-
TDB

‎docs/_09_development/_develop_guide/_develop_guide/_setting_code.rst

+12-1
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,25 @@ Open your ``settings.json`` file from VSCode and add the following content to it
6666
},
6767
"autopep8.args": ["--max-line-length=99", "--ignore=''"],
6868
69-
// ROS2 uses as a linter flake8==4.0.1 (apt installation). Pip installation should be
69+
// ROS2 HUMBLE uses as a linter flake8==4.0.1 (apt installation). Pip installation should be
7070
// at the same version to avoid errors. pycodestyle==2.8.0 is also required.
7171
// vscode flake8 extension requires at least flake8 v5.0.0. Pylint extension is used
7272
// instead with identical configuration.
7373
"pylint.args": ["--disable=B902,C816,D100,D101,D102,D103,D104,D105,D106,D107,D203,D212,D404,I202",
7474
"--max-line-length=99", "--import-order-style=google", "--show-source=true",
7575
"--statistics=true"],
7676
77+
Newer versions of ROS 2 include upgraded flake8 (in ament_flake8), so it is preferable to use
78+
flake8 from VSCode too instead of pylint. To do so, use, instead of the 'pylint.args' settings,
79+
the following settings:
80+
81+
.. code-block:: json
82+
83+
// flake8
84+
"flake8.args": ["--extend-ignore=B902,C816,D100,D101,D102,D103,D104,D105,D106,D107,D203,D212,D404,I202",
85+
"--import-order-style=google", "--max-line-length=99", "--show-source=true",
86+
"--statistics=true"],
87+
7788
.. _development_guide_code_config_variables:
7889

7990
Set Configuration Variables

0 commit comments

Comments
 (0)