From 2cca64ebada895aeef180835bb38d22149d8c9d0 Mon Sep 17 00:00:00 2001 From: Ryan Friedman Date: Fri, 26 Apr 2024 14:47:50 -0600 Subject: [PATCH] Improve examples * Simpler and standard build workflow * Utilize CTest with the recommended workflow of optional tests * Skip using make directly so these become more platform portable * Skip having to manually create the build directory * Do all operations from the source directory when possible to reduce the number of commands Signed-off-by: Ryan Friedman --- .../standalone/acoustic_comms_demo/README.md | 16 +++--- examples/standalone/custom_server/README.md | 15 +++--- .../standalone/each_performance/README.md | 35 +++++++++---- examples/standalone/entity_creation/README.md | 15 +++--- examples/standalone/external_ecm/README.md | 28 +++++----- .../standalone/gtest_setup/CMakeLists.txt | 52 +++++++++---------- examples/standalone/gtest_setup/README.md | 39 ++++++++++---- examples/standalone/joy_to_twist/README.md | 25 ++++----- examples/standalone/joystick/README.md | 34 ++++++------ 9 files changed, 146 insertions(+), 113 deletions(-) diff --git a/examples/standalone/acoustic_comms_demo/README.md b/examples/standalone/acoustic_comms_demo/README.md index 3400638570..6464f7132e 100644 --- a/examples/standalone/acoustic_comms_demo/README.md +++ b/examples/standalone/acoustic_comms_demo/README.md @@ -15,17 +15,19 @@ will receive the signal and start moving before Daphne. From this directory, run the following to compile: - mkdir build - cd build - cmake .. - make +```bash +cmake -B build +cmake --build build +``` ## Execute Instructions -From the `build` directory, run Gazebo Sim and the example controller: +Run Gazebo Sim and the example controller: - gz sim -r ../../../worlds/acoustic_comms_demo.sdf - ./acoustic_comms_demo +```bash +gz sim -r ../../worlds/acoustic_comms_demo.sdf +./build/acoustic_comms_demo +``` It can be seen visually that one of the vehicles (Triton) starts moving immediately, then afer a while Tethys will start moving, and then finally Daphne. diff --git a/examples/standalone/custom_server/README.md b/examples/standalone/custom_server/README.md index 706fbd5425..4d1b4b7aff 100644 --- a/examples/standalone/custom_server/README.md +++ b/examples/standalone/custom_server/README.md @@ -5,17 +5,18 @@ using the C++ API, instead of using Gazebo from the command line. ## Build Instructions -From this directory: +From this directory, run the following to compile: - cd gz-sim/examples/standalone/custom_server - mkdir build - cd build - cmake .. - make +```bash +cmake -B build +cmake --build build +``` ## Execute Instructions - ./custom_server +```bash +./build/custom_server +``` The server will run `shapes.sdf` for 100 iterations and exit. No GUI will show up. diff --git a/examples/standalone/each_performance/README.md b/examples/standalone/each_performance/README.md index 16806043d0..d1a4f3cd51 100644 --- a/examples/standalone/each_performance/README.md +++ b/examples/standalone/each_performance/README.md @@ -1,18 +1,33 @@ Example program to generate performance data -### Build +## Build Instructions - cd examples/standalong/each_performance - mkdir build - cd build - cmake .. - make +From this directory, run the following to compile: + +```bash +cmake -B build +cmake --build build +``` ### Run - ./each +```bash +cd build +./each +``` + +This will generate `./build/each.data` which is the performance data. + +### Generate and view plots + +One the above program is complete, generate the plots. + +```bash +cd build +# Generate plots +gnuplot -e "filename='each.data'" ../each.gp +eog *.png +``` -### Generate and view plot +You can now scroll through two plots to view performance data. - gnuplot -e "filename='each.data'" ../each.gp - eog *.png diff --git a/examples/standalone/entity_creation/README.md b/examples/standalone/entity_creation/README.md index 578ecf3d6b..53cdb8db79 100644 --- a/examples/standalone/entity_creation/README.md +++ b/examples/standalone/entity_creation/README.md @@ -2,24 +2,21 @@ ## Build -``` -mkdir build -cd build -cmake .. -make +```bash +cmake -B build +cmake --build build ``` ## Run This example only works if the world is called `empty`. Start an empty world with: -``` +```bash gz sim empty.sdf ``` Then run the create program to spawn entities into the world: -``` -cd build -./entity_creation +```bash +./build/entity_creation ``` diff --git a/examples/standalone/external_ecm/README.md b/examples/standalone/external_ecm/README.md index 6d917f3f43..42c5f075e0 100644 --- a/examples/standalone/external_ecm/README.md +++ b/examples/standalone/external_ecm/README.md @@ -3,17 +3,14 @@ Example showing how to get a snapshot of all entities and components in a running simulation from an external program using the state message. -## Build +## Build Instructions -From the root of the `gz-sim` repository, do the following to build the example: +From this directory, run the following to compile: -~~~ -cd gz-sim/examples/standalone/external_ecm -mkdir build -cd build -cmake .. -make -~~~ +```bash +cmake -B build +cmake --build build +``` This will generate the `external_ecm` executable under `build`. @@ -21,17 +18,20 @@ This will generate the `external_ecm` executable under `build`. Start a simulation, for example: - gz sim shapes.sdf +```bash +gz sim shapes.sdf +``` -On another terminal, run the `external_ecm` executable, passing the name of the +In another terminal, from this directory, run the `external_ecm` executable, passing the name of the running world you want to inspect: - cd gz-sim/examples/standalone/external_ecm - ./external_ecm shapes +```bash +./build/external_ecm shapes +``` You should see something like this: -``` +```text $ ./external_ecm shapes Requesting state for world [shapes] on service [/world/shapes/state]... diff --git a/examples/standalone/gtest_setup/CMakeLists.txt b/examples/standalone/gtest_setup/CMakeLists.txt index ee03ecce4c..ed1f8d7b40 100644 --- a/examples/standalone/gtest_setup/CMakeLists.txt +++ b/examples/standalone/gtest_setup/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.11.0 FATAL_ERROR) +cmake_minimum_required(VERSION 3.16 FATAL_ERROR) project(GTestSetup) @@ -6,32 +6,28 @@ project(GTestSetup) find_package(gz-sim8 REQUIRED) set(GZ_SIM_VER ${gz-sim8_VERSION_MAJOR}) -# Fetch and configure GTest -include(FetchContent) -FetchContent_Declare( - googletest - # Version 1.14. Use commit hash to prevent tag relocation - URL https://github.com/google/googletest/archive/f8d7d77c06936315286eb55f8de22cd23c188571.zip -) -set(gtest_force_shared_crt ON CACHE BOOL "" FORCE) -FetchContent_MakeAvailable(googletest) +find_package(GTest REQUIRED) +if(NOT TARGET GTest::gtest_main AND TARGET gtest_main) + add_library(GTest::gtest_main ALIAS gtest_main) +endif() -enable_testing() -include(Dart) +include(CTest) +# CTest defines "BUILD_TESTING" so that users can easily disable tests in a common way. +if(BUILD_TESTING) + # Generate tests + foreach(TEST_TARGET + command_TEST + gravity_TEST) -# Generate tests -foreach(TEST_TARGET - command_TEST - gravity_TEST) - - add_executable( - ${TEST_TARGET} - ${TEST_TARGET}.cc - ) - target_link_libraries(${TEST_TARGET} - gtest_main - gz-sim${GZ_SIM_VER}::gz-sim${GZ_SIM_VER} - ) - include(GoogleTest) - gtest_discover_tests(${TEST_TARGET}) -endforeach() + add_executable( + ${TEST_TARGET} + ${TEST_TARGET}.cc + ) + target_link_libraries(${TEST_TARGET} + GTest::gtest_main + gz-sim${GZ_SIM_VER}::gz-sim${GZ_SIM_VER} + ) + include(GoogleTest) + gtest_discover_tests(${TEST_TARGET}) + endforeach() +endif() diff --git a/examples/standalone/gtest_setup/README.md b/examples/standalone/gtest_setup/README.md index 8d95b90bf7..21d5c469a8 100644 --- a/examples/standalone/gtest_setup/README.md +++ b/examples/standalone/gtest_setup/README.md @@ -9,18 +9,37 @@ The example contains 2 tests: See the comments on the source code for more explanations. -## Build +## Build Instructions -From the root of the repository: +From this directory, run the following to compile: - cd examples/standalone/gtest_setup - mkdir build - cd build - cmake .. - make +```bash +cmake -B build +cmake --build build +``` ## Run tests - cd examples/standalone/gtest_setup/build - ./gravity_TEST - ./command_TEST +From this directory, run the following to run tests: + +### CMake 3.20 or newer + +```bash +ctest --test-dir build +``` + +By default, ctest hides stdout from tests. +To enable test output, add `-V`. +CTest also hides colors, which can be re-enabled. +```bash +GTEST_COLOR=1 ctest -V --test-dir build +``` + + +### CMake 3.19 or earlier + +```bash +cd build +ctest +``` + diff --git a/examples/standalone/joy_to_twist/README.md b/examples/standalone/joy_to_twist/README.md index ae35890d94..086544367e 100644 --- a/examples/standalone/joy_to_twist/README.md +++ b/examples/standalone/joy_to_twist/README.md @@ -6,17 +6,14 @@ messages and converts publishes [gz::msgs::Twist](https://gazebosim.org/api/msgs/9/classgz_1_1msgs_1_1Twist.html) messages according to user-defined configuration. -## Build +## Build Instructions -From the root of the `gz-sim` repository, do the following to build the example: +From this directory, run the following to compile: -~~~ -cd examples/standalone/joy_to_twist -mkdir build -cd build -cmake .. -make -~~~ +```bash +cmake -B build +cmake --build build +``` This will generate the `joy_to_twist` executable under `build`. @@ -27,7 +24,9 @@ An example file, `joy_to_twist.sdf`, is provided. You can run the example as follows: - ./joy_to_twist ../joy_to_twist.sdf +```bash +./build/joy_to_twist joy_to_twist.sdf +``` This program by itself won't do much unless there is another source of joy messages that it can consume. See the demo below for a full integrated example. @@ -41,8 +40,10 @@ that can be controlled using a joystick. You can run it as follows: messages. See that standalone program's instructions to details on how to build it. Once it's built, you can run it as follows: - cd examples/standalone/joystick - ./joystick ../joystick.sdf +```bash +cd examples/standalone/joystick +./build/joystick ../joystick.sdf +``` 1. On another terminal, run the `joy_to_twist` executable as described above, which will convert joy messages to twist messages: diff --git a/examples/standalone/joystick/README.md b/examples/standalone/joystick/README.md index 9c8782a0ab..36670a539a 100644 --- a/examples/standalone/joystick/README.md +++ b/examples/standalone/joystick/README.md @@ -6,17 +6,14 @@ messages from a joystick device using Gazebo Transport. The mapping of joystick buttons to fields in the message is the same as [this](http://wiki.ros.org/joy). -## Build +## Build Instructions -From the root of the `gz-sim` repository, do the following to build the example: +From this directory, run the following to compile: -~~~ -cd examples/standalone/joystick -mkdir build -cd build -cmake .. -make -~~~ +```bash +cmake -B build +cmake --build build +``` This will generate the `joystick` executable under `build`. @@ -27,7 +24,9 @@ An example file, `joystick.sdf`, is provided. You can run the example as follows: - ./joystick ../joystick.sdf +```bash +./build/joystick joystick.sdf +``` You may get error messages if a joystick is not found or the SDF file is invalid. Make sure you have a joystick connected and that the correct device is passed in @@ -39,7 +38,9 @@ the SDF file's `` tag, which defaults to `/dev/input/js0`. If no errors are printed, you can check that the messages are being published by echoing the `/joy` topic: - gz topic echo -t /joy +```bash +gz topic echo -t /joy +``` ## Demo example @@ -50,14 +51,15 @@ that can be controlled using a joystick. You can run it as follows: joystick messages: cd examples/standalone/joystick - ./joystick ../joystick.sdf + ./build/joystick joystick.sdf -1. On another terminal, run the `joy_to_twist` executable to convert joy - messages to twist messages. See that standalone program's instructions for - details on how to build it. Once it's built, you can run it as follows: +1. On another terminal, build and run the `joy_to_twist` executable to convert joy + messages to twist messages. See that + [standalone program's instructions](../joy_to_twist/README.md) + for details on how to build it. Once it's built, you can run it as follows: cd examples/standalone/joy_to_twist - ./joy_to_twist ../joy_to_twist.sdf + ./build/joy_to_twist joy_to_twist.sdf 1. Finally, on a 3rd terminal, run `gz sim` with the vehicle that will consume the twist messages: