Difference between revisions of "Applications"

From Wiki for iCub and Friends
Jump to: navigation, search
m (Contrib)
Line 146: Line 146:
   # default prefix for applications
   # default prefix for applications
   set(ICUB_APPLICATIONS_PREFIX "$ENV{ICUB_ROOT}"  CACHE PATH "Application path prefix")

Revision as of 23:09, 10 November 2010

This documentation is work in progress.

Configuration and xml files (or resource files) can be placed in the repository. Since these files are customized depending on the setup/configuration in the repository we only keep them in the form of template files ready to be customized by the users.

The idea is that at compile time resource files are installed in a common directory outside the repository. When you run cmake this directory is a cache entry:


which gets initialized with the value of the env. variable ICUB_ROOT, but can be customized by the user.

Modules using the ResourceFinder class will be able to pick them, provided you point the ICUB_ROOT environment variable to the directory where you install them (the ResourceFinder also searches in a few default directories so there is no strict need for an ICUB_ROOT variable but we don't consider this case here).

This makes it possible for code form different projects/repositories (or code in contrib) to be installed and coexist in the same installation tree.


It is easy to explain how applications will work in a few examples.

Suppose you download the iCub code in /home/nat/iCub.

Compile iCub:

 cd /home/nat/iCub/main/build
 cmake ../

now install applications

 make install_applications

xmls and config files will be copied to $ICUB_ROOT (e.g. /home/nat/iCub/app). If you are wondering what is the difference with the past, you should notice that applications in iCub/app are now copies and no longer in the repository. iCub/app will merge applications from main and contrib (and potentially other projects as well).


Now suppose you have code in contrib, my-app and you want to install it in a similar way. All you need to do is to add a rule for installing applications in my-app.

 cd /home/nat/iCub/contrib/my-app
 cmake ./

...we assume here cmake gets configured to select the application installation directory to be $ICUB_ROOT...

 make install_applications

xml templates and config files will go to /home/nat/iCub/app.

If modules in my-app are configured to use the ResourceFinder with the ICUB_ROOT policy, everything will work.


Suppose now there is another project repository that has applications you want to use. These applications use the ResourceFinder but follow another policy called PROJECT_ROOT. All you need to do is to set the $PROJECT_ROOT environment variable to point to /home/nat/iCub/app, install the application from the project repository and everything should work seamlessly.

 cd /home/nat/chris-project
 cmake ./

...again assuming cmake selects the application install directory to be $PROJECT_ROOT...

 make install_applications

CMake code

Rules for installing applications can be specified:

  • inside a directory in main/app
  • inside a module

Similarly code in contrib can define new applications:

  • inside each individual modules
  • inside an app directory, for collections of modules (e.g. contrib/src/cognitiveArchitecture/app).

Inside a directory in main/app

Suppose you have an application called grasping.

  • Create a directory in main/app/grasping
  • Put all your conf and scripts files there as usual (i.e. main/app/gasping/conf, main/app/grasping/scripts)
  • Add CMakeFiles.txt file in main/app/grasping
  • Edit main/app/CMakeFiles.txt and add the grasping subdirectory

The CMakeFiles.txt will look something like:

 set(appname grasping)

 # build a list of scripts and conf files to be installed
 file(GLOB scripts ${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.template)
 file(GLOB conf ${CMAKE_CURRENT_SOURCE_DIR}/conf/*.ini)
 # add rule so that all files in ${scripts} will go to ${appname}/scripts
                  FILES ${scripts}
                  DESTINATION scripts)
 # add rule so that all files in ${conf} will go to ${appname}/conf
                  FILES ${conf}
                  DESTINATION conf)

This will add cmake code so that when you type make install_applications all files in main/app/grasping/scripts and main/app/grasping/conf will be copied to $ICUB_APPLICATIONS_PREFIX/app/grasping/scripts and grasping/conf (respectively). The code is generic and allows flexibility but this is probably how most applications will use it.

It is also possible to have more flexibility, in case you want to install files in directories of your choice inside $ICUB_APPLICATIONS_PREFIX.

                  FILES ...
                  DESTINATION dest)

here files are copied in $ICUB_APPLICATIONS_PREFIX/dest (and NOT $ICUB_APPLICATIONS_PREFIX/app/${appname}/destination, as it was before).

Inside a module

Sometimes you want to provide conf files or xml templates that show how your module can be used. Maybe this is not a real application but just a typical or exemplar instantiation of your module, so it does not fit in main/app. One possibility could be to add these files in the directory of your module (in src) and add install rules so that it will be copied together with the other applications.

Example: module reaching, in src/modules/reaching.

  • add src/modules/reaching/conf and scripts and place your files there
  • add this code in src/modules/reaching/CMakeLists.txt
 set(appname reaching)
 file(GLOB conf ${CMAKE_CURRENT_SOURCE_DIR}/conf/*.ini)
                 FILES ${conf}
                 DESTINATION conf/)


Can these features be used inside contrib? The short answer is yes. And clearly this applies to other repositories as well.

The icub_app and icub_app_install are macros that are defined in a file called iCubHelpers.cmake. This file is installed and available for inclusion in cmake after you call FIND_PACKAGE(ICUB).

Typically code will look like:

A common CMakeLists.txt:

 # default prefix for applications
 set(ICUB_APPLICATIONS_PREFIX "$ENV{ICUB_ROOT}"  CACHE PATH "Application path prefix")
 ## make all applications show up as single target

and individual CMakeLists.txt files inside the directories application1 and application2, which are quite similar to the ones described above for applications in main.

Discussion: the meaning of ICUB_ROOT

Up to here we have used ICUB_ROOT with its traditional usage, i.e. pointing to the root of the repository. In doing so applications have been istalled in ICUB_ROOT/app. This is ok and closely matches how applications have been used. It is possible however to set ICUB_ROOT to point anywhere, for example /home/nat/iCub-applications.

In this case applications will be installed outside the repository. This might make a lot of sense, since the applications directory can merge applications coming from different repositories.

ICUB_ROOT in this case will loose its traditional meaning of pointing to the location of the sources. However, there is actually no need for an environment variable that points to the sources (cmake can happily live without it, in fact the only environment variable that is important is ICUB_DIR, and only for other packages/code to link against libraries in the iCub package). There will be some confusion at the beginning, but it should not be difficult to get used to this. The advantage is that the ResourceFinder in most modules is already configured to use ICUB_ROOT so no changes in the code will be required.