ign -> gz Environment Variable Migration : gz-common

Migration.md

@@ -19,9 +19,19 @@ release will remove the deprecated code.
    (`ignLogInit()`, etc.) are deprecated and will be removed in future versions. Use `gz` instead
    (e.g. `gzmsg`, `gzwarn`, `gzLogInit()`)
 
-1. All the plugin APIs are deprecated, use the gz-plugin library instead. See
+5. All the plugin APIs are deprecated, use the gz-plugin library instead. See
    the [migration guide](https://github.com/ignitionrobotics/ign-plugin/blob/ign-plugin1/MIGRATION.md).
 
+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`
+
+
 ### Additions
 
 1. **geospatial** component that loads heightmap images and DEMs
@@ -66,7 +76,7 @@ release will remove the deprecated code.
 1. **profiler** component that helps measure software performance.
 
 1. **SystemPaths.hh**
-    + Search paths specified in `IGN_FILE_PATH` environment variable when
+    + Search paths specified in `GZ_FILE_PATH` environment variable when
       finding files.
 
 1. **Util.hh**

av/include/gz/common/VideoEncoder.hh

@@ -70,19 +70,19 @@ namespace gz
       /// failure isn't a result of faulty HW encoding (e.g. when NVENC sessions
       /// are exhausted).
       /// \note This will automatically select a HW-accelerated encoder based
-      /// on the values of environment variables IGN_VIDEO_ALLOWED_ENCODERS,
-      /// IGN_VIDEO_ENCODER_DEVICE and IGN_VIDEO_ENCODER_USE_HW_SURFACE.
+      /// on the values of environment variables GZ_VIDEO_ALLOWED_ENCODERS,
+      /// GZ_VIDEO_ENCODER_DEVICE and GZ_VIDEO_ENCODER_USE_HW_SURFACE.
       /// To completely avoid trying to set up HW accelerated encoding,
-      /// set IGN_VIDEO_ALLOWED_ENCODERS to value NONE or leave it empty or
+      /// set GZ_VIDEO_ALLOWED_ENCODERS to value NONE or leave it empty or
       /// unset.
       /// The meaning of these variables is the following:
-      /// - IGN_VIDEO_ALLOWED_ENCODERS is a colon-separated list of values of
+      /// - GZ_VIDEO_ALLOWED_ENCODERS is a colon-separated list of values of
       /// HWEncoderType enum, or ALL to allow all encoders. Default is NONE.
-      /// - IGN_VIDEO_ENCODER_DEVICE optionally specifies the HW device
+      /// - GZ_VIDEO_ENCODER_DEVICE optionally specifies the HW device
       /// to use for encoding (used only when a matching encoder is found
       /// first). By default, an empty string is used, which means to use
       /// whatever device is found to work first.
-      /// - IGN_VIDEO_USE_HW_SURFACE specifies whether the encoder should use
+      /// - GZ_VIDEO_USE_HW_SURFACE specifies whether the encoder should use
       /// an explicit GPU buffer for video frames. Some codecs do this
       /// implicitly, and then this setting has no meaning (setting it to 1 can
       /// actually decrease performance). For codecs that need to set this

av/src/CMakeLists.txt

@@ -1,9 +1,17 @@
-option(IGN_COMMON_BUILD_HW_VIDEO
+option(GZ_COMMON_BUILD_HW_VIDEO
   "Build support for HW-accelerated video encoding" ON)
 
-ign_get_libsources_and_unittests(sources gtest_sources)
+# TODO(CH3): Deprecated. Remove on tock.
+option(IGN_COMMON_BUILD_HW_VIDEO
+  "Deprecated option for building support for HW-accelerated video encoding" ON)
 
 if(NOT IGN_COMMON_BUILD_HW_VIDEO)
+  set(GZ_COMMON_BUILD_HW_VIDEO IGN_COMMON_BUILD_HW_VIDEO)
+endif()
+
+ign_get_libsources_and_unittests(sources gtest_sources)
+
+if(NOT GZ_COMMON_BUILD_HW_VIDEO)
   list(REMOVE_ITEM sources HWEncoder.cc)
 endif()
 
@@ -17,15 +25,14 @@ target_link_libraries(${av_target}
     AVCODEC::AVCODEC
     AVUTIL::AVUTIL)
 
-if(IGN_COMMON_BUILD_HW_VIDEO)
-  target_compile_definitions(${av_target} PRIVATE IGN_COMMON_BUILD_HW_VIDEO)
+if(GZ_COMMON_BUILD_HW_VIDEO)
+  target_compile_definitions(${av_target} PRIVATE GZ_COMMON_BUILD_HW_VIDEO)
 endif()
 
 ign_build_tests(
-  TYPE UNIT 
+  TYPE UNIT
   SOURCES ${gtest_sources}
   LIB_DEPS
     ${av_target}
     ignition-common${IGN_COMMON_VER}-testing
 )
-

av/src/VideoEncoder.cc

@@ -24,7 +24,7 @@
 #include "gz/common/VideoEncoder.hh"
 #include "gz/common/StringUtils.hh"
 
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
 #include "gz/common/HWEncoder.hh"
 #endif
 
@@ -98,7 +98,7 @@ class GZ_COMMON_AV_HIDDEN gz::common::VideoEncoder::Implementation
   /// \brief Mutex for thread safety.
   public: std::mutex mutex;
 
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   /// \brief The HW encoder configuration (optional).
   public: std::unique_ptr<HWEncoder> hwEncoder = nullptr;
 #endif
@@ -125,7 +125,7 @@ class GZ_COMMON_AV_HIDDEN gz::common::VideoEncoder::Implementation
 /////////////////////////////////////////////////
 const AVCodec* VideoEncoder::Implementation::FindEncoder(AVCodecID _codecId)
 {
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   if (this->hwEncoder)
     return this->hwEncoder->FindEncoder(_codecId);
 #endif
@@ -135,7 +135,7 @@ const AVCodec* VideoEncoder::Implementation::FindEncoder(AVCodecID _codecId)
 /////////////////////////////////////////////////
 AVFrame* VideoEncoder::Implementation::GetFrameForEncoder(AVFrame* _inFrame)
 {
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   if (this->hwEncoder)
     return this->hwEncoder->GetFrameForEncoder(_inFrame);
 #endif
@@ -196,7 +196,18 @@ bool VideoEncoder::Start(const std::string &_format,
   if (_allowHwAccel)
   {
     std::string allowedEncodersStr;
-    env("IGN_VIDEO_ALLOWED_ENCODERS", allowedEncodersStr);
+    env("GZ_VIDEO_ALLOWED_ENCODERS", allowedEncodersStr);
+
+    // TODO(CH3): Deprecated. Remove on tock.
+    if (allowedEncodersStr.empty())
+    {
+      env("IGN_VIDEO_ALLOWED_ENCODERS", allowedEncodersStr);
+      if (!allowedEncodersStr.empty())
+      {
+        gzwarn << "IGN_VIDEO_ALLOWED_ENCODERS is deprecated! "
+               << "Use GZ_VIDEO_ALLOWED_ENCODERS instead!" << std::endl;
+      }
+    }
 
     if (allowedEncodersStr == "ALL")
     {
@@ -213,7 +224,7 @@ bool VideoEncoder::Start(const std::string &_format,
       }
     }
 
-#ifndef IGN_COMMON_BUILD_HW_VIDEO
+#ifndef GZ_COMMON_BUILD_HW_VIDEO
     if (allowedEncoders != HWEncoderType::NONE)
     {
       gzwarn << "Hardware encoding with encoders " << allowedEncodersStr
@@ -223,10 +234,34 @@ bool VideoEncoder::Start(const std::string &_format,
     }
 #endif
 
-    env("IGN_VIDEO_ENCODER_DEVICE", device);
+    env("GZ_VIDEO_ENCODER_DEVICE", device);
+
+    // TODO(CH3): Deprecated. Remove on tock.
+    if (device.empty())
+    {
+      env("IGN_VIDEO_ENCODER_DEVICE", device);
+
+      if (!device.empty())
+      {
+        gzwarn << "IGN_VIDEO_ENCODER_DEVICE is deprecated! "
+               << "Use GZ_VIDEO_ENCODER_DEVICE instead!" << std::endl;
+      }
+    }
 
     std::string hwSurfaceStr;
-    env("IGN_VIDEO_USE_HW_SURFACE", hwSurfaceStr);
+    env("GZ_VIDEO_USE_HW_SURFACE", hwSurfaceStr);
+
+    // TODO(CH3): Deprecated. Remove on tock.
+    if (hwSurfaceStr.empty())
+    {
+      env("IGN_VIDEO_USE_HW_SURFACE", hwSurfaceStr);
+
+      if (!hwSurfaceStr.empty())
+      {
+        gzwarn << "IGN_VIDEO_USE_HW_SURFACE is deprecated! "
+               << "Use GZ_VIDEO_USE_HW_SURFACE instead!" << std::endl;
+      }
+    }
 
     if (!hwSurfaceStr.empty())
     {
@@ -416,7 +451,7 @@ bool VideoEncoder::Start(
     return false;
   }
 
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   // HW encoder needs to be created before the call to FindEncoder()
   this->dataPtr->hwEncoder = std::make_unique<HWEncoder>(
       _allowedHwAccel, _hwAccelDevice, _useHwSurface);
@@ -529,7 +564,7 @@ bool VideoEncoder::Start(
   // we misuse this field a bit, as docs say it is unused in encoders
   // here, it stores the input format of the encoder
   this->dataPtr->codecCtx->sw_pix_fmt = this->dataPtr->codecCtx->pix_fmt;
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   if (this->dataPtr->hwEncoder)
     this->dataPtr->hwEncoder->ConfigHWAccel(this->dataPtr->codecCtx);
 #endif
@@ -540,7 +575,7 @@ bool VideoEncoder::Start(
   {
     gzerr << "Could not open video codec: " << av_err2str_cpp(ret)
           << ". Video encoding is not started\n";
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
     if (AVUNERROR(ret) == ENOMEM &&
       this->dataPtr->hwEncoder->GetEncoderType() == HWEncoderType::NVENC)
     {
@@ -1005,7 +1040,7 @@ void VideoEncoder::Reset()
   this->dataPtr->timePrev = std::chrono::steady_clock::time_point();
   this->dataPtr->timeStart = std::chrono::steady_clock::time_point();
   this->dataPtr->filename.clear();
-#ifdef IGN_COMMON_BUILD_HW_VIDEO
+#ifdef GZ_COMMON_BUILD_HW_VIDEO
   if (this->dataPtr->hwEncoder)
     this->dataPtr->hwEncoder.reset();
 #endif

include/gz/common/SystemPaths.hh

@@ -40,9 +40,9 @@ namespace gz
       /// \brief Constructor for SystemPaths
       public: SystemPaths();
 
-      /// \brief Get the log path. If IGN_LOG_PATH environment variable is set,
-      /// then this path is used. If not, the path is $HOME/.ignition, and in
-      /// case even HOME is not set, /tmp/ignition is used. If the directory
+      /// \brief Get the log path. If GZ_LOG_PATH environment variable is set,
+      /// then this path is used. If not, the path is $HOME/.gz, and in
+      /// case even HOME is not set, /tmp/gz is used. If the directory
       /// does not exist, it is created in the constructor of SystemPaths.
       /// \return the path
       public: std::string LogPath() const;
@@ -101,7 +101,7 @@ namespace gz
 
       /// \brief Set the file path environment variable to use, and clears
       /// any previously set file paths. The default
-      /// environment variable is IGN_FILE_PATH. The
+      /// environment variable is GZ_FILE_PATH. The
       /// environment variable should be a set of colon (semicolon on windows)
       /// delimited paths. These paths will be used with the FindFile function.
       /// \param [in] _env name of the environment variable

src/SystemPaths.cc

@@ -37,10 +37,16 @@ using namespace common;
 class gz::common::SystemPaths::Implementation
 {
   /// \brief Name of the environment variable to check for plugin paths
-  public: std::string pluginPathEnv = "IGN_PLUGIN_PATH";
+  public: std::string pluginPathEnv = "GZ_PLUGIN_PATH";
+
+  // TODO(CH3): Deprecated. Remove on tock.
+  public: std::string pluginPathEnvDeprecated = "IGN_PLUGIN_PATH";
 
   /// \brief Name of the environment variable to check for file paths
-  public: std::string filePathEnv = "IGN_FILE_PATH";
+  public: std::string filePathEnv = "GZ_FILE_PATH";
+
+  // TODO(CH3): Deprecated. Remove on tock.
+  public: std::string filePathEnvDeprecated = "IGN_FILE_PATH";
 
   /// \brief Paths to plugins
   public: std::list<std::string> pluginPaths;
@@ -83,12 +89,23 @@ SystemPaths::SystemPaths()
 {
   std::string home, path, fullPath;
   if (!env(IGN_HOMEDIR, home))
-    home = "/tmp/ignition";
+    home = "/tmp/gz";
 
-  if (!env("IGN_LOG_PATH", path))
+  if (!env("GZ_LOG_PATH", path))
   {
-    if (home != "/tmp/ignition")
-      fullPath = joinPaths(home, ".ignition");
+    // TODO(CH3): Deprecated. Remove on tock.
+    if (env("IGN_LOG_PATH", path))
+    {
+      gzwarn << "Setting log path to [" << path << "] using deprecated "
+             << "environment variable [IGN_LOG_PATH]. Please use "
+             << "[GZ_LOG_PATH] instead." << std::endl;
+    }
+  }
+
+  if (path.empty())
+  {
+    if (home != "/tmp/gz")
+      fullPath = joinPaths(home, ".gz");
     else
       fullPath = home;
   }
@@ -100,11 +117,23 @@ SystemPaths::SystemPaths()
     createDirectories(fullPath);
   }
 
-
   this->dataPtr->logPath = fullPath;
   // Populate this->dataPtr->filePaths with values from the default
   // environment variable.
-  this->SetFilePathEnv(this->dataPtr->filePathEnv);
+
+  if (this->dataPtr->filePathEnv.empty() &&
+      !this->dataPtr->filePathEnvDeprecated.empty())
+  {
+    gzwarn << "Setting file path using deprecated environment variable ["
+           <<  this->dataPtr->filePathEnvDeprecated
+           << "]. Please use " <<  this->dataPtr->filePathEnv
+           << " instead." << std::endl;
+   this->SetFilePathEnv(this->dataPtr->filePathEnvDeprecated);
+  }
+  else
+  {
+    this->SetFilePathEnv(this->dataPtr->filePathEnv);
+  }
 }
 
 /////////////////////////////////////////////////
@@ -117,6 +146,26 @@ std::string SystemPaths::LogPath() const
 void SystemPaths::SetPluginPathEnv(const std::string &_env)
 {
   this->dataPtr->pluginPathEnv = _env;
+
+  // TODO(CH3): Deprecated. Remove on tock.
+  std::string result;
+  if (!this->dataPtr->pluginPathEnv.empty())
+  {
+    if (env(this->dataPtr->pluginPathEnv, result))
+    {
+      // TODO(CH3): Deprecated. Remove on tock.
+      std::string ign_prefix = "IGN_";
+
+      // Emit warning if env starts with IGN_
+      if (env_.compare(0, ign_prefix.length(), ign_prefix) == 0)
+      {
+        gzwarn << "Finding plugins using deprecated IGN_ prefixed environment "
+               << "variable ["
+               << _env << "]. Please use the GZ_ prefix instead"
+               << std::endl;
+      }
+    }
+  }
 }
 
 /////////////////////////////////////////////////
@@ -129,6 +178,15 @@ const std::list<std::string> &SystemPaths::PluginPaths()
     {
       this->AddPluginPaths(result);
     }
+    // TODO(CH3): Deprecated. Remove on tock.
+    if (env(this->dataPtr->pluginPathEnvDeprecated, result))
+    {
+      this->AddPluginPaths(result);
+      gzwarn << "Finding plugins using deprecated environment variable "
+             << "[" << this->dataPtr->pluginPathEnvDeprecated
+             << "]. Please use [" << this->dataPtr->pluginPathEnv
+             << "] instead." << std::endl;
+    }
   }
   return this->dataPtr->pluginPaths;
 }
@@ -165,12 +223,25 @@ std::string SystemPaths::FindSharedLibrary(const std::string &_libName)
 void SystemPaths::SetFilePathEnv(const std::string &_env)
 {
   this->dataPtr->filePathEnv = _env;
+  std::string result;
+
   if (!this->dataPtr->filePathEnv.empty())
   {
     this->ClearFilePaths();
-    std::string result;
     if (env(this->dataPtr->filePathEnv, result))
     {
+      // TODO(CH3): Deprecated. Remove on tock.
+      std::string ign_prefix = "IGN_";
+
+      // Emit warning if env starts with IGN_
+      if (env_.compare(0, ign_prefix.length(), ign_prefix) == 0)
+      {
+        gzwarn << "Finding files using deprecated IGN_ prefixed environment "
+               << "variable ["
+               << _env << "]. Please use the GZ_ prefix instead"
+               << std::endl;
+      }
+
       this->AddFilePaths(result);
     }
   }