/**
\page yarp_external_build Configuring your external build

\tableofcontents

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.

\verbatim
 find_package(YARP REQUIRED)
\endverbatim

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

\verbatim
 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})
\endverbatim

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
\ref datafiles_extendsearch "setting the YARP_DATA_DIRS environment variable".

\section data-files-inside-specific-directories Install data files inside directories specific for your project


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

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

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

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

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

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

and the analogue variables containing absolute paths:

\li <B><PACKAGE>_CONTEXTS_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_PLUGIN_MANIFESTS_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_APPLICATIONS_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_MODULES_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_ROBOTS_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_TEMPLATES_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_APPLICATIONS_TEMPLATES_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_MODULES_TEMPLATES_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_DATA_INSTALL_DIR_FULL</B>
\li <B><PACKAGE>_CONFIG_INSTALL_DIR_FULL</B>

Now you can install additional data files by using the macro \e yarp_install, e.g.:
\verbatim
 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})
\endverbatim

Unless the \e 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 \e WITH_PLUGINS argument is passed, a plugin manifest file
containing the search path for the plugins is generated and installed

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

*/
