From 5ca065b7249fd62fff0a9fc1861fe2b649fdf281 Mon Sep 17 00:00:00 2001 From: Silvio Traversaro Date: Tue, 13 Aug 2024 17:32:08 +0200 Subject: [PATCH] Add documentation --- README.md | 5 +++ docs/build-from-source.md | 9 ++++- .../gz-sim-yarp-plugins-check-model/README.md | 37 +++++++++++++++++++ 3 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 tools/gz-sim-yarp-plugins-check-model/README.md diff --git a/README.md b/README.md index 7385891..6f3a40b 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,11 @@ models > [!WARNING] > It is possible, but strongly discouraged, to specify the location of a `yarpConfigurationFile` using absolute paths or paths relative to the current working directory: the former approach is not portable, while the latter only works if the library is loaded from the directory it was intended to be loaded from. +## Tools + +This repository also contain some helper executable tools: +* [`gz-sim-yarp-plugins-check-model`](./tools/gz-sim-yarp-plugins-check-model/README.md): Tool to automatically check if a world or a model that uses gz-sim-yarp-plugins is able to load correctly. + ## Run Tests To run the tests, just configure the project with the `BUILD_TESTING` option, and run `ctest`: diff --git a/docs/build-from-source.md b/docs/build-from-source.md index 83abe15..52947a9 100644 --- a/docs/build-from-source.md +++ b/docs/build-from-source.md @@ -25,7 +25,7 @@ in addition to the usual dependencies used to configure, compile and test C++ pa If you are using conda (or mamba), the dependencies of `gz-sim-yarp-plugins` can be installed with: ```bash -conda install -c conda-forge libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest +conda install -c conda-forge libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest cli11 ``` This command should be executed in a terminal with the environment activated. @@ -115,3 +115,10 @@ export GZ_SIM_SYSTEM_PLUGIN_PATH=${GZ_SIM_SYSTEM_PLUGIN_PATH}: ~~~ where `` is the directory passed to `CMAKE_INSTALL_PREFIX` during the CMake configuration. + +To ensure that the tools are found, instead you need to add their location to the `PATH`: + +~~~ +export PATH=${PATH}:/bin +~~~ + diff --git a/tools/gz-sim-yarp-plugins-check-model/README.md b/tools/gz-sim-yarp-plugins-check-model/README.md new file mode 100644 index 0000000..1fb3de3 --- /dev/null +++ b/tools/gz-sim-yarp-plugins-check-model/README.md @@ -0,0 +1,37 @@ +# gz-sim-yarp-plugins-check-model + +The `gz-sim-yarp-plugins-check-model` is an helper tool that can be used to check automatically if a world or a model containing `gz-sim-yarp-plugins` is able to start correctly, and if all the `gz-sim-yarp-plugins` in it load correctly. It can be useful to automatically check in Continuous Integration if some model or world contained in a given repo (and all its associated configuration file) are able to load. + +If you want to check if a world is able to load correctly, you can run the tool as: + +~~~ +gz-sim-yarp-plugins-check-model --world-file ./local/to/world.sdf +~~~ + +while to check if a model is able to load correctly, you can pass: + +~~~ +gz-sim-yarp-plugins-check-model --model-uri model://ergoCubGazeboV1 +~~~ + +The tool will return 0 as exit value if the world or model loaded correctly, or 1 if there was an error in the loading. + +For more information and options, run `gz-sim-yarp-plugins-check-model --help`. + + +## Usage in CI + +To run the tool in CI, you can just invoke it in your CI script with the file or model you want to check as: + +~~~ +gz-sim-yarp-plugins-check-model --model-uri model://ergoCubGazeboV1 +~~~ + +Remember that environment variables such as `GZ_SIM_RESOURCE_PATH` used to find `model://` files need to be set for the tool to work appropriately. + +You can also use the tool as part of a CMake test, with the following CMake code: + +~~~cmake +add_test(NAME project-check-world-loads-correctly + COMMAND gz-sim-yarp-plugins-check-model --world-file ${PROJECT_SOURCE_DIR}/location/of/world/file.sdf) +~~~