[cmake-developers] Adding the OpenRAVE library module

[Brad King]

On 04/11/2011 07:25 PM, Rosen Diankov wrote:
> I have one question about case though. If it is OpenRAVE, then do all
> the variables have to be prefixed with the correct case OpenRAVE? In
> that case, would it be easier to do openrave-config.cmake and then
> have openrave_XXX variables set? what is your advice here?

As long as the documentation of your project describes the variables provided
by the package configuration file the case doesn't matter to us.  IMO it looks
nicest to have the variable use case like "OpenRAVE_" regardless of the file name.

> what about Windows? i doubt all users will be installing to C:\Program Files\...

The set of prefixes that find_package uses is fairly extensive.  It includes
things like the PATH (minus trailing /bin) which might have your project in it.
Also if your installer sets the OpenRAVE_DIR environment variable to point at
the right place then find_package(OpenRAVE) will use that.

Even if it is not found automatically CMake will ask for OpenRAVE_DIR to be set
to point at the file.  That one value is the only thing that the user will have
to set.  The config file should contain full information after that.

On 04/11/2011 11:09 PM, Rosen Diankov wrote:
> one more question. Even if a openrave-config.cmake file is present, we
> should also have a Findopenrave.cmake file right?

Not necessarily.  One of the reasons we designed find_package to work in this
mode was to prevent every single project from needing a find module distributed
with CMake.  It doesn't make sense to distribute a find module with the project
itself because by the time CMake has found it it might as well have found the
rest of the project too.

Some projects provide a find module in their documentation that is meant to
be copied into projects that depend on it.  In this case the module should be
nothing more than a wrapper around a call to find_package(... NO_MODULE) which
looks for <pkg>Config.cmake.  The purpose of the wrapper is to add registry
entries and other package-specific install locations to the call in the HINTS
and PATHS option.  This isn't much different from simply documenting that
applications may add such paths to their calls to find_package() for your
project though.

> After playing around with openrave-config.cmake, it turns out that
> openrave_FOUND gets set to TRUE no matter how hard
> openrave-config.cmake tries to set it to FALSE. (cmake 2.8.0)

That's intentional.  The variable is set by find_package *after* loading the
package configuration file to indicate that it was loaded successfully.  The
idea is that if the config file was found then it provides everything that
the package needs so the package is indeed found.  You can place a package
version file (openrave-config-version.cmake) next to the main config file to
do a version and suitability test and have an opportunity to tell CMake not
to use this particular installation for some reason.  Note that the package
version file will also let applications do

  find_package(OpenRAVE 1.2) # find version compatible with 1.2

and CMake will know how to honor the request.  The links I sent in my previous
response describe how to write the package version file to achieve whatever
compatibility rules you use for your project versioning.

> Also, all the examples use find_package_handle_standard_args, but that
> only sets the upper case variable OPENRAVE_FOUND.. does that mean i
> have to use all upper case?

This is an issue for find modules, not package configuration files.

That's a convention due to the history of the way find modules were originally
written.  By the time the standard handling and conventions were introduced
almost every module used upper-case names even if the module name itself was
CamelCase.  Some modules provide CamelCase variables and then copy the result
from find_package_handle_standard_args over to a CamelCase_FOUND variable.

> So I'm guessing that the fact that openrave-config.cmake is found
> means an installation exists and we should use the prefix set during
> cmake to fill the include directories, etc?

I typically write them to compute the installation prefix relative to their
own location.  That makes the file suitable for use in a relocatable tarball
distribution:

  get_filename_component(_PREFIX "${CMAKE_CURRENT_LIST_FILE}" PATH)
  get_filename_component(_PREFIX "${_PREFIX}" PATH) # repeat as needed
  get_filename_component(OpenRAVE_PREFIX "${_PREFIX}" PATH) # last step

> In other words openrave-config.cmake would just look like:
> 
> set(openrave_INCLUDE_DIRS "XXX")
> set(openrave_LIBRARIES openrave)
> set(openrave_VERSION_STRING "x.x.x")

Basically yes.  I might write it as

  set(OpenRAVE_INCLUDE_DIRS "${OpenRAVE_PREFIX}/include")
  set(OpenRAVE_LIBRARIES openrave)
  set(OpenRAVE_VERSION_STRING "x.x.x")

Then provide the "openrave" library as an imported target:

  http://www.cmake.org/Wiki/CMake/Tutorials/Exporting_and_Importing_Targets

That will help applications link to the library nicely.

-Brad