gazebosim/gz-utils

Classes and functions for robot applications

Gazebo Utils : Classes and functions for robot applications

Maintainer: addisu AT openrobotics DOT org

Build	Status
Test coverage
Ubuntu Jammy
Homebrew
Windows

Gazebo Utils, a component of Gazebo, provides general purpose classes and functions designed for robotic applications.

Table of Contents

Features

Install

Usage

Documentation

Testing

Folder Structure

Code of Conduct

Contributing

Versioning

License

Features

Gazebo Utils provides a wide range of functionality, including:

• A helper class to implement the PIMPL pattern
• A command line parsing utility (vendored CLI11)
• Macros to suppress warnings

Install

See the installation tutorial.

Usage

Please refer to the examples directory.

Documentation

API and tutorials can be found at https://gazebosim.org/libs/utils.

You can also generate the documentation from a clone of this repository by following these steps.

1. You will need Doxygen. On Ubuntu Doxygen can be installed using

   sudo apt-get install doxygen
   

2. Clone the repository

   git clone https://github.com/gazebosim/gz-utils
   

3. Configure and build the documentation.

   cd gz-utils; mkdir build; cd build; cmake ../; make doc
   

4. View the documentation by running the following command from the build directory.

   firefox doxygen/html/index.html
   

Testing

Follow these steps to run tests and static code analysis in your clone of this repository.

1. Follow the source install instruction.

2. Run tests.

   make test
   

3. Static code checker.

   make codecheck
   

Folder Structure

Refer to the following table for information about important directories and files in this repository.

gz-utils
├── cli                      Gazebo CLI component. Vendored from https://github.com/CLIUtils/CLI11/
├── examples                 Example programs.
├── include/gz/utils         Header files.
├── src                      Source files and unit tests.
├── test
│    ├── integration         Integration tests.
│    ├── performance         Performance tests.
│    └── regression          Regression tests.
├── tutorials                Tutorials, written in markdown.
├── Changelog.md             Changelog.
└── CMakeLists.txt           CMake build script.

Contributing

Please see CONTRIBUTING.md.

Code of Conduct

Please see CODE_OF_CONDUCT.md

Versioning

This library uses Semantic Versioning. Additionally, this library is part of the Gazebo project which periodically releases a versioned set of compatible and complimentary libraries. See the Gazebo website for version and release information.

License

This library is licensed under Apache 2.0. See also the LICENSE file.

gz-utils's Issues

cli: add custom formatter for help strings

Desired behavior

The default format of help strings with the cli component is a bit different from the format we have been using in our cmd*.rb commands. Different is not necessarily worse, but I am noticing a specific issue with the formatting while reviewing gazebosim/gz-plugin#65 that makes the output a bit confusing:

• Before gazebosim/gz-plugin#65:

$ ign plugin
Print information about plugins.

  ign plugin [options]

Options:

  -i [ --info ]              Get info about a plugin.
                             Requires the -p option.

  -p [ --plugin ] arg        Path to a plugin.
                             Required with -i.

  -v [ --verbose ]           Print verbose info.

  -h [ --help ]              Print this help message.
                                                    
  --force-version <VERSION>  Use a specific library version.
                                                    
  --versions                 Show the available versions.

• After gazebosim/gz-plugin#65:

$ bin/ign-plugin 
Introspect Ignition plugin
Usage: bin/ign-plugin [OPTIONS]

Options:
  -h,--help                   Print this help message and exit
  --help-all                  Show all help
  --version                   
  -v,--verbose                Verbose level
  -i,--info                   Get info about a plugin.
                              Requires the -p option.
  -p,--plugin TEXT Needs: --info
                              Path to a plugin.
                              Required with -i.

My main concern is the line -p,--plugin TEXT Needs: --info. I don't like the Needs: --info right next to TEXT without a delimiter or something to indicate that you shouldn't type Needs: on the command line. I'm guessing people will be able to figure it out, but it would be nice to be able to tidy this up.

Alternatives considered

Leave it as is I suppose.

Implementation suggestion

There is documentation about Formatting help output. One option on that page is Subclassing the CLI::Formatter class. For the -p,--plugin TEXT Needs: --info line mentioned above, this would entail overriding the make_option_opts method (and specifically this line).

We should be careful of modifying our fork of cli11 in case this package is built against an external version.

Additional context

ignition utils 1.2.0 doesn't build with ign-cmake 2.10.0 and with clang-6.0 compiler

Environment

• OS Version: Ubuntu 18.04
• Source or binary build?
  • Source build from branch releasing ign-utils 1.2.0 (3991dca05d041dba5477e5aa53f6b058183cd111)
  • compiler clang-6.0 (CC and CXX)
  • ign-cmake 2.10.0 version built from source with clang-6.0 compiler. (source branch: 7eb246daaa6248db3f7c85183789fc1e752423c9)

Description

• Expected behavior: building ign-utils 1.2.0 with clang-6.0 compiler works
• Actual behavior: linker error happens when building ign-utils 1.2.0 with clang-6.0 compiler

Steps to reproduce

To reproduce the error, you will need a system with Clang-6.0 compiler

1. Build ign-cmake 2.10.0 from source with clang-6.0 compiler

• Clone ign-cmake 2.10.0 from (here)
• Browse to repository, open a terminal in it and run

mkdir build 
cd build

• ensure compiler is set to clang-6.0:

export CC=clang-6.0 
export CXX=clang++-6.0

• create a local installation dir for ign-cmake:

mkdir $HOME/ign-cmake-2.10.0

• build and install ign-cmake-2.10.0:

cmake -DCMAKE_INSTALL_PREFIX=$HOME/ign-cmake-2.10.0 ..
make
make install

2. Build ign-uitls 1.2.0 from source with clang-6.0 compiler

• clone ign-utils 1.2.0 (from here)
• browse to the repository, open a terminal in it and run

mkdir build 
cd build

• ensure compilers are set to clang-6.0:

export CC=clang-6.0 
export CXX=clang++-6.0

• build ign-utils with correct prefix path to ign-cmake-2.10.0:

cmake -DCMAKE_PREFIX_PATH=$HOME/ign-cmake-2.10.0 ..
make

Output

Cmake configuration for ign-utils:

g.gulgulia:~/gg_workspace/ign-utils/build$ export CXX=clang++-6.0
g.gulgulia:~/gg_workspace/ign-utils/build$ export CC=clang-6.0
g.gulgulia:~/gg_workspace/ign-utils/build$ cmake -DCMAKE_PREFIX_PATH=$HOME/ign-cmake-2.10.0 ..
-- The C compiler identification is Clang 6.0.0
-- The CXX compiler identification is Clang 6.0.0
-- Check for working C compiler: /usr/bin/clang-6.0
-- Check for working C compiler: /usr/bin/clang-6.0 -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/clang++-6.0
-- Check for working CXX compiler: /usr/bin/clang++-6.0 -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- ignition-utils1 version 1.2.0
-- Operating system is Linux
-- Found CPack generators: DEB
-- 
-- Searching for host SSE information
-- SSE2 found
-- SSE3 found
-- SSE4.1 found
-- SSE4.2 found
-- Configuring library: ignition-utils1
-- Performing Test COMPILER_HAS_HIDDEN_VISIBILITY
-- Performing Test COMPILER_HAS_HIDDEN_VISIBILITY - Success
-- Performing Test COMPILER_HAS_HIDDEN_INLINE_VISIBILITY
-- Performing Test COMPILER_HAS_HIDDEN_INLINE_VISIBILITY - Success
-- Performing Test COMPILER_HAS_DEPRECATED_ATTR
-- Performing Test COMPILER_HAS_DEPRECATED_ATTR - Success
-- Adding 2 UNIT tests
-- No tests have been specified for INTEGRATION
-- Adding 1 INTEGRATION tests
-- No tests have been specified for PERFORMANCE
-- No tests have been specified for REGRESSION
-- Configuring library: ignition-utils1-cli
-- The program [cppcheck] was not found! Skipping codecheck setup
-- Build configuration successful
-- Build type: RelWithDebInfo
-- Install prefix: /usr/local
-- Looking for ronn to generate manpages - found
-- Found Doxygen: /usr/bin/doxygen (found version "1.8.13") found components:  doxygen dot 
-- Configuring done
-- Generating done
-- Build files have been written to: /home/g.gulgulia/gg_workspace/ign-utils/build

To check if ign-cmake 2.10.0 was correctly used, I ran from build dir: ccmake .. . The output is below:

 BUILD_DOCS                       ON                                                                                                                                                                              
 BUILD_SHARED_LIBS                ON                                                                                                                                                                              
 BUILD_TESTING                    ON                                                                                                                                                                              
 CMAKE_BUILD_TYPE                                                                                                                                                                                                 
 CMAKE_INSTALL_PREFIX             /usr/local                                                                                                                                                                      
 CPPCHECK_PATH                    CPPCHECK_PATH-NOTFOUND                                                                                                                                                          
 DPKG_PROGRAM                     /usr/bin/dpkg                                                                                                                                                                   
 FIND_PATH                        /usr/bin/find                                                                                                                                                                   
 GZIP                             /bin/gzip                                                                                                                                                                       
 IGN_UTILS_VENDOR_CLI11           ON                                                                                                                                                                              
 PYTHON_VERSION                                                                                                                                                                                                   
 RONN                             /usr/bin/ronn                                                                                                                                                                   
 RPMBUILD_PROGRAM                 RPMBUILD_PROGRAM-NOTFOUND                                                                                                                                                       
 SSE2_FOUND                       ON                                                                                                                                                                              
 SSE3_FOUND                       ON                                                                                                                                                                              
 SSE4_1_FOUND                     ON                                                                                                                                                                              
 SSE4_2_FOUND                     ON                                                                                                                                                                              
 SSSE3_FOUND                      ON                                                                                                                                                                              
 USE_FULL_RPATH                   OFF                                                                                                                                                                             
 USE_HOST_SSE_FLAGS               ON                                                                                                                                                                              
 USE_IGN_RECOMMENDED_FLAGS        ON                                                                                                                                                                              
 ignition-cmake2_DIR              /home/g.gulgulia/ign-cmake-2.10.0/share/cmake/ignition-cmake2

after that I build ign-utils and encounter a linker error when UNIT_Environment_TEST is being linked against library Environment

g.gulgulia:~/gg_workspace/ign-utils/build$ make
-- ignition-utils1 version 1.2.0
-- Operating system is Linux
-- Found CPack generators: DEB
-- 
-- Searching for host SSE information
-- SSE2 found
-- SSE3 found
-- SSE4.1 found
-- SSE4.2 found
-- Configuring library: ignition-utils1
-- Adding 2 UNIT tests
-- No tests have been specified for INTEGRATION
-- Adding 1 INTEGRATION tests
-- No tests have been specified for PERFORMANCE
-- No tests have been specified for REGRESSION
-- Configuring library: ignition-utils1-cli
-- The program [cppcheck] was not found! Skipping codecheck setup
-- Build configuration successful
-- Build type: RelWithDebInfo
-- Install prefix: /usr/local
-- Looking for ronn to generate manpages - found
-- Configuring done
-- Generating done
-- Build files have been written to: /home/g.gulgulia/gg_workspace/ign-utils/build
Scanning dependencies of target doc
[  6%] Generating API documentation with Doxygen
[  6%] Built target doc
Scanning dependencies of target gtest
[ 13%] Building CXX object test/CMakeFiles/gtest.dir/gtest/src/gtest-all.cc.o
[ 20%] Linking CXX static library ../lib/libgtest.a
[ 20%] Built target gtest
Scanning dependencies of target ignition-utils1
[ 26%] Building CXX object src/CMakeFiles/ignition-utils1.dir/Environment.cc.o
[ 33%] Linking CXX shared library ../lib/libignition-utils1.so
[ 33%] Built target ignition-utils1
Scanning dependencies of target gtest_main
[ 40%] Building CXX object test/CMakeFiles/gtest_main.dir/gtest/src/gtest_main.cc.o
[ 46%] Linking CXX static library ../lib/libgtest_main.a
[ 46%] Built target gtest_main
Scanning dependencies of target UNIT_Environment_TEST
[ 53%] Building CXX object src/CMakeFiles/UNIT_Environment_TEST.dir/Environment_TEST.cc.o
[ 60%] Linking CXX executable ../bin/UNIT_Environment_TEST
CMakeFiles/UNIT_Environment_TEST.dir/Environment_TEST.cc.o: In function `Environment_emptyENV_Test::TestBody()':
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:28: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
CMakeFiles/UNIT_Environment_TEST.dir/Environment_TEST.cc.o: In function `Environment_envSet_Test::TestBody()':
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:36: undefined reference to `ignition::utils::v1::setenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:41: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:49: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:57: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:62: undefined reference to `ignition::utils::v1::unsetenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
CMakeFiles/UNIT_Environment_TEST.dir/Environment_TEST.cc.o: In function `Environment_envUnset_Test::TestBody()':
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:69: undefined reference to `ignition::utils::v1::unsetenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:74: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:81: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:88: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:91: undefined reference to `ignition::utils::v1::unsetenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
CMakeFiles/UNIT_Environment_TEST.dir/Environment_TEST.cc.o: In function `Util_TEST_envSetEmpty_Test::TestBody()':
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:99: undefined reference to `ignition::utils::v1::setenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:100: undefined reference to `ignition::utils::v1::setenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:105: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:121: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:129: undefined reference to `ignition::utils::v1::env(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >&, bool)'
/home/g.gulgulia/gg_workspace/ign-utils/src/Environment_TEST.cc:132: undefined reference to `ignition::utils::v1::unsetenv(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&)'
clang: error: linker command failed with exit code 1 (use -v to see invocation)
src/CMakeFiles/UNIT_Environment_TEST.dir/build.make:98: recipe for target 'bin/UNIT_Environment_TEST' failed
make[2]: *** [bin/UNIT_Environment_TEST] Error 1
CMakeFiles/Makefile2:1088: recipe for target 'src/CMakeFiles/UNIT_Environment_TEST.dir/all' failed
make[1]: *** [src/CMakeFiles/UNIT_Environment_TEST.dir/all] Error 2
Makefile:162: recipe for target 'all' failed
make: *** [all] Error 2

Here's a screenshot of the error

Note: I tried the same steps but with clang-8 and clang-9, and ign-utils could be compiled with clang-8 and clang-9

Warning suppression macros conflict with those provided by ign-cmake

Both ign-utils and ign-cmake define macros with the same name, such as IGN_UTILS_WARN_IGNORE__NON_VIRTUAL_DESTRUCTOR and DETAIL_IGN_UTILS_WARN_IGNORE__NON_VIRTUAL_DESTRUCTOR:

• https://github.com/ignitionrobotics/ign-cmake/blob/ignition-cmake2_2.6.2/include/ignition/utilities/SuppressWarning.hh
• https://github.com/ignitionrobotics/ign-utils/blob/main/include/ignition/utils/SuppressWarning.hh

these header files have different header guards, though, leading to compiler warnings on windows if both are included together:

• https://build.osrfoundation.org/job/sdformat-ci-pr_any-windows7-amd64/1908/msbuild/new/

Perhaps we need to wrap all our #define statements in #ifndef?

fatal error: gz/utils/Export.hh: No such file or directory

Trying to do a clean build of Garden results in:

colcon build --cmake-args -DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Debug -DBUILD_DOCS=OFF --merge-install
Starting >>> OGRE    
Starting >>> ignition-tools2
Finished <<< ignition-tools2 [0.10s]                                                   
Finished <<< OGRE [0.58s]                     
Starting >>> ignition-cmake3
Finished <<< ignition-cmake3 [0.05s]                   
Starting >>> ignition-utils2
--- stderr: ignition-utils2
In file included from /home/matias/Projects/ign/src/ign-utils/include/ignition/utils/Environment.hh:18,
                 from /home/matias/Projects/ign/src/ign-utils/src/Environment.cc:18:
/home/matias/Projects/ign/src/ign-utils/include/gz/utils/Environment.hh:22:10: fatal error: gz/utils/Export.hh: No such file or directory
   22 | #include <gz/utils/Export.hh>
      |          ^~~~~~~~~~~~~~~~~~~~
compilation terminated.
make[2]: *** [src/CMakeFiles/ignition-utils2.dir/build.make:63: src/CMakeFiles/ignition-utils2.dir/Environment.cc.o] Error 1
make[1]: *** [CMakeFiles/Makefile2:363: src/CMakeFiles/ignition-utils2.dir/all] Error 2
make: *** [Makefile:163: all] Error 2
---
Failed   <<< ignition-utils2 [0.05s, exited with code 2]

Summary: 3 packages finished [1.00s]
  1 package failed: ignition-utils2
  1 package had stderr output: ignition-utils2
  13 packages not processed

Environment

• OS Version: Ubuntu 20.04.4 LTS
• Source or binary build?
  b802e60

Description

• Expected behavior: Build correctly
• Actual behavior: Compiler errors

Steps to reproduce

The ones described in https://gazebosim.org/docs/garden/install_ubuntu_src

Require DCO

This repository doesn't have DCO checks configured.

Feature request: add macros for arm64 and armhf in ExtraTestMacros.hh

Desired behavior

Currently there are macros in ExtraTestMacros.hh to disable tests for different platforms, and we seem to be finding more and more test failures in arm64 and armhf platforms. It would be convenient to have macros for skipping tests for those architectures.

Alternatives considered

Implementation suggestion

Additional context

IgnitionFormatter.hpp renamed to GzFormatter.hpp

@mjcarroll, should this file IgnitionFormatter.hpp need to be renamed to GzFormatter.hpp ?

Migrate environment variable functions to utils

Migrate environment manipulation functionality from ign-common to ign-utils.