Using the pid-rpath system

pid-rpath packages provides the mechanisms used to find software resource like files and folders at runtime. Its usage is bound to the use of the PID development methodology.

To use it inside a PID package, first declare the dependency to the pid-package in the root CMakeLists.txt of your package:

PID_Dependency(pid-rpath VERSION 2.2)

Then declare a component (application or library) using PID runtime resource:

PID_Component(your_component_name SHARED DIRECTORY your_directory
                      RUNTIME_RESOURCES	folder1 folder2/file1 ...)

In this example, the component your_component_name declares that it will/may access resources folder1 (a folder) and folder2/file1 (a file) at runtime. These resources’ path are defined relative to the package share/resources folder and will be accessed/written from this relative path.

The component has then to declare its dependency to the rpathlib library:

PID_Component_Dependency(your_component_name DEPEND rpathlib PACKAGE pid-rpath)

or simpler:

PID_Component(your_component_name SHARED DIRECTORY your_directory
                      RUNTIME_RESOURCES	folder1 folder2/file1
                      DEPEND pid/rpath)

Finally, inside the c++ code of your component, include the API of rpathlib:

#include <pid/rpath.h>

That’s it your code is ready to use relative runtime path. To do so, anytime you want your code to access a resource at runtime use the PID_PATH macro. For instance:

...
std::string path_to_folder = PID_PATH("folder1");
std::string path_to_file = PID_PATH("folder2/file1");
... // use path to read files and folders

If the path used are unknown (because either you do not have created them in project folder or you did not declare them as runtime resources of the component) the system will generate an exception.

The resources may not exist, for instance if you want to write files (typically logs) into a folder. To allow the creation of resources, prefix the path string with the + symbol:

...
std::string path_to_file_to_create = PID_PATH("+folder1/a_new_file");
... // use path to write file a_new_file

This way the system will only check that the file may exist: it checks if the resource has been declared as a direct runtime resource by the component your_component_name or that it is contained in a folder that is a runtime resource of this component. In this case the system does not check for the existence of the finally targetted resource in the filesystem.

Remark on unsupported systems

Unix systems are supported (including macosx) but some of them have limited support, like Windows. When working with such systems there is no automatic configuration of path resolution mechnism, you must do this configuration by hand. To do this, you must call the PID_EXE macro at the really beginning of your executable entry point (i.e. the main function):

...
int main(int argc, char* argv[]){
  PID_EXE(argv[0]);//do not forget to do that call on Windows !!
  //from here call PID_PATH as usual...
  ...
}