How can I get CMake to find my alternative Boost installation?

You should have a look at FindBoost.cmake script, which handles Boost detection and setting up all Boost variables. It typically resides in /usr/share/cmake-2.6/Modules/. In it, you will find documentation. For instance:

# These last three variables are available also as environment variables:##   BOOST_ROOT or BOOSTROOT      The preferred installation prefix for searching for#                                Boost.  Set this if the module has problems finding#                                the proper Boost installation.#

In contrast to BOOST_ROOT, the variables you are referring to are actually variables that are set by the FindBoost module. Note that you don't have to (and probably also don't want to) edit your CMake project configuration to set BOOST_ROOT. Instead, you should use the environment variable, e.g. calling

# BOOST_ROOT=/usr/local/... ccmake .

I was finally able to get what I wanted with

cmake -DCMAKE_INSTALL_PREFIX=$TARGET \    -DBoost_NO_BOOST_CMAKE=TRUE \    -DBoost_NO_SYSTEM_PATHS=TRUE \    -DBOOST_ROOT:PATHNAME=$TARGET \    -DBoost_LIBRARY_DIRS:FILEPATH=${TARGET}/lib

The short version

You only need BOOST_ROOT, but you're going to want to disable searching the system for your local Boost if you have multiple installations or cross-compiling for iOS or Android. In which case add Boost_NO_SYSTEM_PATHS is set to false.

set( BOOST_ROOT "" CACHE PATH "Boost library path" )set( Boost_NO_SYSTEM_PATHS on CACHE BOOL "Do not search system for Boost" )

Normally this is passed on the CMake command-line using the syntax -D<VAR>=value.

The longer version

Officially speaking the FindBoost page states these variables should be used to 'hint' the location of Boost.

This module reads hints about search locations from variables:

BOOST_ROOT             - Preferred installation prefix (or BOOSTROOT)BOOST_INCLUDEDIR       - Preferred include directory e.g. <prefix>/includeBOOST_LIBRARYDIR       - Preferred library directory e.g. <prefix>/libBoost_NO_SYSTEM_PATHS  - Set to ON to disable searching in locations not                         specified by these hint variables. Default is OFF.Boost_ADDITIONAL_VERSIONS                       - List of Boost versions not known to this module                         (Boost install locations may contain the version)

This makes a theoretically correct incantation:

cmake -DBoost_NO_SYSTEM_PATHS=TRUE \      -DBOOST_ROOT=/path/to/boost-dir

When you compile from source

include( ExternalProject )set( boost_URL "http://sourceforge.net/projects/boost/files/boost/1.63.0/boost_1_63_0.tar.bz2" )set( boost_SHA1 "9f1dd4fa364a3e3156a77dc17aa562ef06404ff6" )set( boost_INSTALL ${CMAKE_CURRENT_BINARY_DIR}/third_party/boost )set( boost_INCLUDE_DIR ${boost_INSTALL}/include )set( boost_LIB_DIR ${boost_INSTALL}/lib )ExternalProject_Add( boost        PREFIX boost        URL ${boost_URL}        URL_HASH SHA1=${boost_SHA1}        BUILD_IN_SOURCE 1        CONFIGURE_COMMAND        ./bootstrap.sh        --with-libraries=filesystem        --with-libraries=system        --with-libraries=date_time        --prefix=<INSTALL_DIR>        BUILD_COMMAND        ./b2 install link=static variant=release threading=multi runtime-link=static        INSTALL_COMMAND ""        INSTALL_DIR ${boost_INSTALL} )set( Boost_LIBRARIES        ${boost_LIB_DIR}/libboost_filesystem.a        ${boost_LIB_DIR}/libboost_system.a        ${boost_LIB_DIR}/libboost_date_time.a )message( STATUS "Boost static libs: " ${Boost_LIBRARIES} )

Then when you call this script you'll need to include the boost.cmake script (mine is in the a subdirectory), include the headers, indicate the dependency, and link the libraries.

include( boost )include_directories( ${boost_INCLUDE_DIR} )add_dependencies( MyProject boost )target_link_libraries( MyProject                       ${Boost_LIBRARIES} )