YARP
Yet Another Robot Platform
Configuring your external build

Table of Contents

These simple instructions show how to configure your build to install data files (xml and config files for applications and modules) so that they can be easily found by programs that use ResourceFinder objects.

First make sure you find YARP, which brings in a set of YARP variables and commands.

 find_package(YARP REQUIRED)

You can now use YARP's own data directories, e.g.:

 yarp_install(FILES ${conf} DESTINATION ${YARP_CONTEXTS_INSTALL_DIR}/${appname})
 yarp_install(FILES ${templates} DESTINATION ${YARP_APPLICATIONS_TEMPLATES_INSTALL_DIR})
 yarp_install(FILES ${scripts} DESTINATION ${YARP_APPLICATIONS_INSTALL_DIR})

Please note that these CMake variables define relative paths, where data will be installed with respect to the installation prefix you configure your build with (CMAKE_INSTALL_PREFIX CMake variable); for YARP to be able to find these files, you need to make sure that the installation prefix for your build matches the one for YARP, or you will need to tweak your environment by setting the YARP_DATA_DIRS environment variable.

Install data files inside directories specific for your project

We recommend you now have a look at the tutorials in ResourceFinder Tutorials and Specification to see how you can use these variables and the ResourceFinder class in your project.

This is an advanced feature that should be considered experimental and can be removed in the future.

If you want to install data files inside directories specific to your project, you should add:

 yarp_configure_external_installation(<PACKAGE>
                                      [COMPONENT <component>]
#                                     [NO_PATH_D]
#                                     [WITH_PLUGINS])
# )

Where PACKAGE is the name of your build/project. This command creates the following CMake variables containing paths relative to the install prefix:

  • <PACKAGE>_CONTEXTS_INSTALL_DIR for "context" folders, containing configuration files and data that modules look for at runtime
  • <PACKAGE>_PLUGIN_MANIFESTS_INSTALL_DIR for plugin manifest files
  • <PACKAGE>_APPLICATIONS_INSTALL_DIR for XML files describing applications (collections of modules and connections between them)
  • <PACKAGE>_MODULES_INSTALL_DIR for XML files describing modules (including input/output ports)
  • <PACKAGE>_ROBOTS_INSTALL_DIR for robot-specific configuration files
  • <PACKAGE>_TEMPLATES_INSTALL_DIR generic directory for templates; it is however advised to use specific applications/modules templates install directories
  • <PACKAGE>_APPLICATIONS_TEMPLATES_INSTALL_DIR for application templates (XML files with .template extension), which need to be properly customized
  • <PACKAGE>_MODULES_TEMPLATES_INSTALL_DIR for module templates (should not be needed)
  • <PACKAGE>_DATA_INSTALL_DIR generic directory for data; it is however advised to use more specific directories
  • <PACKAGE>_CONFIG_INSTALL_DIR generic directory for configuration files

and the analogue variables containing absolute paths:

  • <PACKAGE>_CONTEXTS_INSTALL_DIR_FULL
  • <PACKAGE>_PLUGIN_MANIFESTS_INSTALL_DIR_FULL
  • <PACKAGE>_APPLICATIONS_INSTALL_DIR_FULL
  • <PACKAGE>_MODULES_INSTALL_DIR_FULL
  • <PACKAGE>_ROBOTS_INSTALL_DIR_FULL
  • <PACKAGE>_TEMPLATES_INSTALL_DIR_FULL
  • <PACKAGE>_APPLICATIONS_TEMPLATES_INSTALL_DIR_FULL
  • <PACKAGE>_MODULES_TEMPLATES_INSTALL_DIR_FULL
  • <PACKAGE>_DATA_INSTALL_DIR_FULL
  • <PACKAGE>_CONFIG_INSTALL_DIR_FULL

Now you can install additional data files by using the macro yarp_install, e.g.: 

 set (appname myApplication)
 file(GLOB conf ${CMAKE_CURRENT_SOURCE_DIR}/conf/*.ini)
 file(GLOB templates ${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.template)
 file(GLOB scripts ${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.xml)

 yarp_install(FILES ${conf} DESTINATION ${<PACKAGE>_CONTEXTS_INSTALL_DIR}/${appname})
 yarp_install(FILES ${templates} DESTINATION ${<PACKAGE>_APPLICATIONS_TEMPLATES_INSTALL_DIR})
 yarp_install(FILES ${scripts} DESTINATION ${<PACKAGE>_APPLICATIONS_INSTALL_DIR})

Unless the NO_PATH_D option is passed, this macro checks if the installation directory of the package is the same as YARP's, in which case it sets up automatic recognition of data directories; otherwise, it warns the user to set up appropriately the YARP_DATA_DIRS environment variable.

If the WITH_PLUGINS argument is passed, a plugin manifest file containing the search path for the plugins is generated and installed

An extra COMPONENT argument can be passed to this function to set the component for the installed files. If not set, "configuration" will be used.