How To Use Paths in ArmarX

Table of Contents

• Requirements
• Resolve Environment Variables
• Specify Paths Relative to a Package
• Advanced: Finding CMake Packages

Paths may be absolute, relative to the current directory or relative to a certain ArmarX package. Furthermore, they might contain environment variables, which need to be resolved before providing the path as a parameter to a function. Several convenience functions for handling paths already exist in ArmarX. Here, you can find some of them.

Requirements

Add ArmarXCore to the DEPENDENCIES section of the respective armarx_add_component() or the DEPENDENCIES_PUBLIC section of armarx_add_library() statement in the CMakeLists.txt next to your code file. Most likely, it is already listed there.

Resolve Environment Variables

Source
include	#include <ArmarXCore/core/system/ArmarXDataPath.h>
dependecy	ArmarXCore
API documentation	armarx::ArmarXDataPath

Recommended, rather comprehensive solution: Replace environment variables and ~ as in ResolveHomePath, and convert to an absolute path.

Method
signature	std::string armarx::ArmarXDataPath::resolvePath(const std::string& path, bool verbose)

Replace not only environment variables as in ReplaceEnvVars, but also ~ at the beginning of the path.

Method
signature	static void armarx::ArmarXDataPath::ResolveHomePath(std::string& path)

Replace only environment variables, like $ARMARX_WORKSPACE or $HOME, by their value.

Method
signature	static bool armarx::ArmarXDataPath::ReplaceEnvVars(std::string& string)

Further functions exist, see armarx::ArmarXDataPath.

Specify Paths Relative to a Package

Source
include	#include <ArmarXCore/core/PackagePath.h>
dependecy	ArmarXCore
API documentation	armarx::PackagePath

Create a package path, i.e., a path that is relative to a specified ArmarX package. This can be useful, e.g., to refer to files inside a package's data directory.

Method
signature	PackagePath(const std::string& package_name, const std::filesystem::path& rel_path)

Resolve a package path, to get a plain std::filesystem::path.

Method
signature	std::filesystem::path armarx::PackagePath::toSystemPath() const
signature	static std::filesystem::path armarx::PackagePath::toSystemPath(const data::PackagePath& pp)

Send a package path via ice (used, e.g., for interfaces of components).

Method
signature	armarx::data::PackagePath armarx::PackagePath::serialize() const

Advanced: Finding CMake Packages

For a flexible, but more lengthy usage, the armarx::CMakePackageFinder is available, as described in How to locate package data files.

Source
include	#include <ArmarXCore/core/system/cmake/CMakePackageFinder.h>
dependecy	ArmarXCore
API documentation	armarx::CMakePackageFinder

Code example: Assume a file being located at ${Package_DIR}/data/MyArmarXPackage/myDirectory/myDataFile.txt. The package name is MyArmarXPackage. The "relative path" in the context of ArmarX PackagePath is defined as the path relative to the package's data/MyArmarXPackage directory, i.e., myDirectory/myDataFile.txt in this example.

std::string packageName("MyArmarXPackage");
armarx::CMakePackageFinder finder(packageName);
if (finder.packageFound())
{
    ARMARX_INFO << "Package found...";
 
    std::string packageDataDir = finder.getDataDir();
 
    // add the data directory to the search list of ArmarXDataPath
    ArmarXDataPath::addDataPaths(packageDataDir);
 
    std::string relativeFilename("myDirectory/myDataFile.txt");
    std::string absoluteFilename;
    if (ArmarXDataPath::getAbsolutePath(relativeFilename, absoluteFilename))
    {
        ARMARX_INFO << "Located file at:" << absoluteFilename;
    }
}