updated catkin variables, updated api doc

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 2.8)
 project(catkin)
 
 # the following lines must be the same as in catkin/cmake/catkinConfig.cmake.in
-set(catkin_BUILD_PREFIX ${CMAKE_BINARY_DIR}/buildspace CACHE PATH "catkin buildspace")
+set(CATKIN_BUILD_PREFIX ${CMAKE_BINARY_DIR}/buildspace CACHE PATH "catkin buildspace")
 set(catkin_EXTRAS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake CACHE PATH "catkin extras")
 list(INSERT CMAKE_PREFIX_PATH 0 ${CMAKE_BINARY_DIR}/buildspace)
 set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} PARENT_SCOPE)
@@ -18,20 +18,20 @@ catkin_project(catkin)
 
 # for backward compatibility we provide ROSConfig(-version).cmake files
 file(COPY cmake/ROSConfig.cmake
-  DESTINATION ${catkin_BUILD_PREFIX}/share/ros/cmake
+  DESTINATION ${CATKIN_BUILD_PREFIX}/share/ros/cmake
 )
 set(PROJECT_VERSION ${catkin_VERSION})
 configure_file(${catkin_EXTRAS_DIR}/templates/pkgConfig-version.cmake.in
-  ${catkin_BUILD_PREFIX}/share/ros/cmake/ROSConfig-version.cmake
+  ${CATKIN_BUILD_PREFIX}/share/ros/cmake/ROSConfig-version.cmake
   @ONLY
 )
-install(FILES ${catkin_BUILD_PREFIX}/share/ros/cmake/ROSConfig.cmake ${catkin_BUILD_PREFIX}/share/ros/cmake/ROSConfig-version.cmake
+install(FILES ${CATKIN_BUILD_PREFIX}/share/ros/cmake/ROSConfig.cmake ${CATKIN_BUILD_PREFIX}/share/ros/cmake/ROSConfig-version.cmake
   DESTINATION share/ros/cmake
 )
 
 # for compatibility we provide eigen-config(-version).cmake files
 file(COPY cmake/Modules/eigen-config.cmake cmake/Modules/eigen-config-version.cmake
-  DESTINATION ${catkin_BUILD_PREFIX}/share/eigen/cmake
+  DESTINATION ${CATKIN_BUILD_PREFIX}/share/eigen/cmake
 )
 install(FILES cmake/Modules/eigen-config.cmake cmake/Modules/eigen-config-version.cmake
   DESTINATION share/eigen/cmake
@@ -47,4 +47,4 @@ install(DIRECTORY cmake
 
 catkin_python_setup()
 
-add_nosetests(test)
+catkin_add_nosetests(test)

bin/CMakeLists.txt

@@ -14,13 +14,13 @@ set(programs
 # install all programs
 install(PROGRAMS
   ${programs}
-  DESTINATION ${GLOBAL_BIN_DESTINATION}
+  DESTINATION bin
 )
 
 # generate relay-script for each program
 foreach(program ${programs})
   set(EXECUTABLE ${catkin_SOURCE_DIR}/bin/${program})
   configure_file(${catkin_EXTRAS_DIR}/templates/script.sh.in
-    ${catkin_BUILD_PREFIX}/${GLOBAL_BIN_DESTINATION}/${program}
+    ${CATKIN_BUILD_PREFIX}/bin/${program}
     @ONLY)
 endforeach()

cmake/all.cmake

@@ -4,8 +4,8 @@ if(_CATKIN_ALL_INCLUDED_)
 endif()
 set(_CATKIN_ALL_INCLUDED_ TRUE)
 
-if(NOT catkin_BUILD_PREFIX)
-  message(FATAL_ERROR "\ncatkin_BUILD_PREFIX is not set\n")
+if(NOT CATKIN_BUILD_PREFIX)
+  message(FATAL_ERROR "\nCATKIN_BUILD_PREFIX is not set\n")
 endif()
 if(NOT catkin_EXTRAS_DIR)
   message(FATAL_ERROR "\ncatkin_EXTRAS_DIR is not set\n")
@@ -33,7 +33,6 @@ cmake_policy(SET CMP0017 NEW)
 
 list(APPEND CMAKE_MODULE_PATH ${catkin_EXTRAS_DIR}/Modules)
 
-# XXX move stuff to separate folders
 # functions/macros: list_append_unique, safe_execute_process
 # python-integration: catkin_python_setup.cmake, interrogate_setup_dot_py.py, templates/__init__.py.in, templates/script.py.in, templates/python_distutils_install.bat.in, templates/python_distutils_install.sh.in, templates/safe_execute_install.cmake.in
 foreach(filename
@@ -55,6 +54,7 @@ foreach(filename
     platform/lsb
     platform/ubuntu
     platform/windows
+    rosbuild_compat
     test/download_test_data
     test/gtest
     test/nosetests
@@ -63,8 +63,6 @@ foreach(filename
     tools/libraries
     tools/rt
 
-#    install_matching_to_share
-#    rosbuild_compat
 #    tools/threads
   )
   include(${catkin_EXTRAS_DIR}/${filename}.cmake)
@@ -79,9 +77,9 @@ catkin_generate_environment()
 
 # environment to call external processes
 if(CMAKE_HOST_UNIX) # true for linux, apple, mingw-cross and cygwin
-  set(CATKIN_ENV ${catkin_BUILD_PREFIX}/env.sh CACHE INTERNAL "catkin environment")
+  set(CATKIN_ENV ${CATKIN_BUILD_PREFIX}/env.sh CACHE INTERNAL "catkin environment")
 else()
-  set(CATKIN_ENV ${catkin_BUILD_PREFIX}/env.bat CACHE INTERNAL "catkin environment")
+  set(CATKIN_ENV ${CATKIN_BUILD_PREFIX}/env.bat CACHE INTERNAL "catkin environment")
 endif()
 
 # add additional environment hooks

cmake/catkinConfig.cmake.in

@@ -58,9 +58,9 @@ foreach(workspace ${workspaces})
 endforeach()
 
 # the following lines must be the same as in catkin/CMakeLists.txt
-set(catkin_BUILD_PREFIX ${CMAKE_BINARY_DIR}/buildspace CACHE PATH "catkin buildspace")
+set(CATKIN_BUILD_PREFIX ${CMAKE_BINARY_DIR}/buildspace CACHE PATH "catkin buildspace")
 # compare boolean as string since policy CMP0012 is only enabled afterwards
-if("@PKG_BUILDSPACE@" STREQUAL "TRUE")
+if("@BUILDSPACE@" STREQUAL "TRUE")
   set(catkin_EXTRAS_DIR @catkin_EXTRAS_DIR@)
 else()
   set(catkin_EXTRAS_DIR @PKG_CMAKE_DIR@)

cmake/catkin_add_env_hooks.cmake

@@ -1,52 +1,61 @@
 #
-# For each shell in ``SHELLS``, ``<fileprefix>.<shell>.in`` in the
+# Register environment hooks which are executed by the setup script.
+#
+# For each shell in ``SHELLS``, ``<file_prefix>.<shell>.in`` in the
 # directory ``DIRECTORY`` is expand to ``etc/catkin/profile.d/``,
 # where it will be read by generated ``setup.<shell>``.
 #
-# The template can distinguish between build- and installspace using
-# the boolean parameters ``ENV_BUILDSPACE`` and ``ENV_INSTALLSPACE``
+# The template can distinguish between build- and installspace
+# using the boolean variables ``BUILDSPACE`` and ``INSTALLSPACE``
 # which are either ``true`` or ``false``.
 #
 # .. note:: Note the extra ".in" that must appear in the filename
-#    that does not appear in the argument.
+#   that does not appear in the argument.
 #
-# **NOTE** These files will share a single directory with other
-# packages that choose to install env hooks.  Be careful to give the
-# file a unique name.  Typically ``NNprojectname.sh`` is used, where
-# NN can define when something should be run (the files are read in
-# alphanumeric order) and ``projectname`` serves to disambiguate in
-# the event of collision.
+# .. note:: These files will share a single directory with other
+#   packages that choose to install env hooks.  Be careful to give
+#   the file a unique name.  Typically ``NN.name.<shell>`` is used,
+#   where NN can define when something should be run (the files are
+#   read in alphanumeric order) and the name serves to disambiguate
+#   in the event of collisions.
 #
-# :param SHELLS: list of shells (i.e.: sh bat)
-# :param DIRECTORY: Directory of the env hooks (default ${CMAKE_CURRENT_SOURCE_DIR})
+# :param file_prefix: the filename prefix
+# :type file_prefix: string
+# :param SHELLS: the shell extensions (i.e.: sh bat)
+# :type SHELLS: list of strings
+# :param DIRECTORY: the directory (default: ${CMAKE_CURRENT_SOURCE_DIR})
+# :type DIRECTORY: string
 # :param SKIP_INSTALL: if specified the env hooks are only generated
 #   in the buildspace but not installed
+# :type SKIP_INSTALL: option
+#
+# @public
 #
-function(catkin_add_env_hooks ARG_ENV_HOOK)
+function(catkin_add_env_hooks file_prefix)
   parse_arguments(ARG "DIRECTORY;SHELLS" "SKIP_INSTALL" ${ARGN})
 
   # create directory if necessary
-  if(NOT IS_DIRECTORY ${catkin_BUILD_PREFIX}/etc/catkin/profile.d)
-    file(MAKE_DIRECTORY ${catkin_BUILD_PREFIX}/etc/catkin/profile.d)
+  if(NOT IS_DIRECTORY ${CATKIN_BUILD_PREFIX}/etc/catkin/profile.d)
+    file(MAKE_DIRECTORY ${CATKIN_BUILD_PREFIX}/etc/catkin/profile.d)
   endif()
 
   if(NOT ARG_DIRECTORY)
     set(ARG_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
   endif()
 
   foreach(shell ${ARG_SHELLS})
-    set(ENV_HOOK ${ARG_ENV_HOOK}.${shell})
+    set(ENV_HOOK ${file_prefix}.${shell})
     assert_file_exists(${ARG_DIRECTORY}/${ENV_HOOK}.in "User-supplied environment file '${ARG_DIRECTORY}/${ENV_HOOK}.in' missing")
 
     # generate environment hook for buildspace
-    set(ENV_BUILDSPACE true)
-    set(ENV_INSTALLSPACE false)
+    set(BUILDSPACE true)
+    set(INSTALLSPACE false)
     configure_file(${ARG_DIRECTORY}/${ENV_HOOK}.in
-      ${catkin_BUILD_PREFIX}/etc/catkin/profile.d/${ENV_HOOK})
+      ${CATKIN_BUILD_PREFIX}/etc/catkin/profile.d/${ENV_HOOK})
 
     # generate and install environment hook for installspace
-    set(ENV_BUILDSPACE false)
-    set(ENV_INSTALLSPACE true)
+    set(BUILDSPACE false)
+    set(INSTALLSPACE true)
     configure_file(${ARG_DIRECTORY}/${ENV_HOOK}.in
       ${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/${ENV_HOOK})
     if(NOT ${ARG_SKIP_INSTALL})

cmake/catkin_generate_environment.cmake

@@ -1,42 +1,42 @@
 function(catkin_generate_environment)
   # buildspace
-  set(SETUP_DIR ${catkin_BUILD_PREFIX})
-  set(CURRENT_WORKSPACE ${catkin_BUILD_PREFIX}:${CMAKE_SOURCE_DIR})
+  set(SETUP_DIR ${CATKIN_BUILD_PREFIX})
+  set(CURRENT_WORKSPACE ${CATKIN_BUILD_PREFIX}:${CMAKE_SOURCE_DIR})
 
   # create workspace marker
-  file(WRITE ${catkin_BUILD_PREFIX}/CATKIN_WORKSPACE "")
+  file(WRITE ${CATKIN_BUILD_PREFIX}/CATKIN_WORKSPACE "")
   # copy setup.py
   file(COPY ${catkin_EXTRAS_DIR}/templates/setup.py
-    DESTINATION ${catkin_BUILD_PREFIX})
+    DESTINATION ${CATKIN_BUILD_PREFIX})
 
   if(NOT MSVC)
     # non-windows
     # generate env
     configure_file(${catkin_EXTRAS_DIR}/templates/env.sh.in
-      ${catkin_BUILD_PREFIX}/env.sh
+      ${CATKIN_BUILD_PREFIX}/env.sh
       @ONLY)
     # generate setup for various shells
     em_expand(${catkin_EXTRAS_DIR}/templates/setup.context.py.in
       ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/setup.buildspace.context.py
       ${catkin_EXTRAS_DIR}/em/setup.sh.em
-      ${catkin_BUILD_PREFIX}/setup.sh)
+      ${CATKIN_BUILD_PREFIX}/setup.sh)
     foreach(shell bash zsh)
       configure_file(${catkin_EXTRAS_DIR}/templates/setup.${shell}.in
-        ${catkin_BUILD_PREFIX}/setup.${shell}
+        ${CATKIN_BUILD_PREFIX}/setup.${shell}
         @ONLY)
     endforeach()
 
   else()
     # windows
     # generate env
     configure_file(${catkin_EXTRAS_DIR}/templates/env.bat.in
-      ${catkin_BUILD_PREFIX}/env.bat
+      ${CATKIN_BUILD_PREFIX}/env.bat
       @ONLY)
     # generate setup
     em_expand(${catkin_EXTRAS_DIR}/templates/setup.context.py.in
       ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/setup.buildspace.context.py
       ${catkin_EXTRAS_DIR}/em/setup.bat.em
-      ${catkin_BUILD_PREFIX}/setup.bat)
+      ${CATKIN_BUILD_PREFIX}/setup.bat)
   endif()
 
   # installspace
@@ -46,7 +46,7 @@ function(catkin_generate_environment)
   if(NOT CATKIN_BUILD_BINARY_PACKAGE OR "${PROJECT_NAME}" STREQUAL "catkin")
     # install workspace marker
     install(FILES
-      ${catkin_BUILD_PREFIX}/CATKIN_WORKSPACE
+      ${CATKIN_BUILD_PREFIX}/CATKIN_WORKSPACE
       DESTINATION ${CMAKE_INSTALL_PREFIX})
     # install setup.py
     install(PROGRAMS