ign -> gz Environment Variable Migration : gz-sim

Migration.md

@@ -17,6 +17,15 @@ release will remove the deprecated code.
   Use `gz/...` instead.
 * Configuration and log files are stored under `$HOME/.gz/sim` instead of
   `$HOME/.ignition/gazebo`
+* The following `IGN_` prefixed environment variables are deprecated and will be removed in future versions.
+  Use the `GZ_` prefixed versions instead!
+  * `IGN_GAZEBO_RENDER_ENGINE_PATH` -> `GZ_SIM_RENDER_ENGINE_PATH`
+  * `IGN_GAZEBO_PHYSICS_ENGINE_PATH` -> `GZ_SIM_PHYSICS_ENGINE_PATH`
+  * `IGN_GAZEBO_SYSTEM_PLUGIN_PATH` -> `GZ_SIM_SYSTEM_PLUGIN_PATH`
+  * `IGN_DEBUG_COMPONENT_FACTORY` -> `GZ_DEBUG_COMPONENT_FACTORY`
+  * `IGN_GAZEBO_RESOURCE_PATH` -> `GZ_SIM_RESOURCE_PATH`
+  * `IGN_GAZEBO_SERVER_CONFIG_PATH` -> `GZ_SIM_SERVER_CONFIG_PATH`
+
 
 ## Gazebo Sim 6.1 to 6.2
 

docker/run.bash

@@ -34,7 +34,7 @@ docker run -it \
   -e DISPLAY \
   -e QT_X11_NO_MITSHM=1 \
   -e XAUTHORITY=$XAUTH \
-  -e IGN_PARTITION \
+  -e GZ_PARTITION \
   -v "$XAUTH:$XAUTH" \
   -v "/tmp/.X11-unix:/tmp/.X11-unix" \
   -v "/etc/localtime:/etc/localtime:ro" \

examples/plugin/command_actor/README.md

@@ -22,7 +22,7 @@ Add the library to the path:
 
 ~~~
 cd examples/plugin/command_actor
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Then run the demo world:

examples/plugin/custom_component/README.md

@@ -24,7 +24,7 @@ Add the library to the path:
 
 ~~~
 cd examples/plugin/custom_component
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Then run a world that loads the plugin as follows:

examples/plugin/custom_sensor_system/README.md

@@ -28,7 +28,7 @@ Before starting Gazebo, we must make sure it can find the plugin by doing:
 
 ~~~
 cd examples/plugins/custom_sensor_system
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Then load the example world:

examples/plugin/hello_world/README.md

@@ -26,7 +26,7 @@ Before starting Gazebo, we must make sure it can find the plugin by doing:
 
 ~~~
 cd ign-gazebo/examples/plugins/hello_world
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Then load the example world:

examples/plugin/rendering_plugins/README.md

@@ -23,7 +23,7 @@ Add the libraries to the correct paths:
 ~~~
 cd examples/plugin/rendering_plugins
 export IGN_GUI_PLUGIN_PATH=`pwd`/build
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Run the example world

examples/plugin/reset_plugin/README.md

@@ -22,7 +22,7 @@ Add the library to the path:
 
 ~~~
 cd examples/plugin/reset_plugin
-export IGN_GAZEBO_SYSTEM_PLUGIN_PATH=`pwd`/build
+export GZ_SIM_SYSTEM_PLUGIN_PATH=`pwd`/build
 ~~~
 
 Then run a world that loads the plugin as follows:

include/gz/sim/ServerConfig.hh

@@ -441,9 +441,9 @@ namespace gz
     /// file to load either a default or custom set of plugins.
     ///
     /// The following order is used to resolve:
-    /// 1. Config file located at IGN_GAZEBO_SERVER_CONFIG_PATH environment
+    /// 1. Config file located at GZ_SIM_SERVER_CONFIG_PATH environment
     ///    variable.
-    ///   * If IGN_GAZEBO_SERVER_CONFIG_PATH is set but empty, no plugins
+    ///   * If GZ_SIM_SERVER_CONFIG_PATH is set but empty, no plugins
     ///     are loaded.
     /// 2. File at ${IGN_HOMEDIR}/.gz/sim/server.config
     /// 3. File at ${IGN_DATA_INSTALL_DIR}/server.config

include/gz/sim/Util.hh

@@ -156,7 +156,7 @@ namespace gz
         const std::string &_filePath);
 
     /// \brief Get resource paths based on latest environment variables.
-    /// \return All paths in the IGN_GAZEBO_RESOURCE_PATH variable.
+    /// \return All paths in the GZ_SIM_RESOURCE_PATH variable.
     std::vector<std::string> GZ_GAZEBO_VISIBLE resourcePaths();
 
     /// \brief Add resource paths based on latest environment variables.
@@ -267,18 +267,23 @@ namespace gz
         Entity _entity, const EntityComponentManager &_ecm);
 
     /// \brief Environment variable holding resource paths.
-    const std::string kResourcePathEnv{"IGN_GAZEBO_RESOURCE_PATH"};
+    const std::string kResourcePathEnv{"GZ_SIM_RESOURCE_PATH"};
 
     /// \brief Environment variable used by SDFormat to find URIs inside
     /// `<include>`
     const std::string kSdfPathEnv{"SDF_PATH"};
 
     /// \brief Environment variable holding server config paths.
-    const std::string kServerConfigPathEnv{"IGN_GAZEBO_SERVER_CONFIG_PATH"};
+    const std::string kServerConfigPathEnv{"GZ_SIM_SERVER_CONFIG_PATH"};
 
     /// \brief Environment variable holding paths to custom rendering engine
     /// plugins.
-    const std::string kRenderPluginPathEnv{"IGN_GAZEBO_RENDER_ENGINE_PATH"};
+    const std::string kRenderPluginPathEnv{"GZ_SIM_RENDER_ENGINE_PATH"};
+
+    // TODO(CH3): Deprecated. Remove on tock.
+    const std::string kResourcePathEnvDeprecated{"IGN_GAZEBO_RESOURCE_PATH"};
+    const std::string kRenderPluginPathEnvDeprecated{
+      "IGN_GAZEBO_RENDER_ENGINE_PATH"};
     }
   }
 }

include/gz/sim/components/Factory.hh

@@ -176,7 +176,19 @@ namespace components
       // This happens at static initialization time, so we can't use common
       // console
       std::string debugEnv;
-      gz::common::env("IGN_DEBUG_COMPONENT_FACTORY", debugEnv);
+      gz::common::env("GZ_DEBUG_COMPONENT_FACTORY", debugEnv);
+
+      if (debugEnv != "true")
+      {
+        gz::common::env("IGN_DEBUG_COMPONENT_FACTORY", debugEnv);
+        if (debugEnv == "true")
+        {
+          std::cerr << "Environment variable [IGN_DEBUG_COMPONENT_FACTORY] "
+                    << "is deprecated! Please use [GZ_DEBUG_COMPONENT_FACTORY]"
+                    << "instead." << std::endl;
+        }
+      }
+
       if (debugEnv == "true")
       {
         std::cout << "Registering [" << ComponentTypeT::typeName << "]"

src/CMakeLists.txt

@@ -213,7 +213,7 @@ foreach(CMD_TEST
 
   set(_env_vars)
   list(APPEND _env_vars "GZ_CONFIG_PATH=${CMAKE_BINARY_DIR}/test/conf")
-  list(APPEND _env_vars "IGN_GAZEBO_SYSTEM_PLUGIN_PATH=$<TARGET_FILE_DIR:TestModelSystem>")
+  list(APPEND _env_vars "GZ_SIM_SYSTEM_PLUGIN_PATH=$<TARGET_FILE_DIR:TestModelSystem>")
 
   set_tests_properties(${CMD_TEST} PROPERTIES
     ENVIRONMENT "${_env_vars}")

src/ComponentFactory_TEST.cc

@@ -34,7 +34,7 @@ class ComponentFactoryTest : public InternalFixture<::testing::Test>
   protected: void SetUp() override
   {
     InternalFixture::SetUp();
-    common::setenv("IGN_DEBUG_COMPONENT_FACTORY", "true");
+    common::setenv("GZ_DEBUG_COMPONENT_FACTORY", "true");
   }
 };
 
@@ -141,4 +141,3 @@ TEST_F(ComponentFactoryTest, New)
     ASSERT_EQ(nullptr, comp);
   }
 }
-

src/Component_TEST.cc

@@ -41,7 +41,7 @@ class ComponentTest : public InternalFixture<::testing::Test>
   protected: void SetUp() override
   {
     InternalFixture::SetUp();
-    common::setenv("IGN_DEBUG_COMPONENT_FACTORY", "true");
+    common::setenv("GZ_DEBUG_COMPONENT_FACTORY", "true");
   }
 };
 

src/Conversions.cc

@@ -1616,7 +1616,24 @@ msgs::ParticleEmitter gz::sim::convert(const sdf::ParticleEmitter &_in)
     std::string absolutePath = systemPaths.FindFile(path);
 
     if (!absolutePath.empty())
+    {
       out.mutable_color_range_image()->set_data(absolutePath);
+    }
+    // TODO(CH3): Deprecated. Remove on tock.
+    else
+    {
+      systemPaths.SetFilePathEnv(kResourcePathEnvDeprecated);
+      absolutePath = systemPaths.FindFile(path);
+
+      if (!absolutePath.empty())
+      {
+        out.mutable_color_range_image()->set_data(absolutePath);
+        gzwarn << "Using deprecated environment variable ["
+               << kResourcePathEnvDeprecated
+               << "] to find resources. Please use ["
+               << kResourcePathEnv <<" instead." << std::endl;
+      }
+    }
   }
 
   /// \todo(nkoenig) Modify the particle_emitter.proto file to

src/ServerConfig.cc

@@ -873,8 +873,21 @@ gz::sim::loadPluginInfo(bool _isPlayback)
   // 1. Check contents of environment variable
   std::string envConfig;
   bool configSet = gz::common::env(sim::kServerConfigPathEnv,
-                                         envConfig,
-                                         true);
+                                   envConfig,
+                                   true);
+
+  if (!configSet)
+  {
+    configSet = gz::common::env("IGN_GAZEBO_SERVER_CONFIG_PATH",
+                                envConfig,
+                                true);
+    if (configSet)
+    {
+      gzwarn << "Config path found using deprecated environment variable "
+             << "[IGN_GAZEBO_SERVER_CONFIG_PATH]. Please use "
+             << "[GZ_SIM_SERVER_CONFIG_PATH] instead" << std::endl;
+    }
+  }
 
   if (configSet)
   {

src/ServerPrivate.hh

@@ -122,9 +122,10 @@ namespace gz
       /// string and return value of false will be used if the resource could
       /// not be found.
       ///
-      /// Fuel will be checked and then the GZ_GAZEBO_RESOURCE_PATH environment
-      /// variable paths. This service will not check for files relative to
-      /// working directory of the Gazebo server.
+      /// Gazebo Fuel will be checked first, and then paths from the
+      /// GZ_GAZEBO_RESOURCE_PATH environment variable. This service will
+      /// not check for files relative to the working directory of the Gazebo
+      /// server.
       ///
       /// \param[in] _req Request filled with a resource URI to resolve.
       /// Example values could be:

src/Server_TEST.cc

@@ -849,7 +849,7 @@ TEST_P(ServerFixture, Seed)
 /////////////////////////////////////////////////
 TEST_P(ServerFixture, IGN_UTILS_TEST_DISABLED_ON_WIN32(ResourcePath))
 {
-  gz::common::setenv("IGN_GAZEBO_RESOURCE_PATH",
+  gz::common::setenv("GZ_SIM_RESOURCE_PATH",
          (std::string(PROJECT_SOURCE_PATH) + "/test/worlds:" +
           std::string(PROJECT_SOURCE_PATH) + "/test/worlds/models").c_str());
 
@@ -937,7 +937,7 @@ TEST_P(ServerFixture, IGN_UTILS_TEST_DISABLED_ON_WIN32(ResourcePath))
 /////////////////////////////////////////////////
 TEST_P(ServerFixture, GetResourcePaths)
 {
-  gz::common::setenv("IGN_GAZEBO_RESOURCE_PATH",
+  gz::common::setenv("GZ_SIM_RESOURCE_PATH",
       "/tmp/some/path:/home/user/another_path");
 
   ServerConfig serverConfig;
@@ -967,10 +967,10 @@ TEST_P(ServerFixture, GetResourcePaths)
 /////////////////////////////////////////////////
 TEST_P(ServerFixture, AddResourcePaths)
 {
-  gz::common::setenv("IGN_GAZEBO_RESOURCE_PATH",
+  gz::common::setenv("GZ_SIM_RESOURCE_PATH",
       "/tmp/some/path:/home/user/another_path");
   gz::common::setenv("SDF_PATH", "");
-  gz::common::setenv("IGN_FILE_PATH", "");
+  gz::common::setenv("GZ_FILE_PATH", "");
 
   ServerConfig serverConfig;
   sim::Server server(serverConfig);
@@ -1012,7 +1012,7 @@ TEST_P(ServerFixture, AddResourcePaths)
   EXPECT_TRUE(receivedMsg);
 
   // Check environment variables
-  for (auto env : {"IGN_GAZEBO_RESOURCE_PATH", "SDF_PATH", "IGN_FILE_PATH"})
+  for (auto env : {"GZ_SIM_RESOURCE_PATH", "SDF_PATH", "GZ_FILE_PATH"})
   {
     char *pathCStr = std::getenv(env);
 
@@ -1036,9 +1036,9 @@ TEST_P(ServerFixture, AddResourcePaths)
 /////////////////////////////////////////////////
 TEST_P(ServerFixture, ResolveResourcePaths)
 {
-  common::setenv("IGN_GAZEBO_RESOURCE_PATH", "");
+  common::setenv("GZ_SIM_RESOURCE_PATH", "");
   common::setenv("SDF_PATH", "");
-  common::setenv("IGN_FILE_PATH", "");
+  common::setenv("GZ_FILE_PATH", "");
 
   ServerConfig serverConfig;
   Server server(serverConfig);
@@ -1071,7 +1071,7 @@ TEST_P(ServerFixture, ResolveResourcePaths)
         });
 
   // Make sure the resource path is clear
-  common::setenv("IGN_GAZEBO_RESOURCE_PATH", "");
+  common::setenv("GZ_SIM_RESOURCE_PATH", "");
 
   // An absolute path should return the same absolute path
   test(PROJECT_SOURCE_PATH, PROJECT_SOURCE_PATH, true);
@@ -1084,7 +1084,7 @@ TEST_P(ServerFixture, ResolveResourcePaths)
   test(common::joinPaths("test", "worlds", "plugins.sdf"), "", false);
 
   // Try again, this time with a RESOURCE_PATH
-  common::setenv("IGN_GAZEBO_RESOURCE_PATH", PROJECT_SOURCE_PATH);
+  common::setenv("GZ_SIM_RESOURCE_PATH", PROJECT_SOURCE_PATH);
   test(common::joinPaths("test", "worlds", "plugins.sdf"),
       common::joinPaths(PROJECT_SOURCE_PATH, "test", "worlds", "plugins.sdf"),
       true);
@@ -1096,7 +1096,7 @@ TEST_P(ServerFixture, ResolveResourcePaths)
 
   // The model:// URI should not resolve
   test("model://include_nested/model.sdf", "", false);
-  common::setenv("IGN_GAZEBO_RESOURCE_PATH",
+  common::setenv("GZ_SIM_RESOURCE_PATH",
       common::joinPaths(PROJECT_SOURCE_PATH, "test", "worlds", "models"));
   // The model:// URI should now resolve because the RESOURCE_PATH has been
   // updated.

src/SystemLoader.cc

@@ -55,18 +55,38 @@ class gz::sim::SystemLoaderPrivate
     std::string homePath;
     gz::common::env(IGN_HOMEDIR, homePath);
     systemPaths.AddPluginPaths(homePath + "/.gz/sim/plugins");
+
+    // TODO(CH3): Deprecated. Remove on tock.
+    systemPaths.AddPluginPaths(homePath + "/.ignition/gazebo/plugins");
+
     systemPaths.AddPluginPaths(GZ_SIM_PLUGIN_INSTALL_DIR);
 
     auto pathToLib = systemPaths.FindSharedLibrary(_filename);
     if (pathToLib.empty())
     {
-      // We assume gz::sim corresponds to the levels feature
-      if (_name != "gz::sim")
+      // Try deprecated environment variable
+      // TODO(CH3): Deprecated. Remove on tock.
+      common::SystemPaths systemPathsDep;
+      systemPathsDep.SetPluginPathEnv(pluginPathEnvDeprecated);
+      pathToLib = systemPathsDep.FindSharedLibrary(_filename);
+
+      if (pathToLib.empty())
       {
-        gzerr << "Failed to load system plugin [" << _filename <<
-                  "] : couldn't find shared library." << std::endl;
+        // We assume gz::sim corresponds to the levels feature
+        if (_name != "gz::sim")
+        {
+          gzerr << "Failed to load system plugin [" << _filename <<
+                    "] : couldn't find shared library." << std::endl;
+        }
+        return false;
+      }
+      else
+      {
+        gzwarn << "Found plugin [" << _filename
+               << "] using deprecated environment variable ["
+               << pluginPathEnvDeprecated << "]. Please use ["
+               << pluginPathEnv << "] instead." << std::endl;
       }
-      return false;
     }
 
     auto pluginNames = this->loader.LoadLib(pathToLib);
@@ -110,7 +130,8 @@ class gz::sim::SystemLoaderPrivate
   }
 
   // Default plugin search path environment variable
-  public: std::string pluginPathEnv{"IGN_GAZEBO_SYSTEM_PLUGIN_PATH"};
+  public: std::string pluginPathEnv{"GZ_SIM_SYSTEM_PLUGIN_PATH"};
+  public: std::string pluginPathEnvDeprecated{"IGN_GAZEBO_SYSTEM_PLUGIN_PATH"};
 
   /// \brief Plugin loader instace
   public: gz::plugin::Loader loader;