Doubts about Configuration Files in YARP

[pattacini]

I'm a bit lost among all the possible paths from where a configuration file can be found and loaded by a YARP module.

I've got a bunch of questions:

1. Where can I read more about the policies used by YARP to locate files on the system?
2. Is there an handy way to easily find out which exact file will be loaded at start up,
   given that there exist several copies of it in different paths?
3. What do I have to do when I want to modify the content of a configuration file?
4. What do I have to do when I want to make those modifications become the default values?

[pattacini]

The way YARP locates files by means of the yarp::os::ResourceFinder class may appear not easy to understand at first sight, but stems from the original goal of shipping binaries alongside their configuration files with the need to accommodate for different platforms (Windows, Linux, Mac OS X) and for different credentials a user might own on the particular system (i.e. he may not have writing access to system paths).

To answer the questions:

1. There are some tutorials that provide an introduction to these functionalities:
   http://wiki.icub.org/yarpdoc/yarp_resource_finder_tutorials.html.

   The full documentation is available here:
   http://wiki.icub.org/yarpdoc/yarp_data_dirs.html.

   This page is also linked from within the Manual:
   http://wiki.icub.org/wiki/Configuration_files.

2. Whenever you find yourself uncertain about which file your module will load at start up, just use one of the following utilities:

   1. yarp-config context --where moduleContext: this command will list down all the context paths containing your configuration file as they will be visited during the search in decreasing priority order.
   2. yarp resource --context moduleContext --from fileName.ini: this command will show you the location of the file "fileName.ini" belonging to the context "moduleContext" as result of the search. All the possible paths will be thus visited according to the YARP policies until the specified file gets found.

3. You should first copy the file in the local path where it is sure you have writing access to edit it (e.g. in ~/.local/share/yarp/context in Linux, %APPDATA%\yarp\context in Windows, ~/Library/Application Support/yarp/context in Mac OS X).
   To automate this process, you can rely on this command: yarp-config context --import moduleContext filenName.ini. This local file will "shadow" any other copy in the file system. Be careful when dealing with robot related files; in this case, use: yarp-config robot --import robotName fileName.ini.

4. You should overwrite the copy of the file in your repository and then commit it to the net. Afterwards, you have to yield a "cmake", because only by "cmaking" the project that file will be copied out in the build path where it will be ready to be loaded from. Possibly, you have to remember to "make install" the project too if you did in the past. At this point you can safely remove the file in the local path by: yarp-config context --remove moduleContext fileName.ini.

[pattacini]

/cc @robotology/icub-support-team and anyone else might have doubts on this.
Feel free to expand on this issue.

[traversaro]

/cc @robotology/codyco-developers

[drdanz]

Scary details about ResourceFinder internals: http://wiki.icub.org/wiki/YARP_ResourceFinder

[pattacini]

There's an important update on the use of yarp-config robot utility.

Importing single files of the robot context is no longer allowed. One can only decide to import in the local path the whole set of xml files.

@randaz81 and @drdanz might provide rationale for this change.

Then, one question might raise about importing single .ini files in the robot context. Is it still allowed? We do use .ini files in robot contexts to better customize applications for specific robots, indeed.

You ensured that the ResourceFinder still works as expected on the .ini files in those robot directories, but is yarp-config robot --import robotName fileName.ini still operative?

[drdanz]

@pattacini No, since robotology/yarp@560ac72 you are only allowed to import all the files from a robot.

The reason is that for a few good reasons (i.e. being able to modify the robot files with external xml editors), we are moving the robotInterface to use the XInclude W3C Recommendation instead of our custom include tags. This requires that all the files for the robotInterface are in the same place, and the ResourceFinder can no longer be used to look for included files.

In order to ensure that all the robotInterface files are imported together, we decided to force the users to import all the files for a robot.

[randaz81]

@pattacini you can always use yarp-config robot --diff robotName to check the status of individual files.

[pattacini]

@tanismar and @GiuliaP please take a glance at these notes for dealing with configuration files in yarp.