Current situation

The Cmake 3.18 official documentation states:

If Boost was built using the boost-cmake project or from Boost 1.70.0 on it provides a package configuration file for use with find_package’s config mode. This module looks for the package configuration file called BoostConfig.cmake or boost-config.cmake and stores the result in CACHE entry “Boost_DIR”. If found, the package configuration file is loaded and this module returns with no further action. See documentation of the Boost CMake package configuration for details on what it provides.

Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.

Problem description

It may make sense for experts in cmake, but as this explanation lacks broader context explanation, it does not really help the cmake beginner.

Question

Could someone expand on this documentation ? For example, why to set Boost_NO_CMAKE to ON, when the default behavior could be problematic, and how to set the option for best practice ?

Basic answer

For example, there are some basic explanations here on the fact that Boost 1.70 comes with a new way of using Boost with CMake, that is making use of the Boost BoostConfig.cmake rather than the one coming from the CMake distribution.

Old way:

set(Boost_NO_BOOST_CMAKE ON)

find_package(Boost REQUIRED COMPONENTS thread timer)

include_directories(${Boost_INCLUDE_DIRS}
    ...)

link_directories(${Boost_LIBRARY_DIRS}
    ...)

target_link_libraries(...
    ${Boost_LIBRARIES}
    ...)

New way:

set(Boost_NO_BOOST_CMAKE OFF)

find_package(Boost REQUIRED COMPONENTS thread timer)

target_link_libraries(...
    Boost::thread
    Boost::timer
    ...)

Expanding on this information (for example how to make the changes when we don't have control of the code projects, or how to ensure retro-compatibility) would definitely be useful for non-experts in cmake.