Skip to content

Latest commit

 

History

History
140 lines (108 loc) · 6.69 KB

Migration.md

File metadata and controls

140 lines (108 loc) · 6.69 KB
Raw

Note on deprecations

A tick-tock release cycle allows easy migration to new software versions. Obsolete code is marked as deprecated for one major release. Deprecated code produces compile-time warnings. These warning serve as notification to users that their code should be upgraded. The next major release will remove the deprecated code.

Gazebo Common 4.X to 5.X

Deprecations

  1. Submesh::MaterialIndex is deprecated. SubMesh::GetMaterialIndex should be used instead, which properly handles submeshes having no material index applied to them.
  2. The ignition namespace is deprecated and will be removed in future versions. Use gz instead.
  3. Header files under ignition/... are deprecated and will be removed in future versions. Use gz/... instead.
  4. The logging macros (ignmsg, ignwarn, ignerr, etc.) and logging function macros (ignLogInit(), etc.) are deprecated and will be removed in future versions. Use gz instead (e.g. gzmsg, gzwarn, gzLogInit())
  5. All the plugin APIs are deprecated, use the gz-plugin library instead. See the migration guide.
  6. The following IGN_ prefixed environment variables are deprecated and will be removed. Please use the GZ_ prefixed versions instead!
    1. IGN_VIDEO_ALLOWED_ENCODERS -> GZ_VIDEO_ALLOWED_ENCODERS
    2. IGN_VIDEO_ENCODER_DEVICE -> GZ_VIDEO_ENCODER_DEVICE
    3. IGN_VIDEO_USE_HW_SURFACE -> GZ_VIDEO_USE_HW_SURFACE
    4. IGN_FILE_PATH -> GZ_FILE_PATH
    5. IGN_LOG_PATH -> GZ_LOG_PATH
    6. IGN_PLUGIN_PATH -> GZ_PLUGIN_PATH
  7. The following IGN_ / IGNITION_ prefixed macros are deprecated and will be removed in future versions. Additionally, they will only be available when including the corresponding ignition/... header. Use the GZ_ prefix instead.
    1. IGN_ENUM
    2. IGN_HOMEDIR
    3. IGN_NANO_TO_SEC, IGN_SEC_TO_NANO, IGN_MS_TO_NANO, IGN_US_TO_NANO
    4. IGN_SPEED_OF_LIGHT
    5. IGN_SLEEP_S, IGN_SLEEP_US, IGN_SLEEP_MS, IGN_SLEEP_NS
    6. IGN_SYSTEM_TIME, IGN_SYSTEM_TIME_S, IGN_SYSTEM_TIME_US, IGN_SYSTEM_TIME_MS, IGN_SYSTEM_TIME_NS
    7. IGN_ASSERT
    8. IGNITION_COMMON_TINYOBJLOADER_IMPLEMENTATION (src local, hard-tocked)
    9. IGN_PROFILER_ENABLE, IGN_PROFILE_THREAD_NAME, IGN_PROFILE_LOG_TEXT, IGN_PROFILE_BEGIN, IGN_PROFILE_END, IGN_PROFILE_L, IGN_PROFILE, IGN_PROFILE_VALID
    10. IGN_CREATE_SPEC_INTERFACE
    11. IGN_DUMMY_PLUGIN_PATH
    12. IGNITION_UNITTEST_SPECIALIZED_PLUGIN_ACCESS
  8. The Image::Data(unsigned char**, unsigned int&) functions that accept a pointer and a size and internally allocate memory are deprecated and will be removed in future versions. Use the new Data functions that return a std::vector<unsigned char> to have automatic memory management.

Breaking Changes

  1. The project name has been changed to use the gz- prefix, you must use the gz prefix!
  • This also means that any generated code that use the project name (e.g. CMake variables, in-source macros) would have to be migrated.
  • Some non-exhaustive examples of this include:
    • GZ_<PROJECT>_<VISIBLE/HIDDEN>
    • CMake -config files
    • Paths that depend on the project name

Additions

  1. geospatial component that loads heightmap images and DEMs
    • Depends on the gz-common's graphics component and the gdal library

Modifications

  1. HeightmapData.hh and ImageHeightmap.hh have been moved out of the graphics component and into the new geospatial component

    • To use the heightmap features, users must add the geospatial component to the find_package call and update the include paths to use the geospatial subfolder (#include <ignition/common/geospatial/HeightmapData.hh>)

  2. HeightmapData::FillHeightmap method is now const.

  3. Image::AvgColor, Image::Data and Image::RGBData methods are now const.

Gazebo Common 3.X to 4.X

Modifications

  1. Corrected BAYER_RGGR8 to BAYER_BGGR8 in PixelFormatName and PixelFormatType located in graphics/include/gz/common/Image.hh.

  2. URI parsing has updated to follow the specification more closely when URI::Authority is set. Changes include:

    • An empty URI Path is valid.
    • Double forward slashes, //, are valid in a URI Path.
    • A URI Query does not require a key=value format. For example a valid query can be "?aquery", "?aquery?", and ??.
    • A URI authority is optional. If present, then a URI authority begins with two forward slashes and immediately follows the URI scheme. A host must be present if an authority is present and the scheme != 'file'.

Gazebo Common 2.X to 3.X

Additions

  1. Event.hh

    • Added second template argument to EventT to disambiguate events with matching signatures.

  2. profiler component that helps measure software performance.

  3. SystemPaths.hh

    • Search paths specified in GZ_FILE_PATH environment variable when finding files.

  4. Util.hh

    • Added constexpr uint64_t hash64(std::string_view) to generate a hash at compile time if possible.

Modifications

  1. Depends on gz-cmake2

    • gz-common now depends on gz-cmake2.

  2. Requires c++17.

  3. (New in 3.8.0) On Windows, the value of C++ macro GZ_HOMEDIR changed from HOMEPATH to USERPROFILE. It is usually used to read the path to the user's home from environment. The old value pointed to a path relative to the (a) current drive letter as reported by pwd, not the system drive letter. The new value correctly points to an environment variable that contains the full absolute path to the user's profile. If the code did not use the macro in some unexpected way, the new behavior should work either the same or even better (it would work even when the current directory is on a non-system drive). If the code relied on this value to be relative to the current drive letter, it needs to be changed to use HOMEPATH directly.

Gazebo Common 1.X to 2.X

Modifications

  1. Depends on gz-cmake1

    • gz-common now depends on gz-cmake1, which provides support for Component libraries.

  2. Component libraries

    • Some classes have been moved from the main gz-common library to component libraries. To use these features, you must list them in the find_package call and link against them.
      • av: audio and video playback and encoding
      • events: registering and handling event callbacks
      • graphics: animation, images, and triangle meshes

Gazebo Common 0.X to 1.X

Added dependencies

  1. gz-cmake
    • gz-math now has a build dependency on gz-cmake, which allows cmake scripts to be shared across all the Gazebo packages.