Forcing a locally installed Boost to be used instead of the system-level one

Code
1

Hi all,

I have been trying to get Boost working with CMake. What I did almost a year ago is detailed here: CMake with Boost and policy CMP0167 . And that still works, thankfully. :slight_smile: There is just one problem which I do not understand – it isn’t prioritising the path in ${BOOST_ROOT}. I thought it should?

My source code currently has these 3 lines:

## Set the minimum version and the required components
set (BOOST_MIN_VERSION 1.85.0)
set (BOOST_REQUIRED_COMPONENTS program_options filesystem headers)

## Locate Boost using the Boost-provided BoostConfig.cmake
find_package (Boost ${BOOST_MIN_VERSION} COMPONENTS ${BOOST_REQUIRED_COMPONENTS})

I’m currently using Ubuntu 25.10, which installs cmake/Boost-1.88.0/BoostConfig.cmake through the libboost1.88-dev package. In /usr/local/boost/, I have Boost 1.90 installed by downloading and compiling it.

I also have ${BOOST_ROOT} set to /usr/local/boost/.

If I leave the above 3 lines as-is, it uses 1.88 and fails (because I haven’t installed every Boost 1.88 packges).

If I change the first line from “1.85.0” to “1.90.0”, then it finds 1.90 and proceeds perfectly.

I guess I have misunderstood ${BOOST_ROOT}. I thought its purpose was to ensure it is searched first.

Is there an environment variable I could set or a change I can make to my CMakeLists.txt to make it look in /usr/local/boost/ before the system-level paths?

(The remainder of the Boost section of my CMakeLists.txt is probably not relevant, but just in case it is, it is here: QScores-Archiver/src/cmake/boost.cmake at master · rwanwork/QScores-Archiver · GitHub .)

Thank you!

Ray

PS: Of course, another solution is to just install all of the Ubuntu packages that it needs – but I was hoping to use what I have set up in /usr/local/boost/.

2

In config mode, this value is not used!

Set CMAKE_PREFIX_PATH or use the HINT option

1 Like
3

Hi Claus,

Oh! I see – I clearly misunderstood how BOOST_ROOT could be used. Thank you again for your help; I will look into the two options you mentioned!

Ray

4

Why do you say that? In the CMake documentation for the find_package() command, the first location searched by find_package() as defined in the “Config Mode Search Procedure” is described like this:

1. Search prefixes unique to the current <PackageName> being found. See policy CMP0074.

Added in version 3.12.

Specifically, search prefixes specified by the following variables, in order:

a. <PackageName>_ROOT CMake variable, where <PackageName> is the case-preserved package name.
b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the upper-cased package name. See policy CMP0144.

Added in version 3.27.

c. <PackageName>_ROOT environment variable, where <PackageName> is the case-preserved package name.
d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is the upper-cased package name. See policy CMP0144.

Added in version 3.27.

@rwan What’s the full, absolute path to the BoostConfig.cmake file you are having trouble getting it to find using BOOST_ROOT? What CMake version are you using?

1 Like
5

@craig.scott

Why do you say that?

First: I dit not know that BOOST_ROOT is used again because it is not my case-preserved Boost_ROOT name.

Calls to find_package(<PackageName>) will search in prefixes specified by the 
<PackageName>_ROOT CMake variable, where <PackageName> is the (case-preserved) name given to the find_package() call and _ROOT is literal. For example, find_package(Foo) will search prefixes specified in the Foo_ROOT CMake variable (if set). See policy CMP0074.

Second: I would expect to get a NOT_FOUND error in this case

Some of the required COMPONENTS are not found in BOOST_ROOT:

Tested with this CMakeLists.txtand cmake v4.2.3:

cmake_minimum_required(VERSION 3.28...4.3 FATAL_ERROR)

# ---- Project ----

# Note: update this to your new project's name and version
project(Arcanelords VERSION 0.1 LANGUAGES CXX)

# ---- Include guards ----

if(PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR)
    message(
        FATAL_ERROR
        "In-source builds not allowed. Please make a new directory (called a build directory) and run CMake from there."
    )
endif()

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")

include(AddUninstallTarget)

# Added in version 3.30. The FindBoost module is removed.
if(POLICY CMP0167)
  cmake_policy(SET CMP0167 NEW)
endif()

set(Boost_VERBOSE ON)
set(Boost_DEBUG ON)

set(BOOST_ROOT $ENV{HOME}/.local)
set(BOOST_MIN_VERSION 1.90.0)
set(BOOST_REQUIRED_COMPONENTS program_options filesystem)
find_package(Boost ${BOOST_MIN_VERSION} REQUIRED EXACT COMPONENTS ${BOOST_REQUIRED_COMPONENTS})

I get this result:

-- Configuring incomplete, errors occurred!
bash-5.3$ cmake -S . -B build
-- Found Boost 1.90.0 at /Users/clausklein/.local/lib/cmake/Boost-1.90.0
--   Requested configuration: REQUIRED COMPONENTS program_options;filesystem
-- BoostConfig: find_package(boost_headers 1.90.0 EXACT CONFIG REQUIRED  HINTS /Users/clausklein/.local/lib/cmake)
-- Found boost_headers 1.90.0 at /Users/clausklein/.local/lib/cmake/boost_headers-1.90.0
-- BoostConfig: find_package(boost_program_options 1.90.0 EXACT CONFIG REQUIRED  HINTS /Users/clausklein/.local/lib/cmake)
-- Found boost_program_options 1.90.0 at /usr/local/lib/cmake/boost_program_options-1.90.0
-- Boost toolset is clang-darwin16 (AppleClang 16.0.0.16000026)
-- Scanning /usr/local/lib/cmake/boost_program_options-1.90.0/libboost_program_options-variant*.cmake
--   Including /usr/local/lib/cmake/boost_program_options-1.90.0/libboost_program_options-variant-shared.cmake
--   [x] libboost_program_options.dylib
--   Including /usr/local/lib/cmake/boost_program_options-1.90.0/libboost_program_options-variant-static.cmake
--   [ ] libboost_program_options.a
-- Adding boost_program_options dependencies: container;headers
-- Found boost_container 1.90.0 at /usr/local/lib/cmake/boost_container-1.90.0
-- Boost toolset is clang-darwin16 (AppleClang 16.0.0.16000026)
-- Scanning /usr/local/lib/cmake/boost_container-1.90.0/libboost_container-variant*.cmake
--   Including /usr/local/lib/cmake/boost_container-1.90.0/libboost_container-variant-shared.cmake
--   [x] libboost_container.dylib
--   Including /usr/local/lib/cmake/boost_container-1.90.0/libboost_container-variant-static.cmake
--   [ ] libboost_container.a
-- Adding boost_container dependencies: headers
-- Found boost_headers 1.90.0 at /Users/clausklein/.local/lib/cmake/boost_headers-1.90.0
-- Found boost_headers 1.90.0 at /Users/clausklein/.local/lib/cmake/boost_headers-1.90.0
-- BoostConfig: find_package(boost_filesystem 1.90.0 EXACT CONFIG REQUIRED  HINTS /Users/clausklein/.local/lib/cmake)
-- Found boost_filesystem 1.90.0 at /usr/local/lib/cmake/boost_filesystem-1.90.0
-- Boost toolset is clang-darwin16 (AppleClang 16.0.0.16000026)
-- Scanning /usr/local/lib/cmake/boost_filesystem-1.90.0/libboost_filesystem-variant*.cmake
--   Including /usr/local/lib/cmake/boost_filesystem-1.90.0/libboost_filesystem-variant-shared.cmake
--   [x] libboost_filesystem.dylib
--   Including /usr/local/lib/cmake/boost_filesystem-1.90.0/libboost_filesystem-variant-static.cmake
--   [ ] libboost_filesystem.a
-- Adding boost_filesystem dependencies: atomic;headers
-- Found boost_atomic 1.90.0 at /usr/local/lib/cmake/boost_atomic-1.90.0
-- Boost toolset is clang-darwin16 (AppleClang 16.0.0.16000026)
-- Scanning /usr/local/lib/cmake/boost_atomic-1.90.0/libboost_atomic-variant*.cmake
--   Including /usr/local/lib/cmake/boost_atomic-1.90.0/libboost_atomic-variant-shared.cmake
--   [x] libboost_atomic.dylib
--   Including /usr/local/lib/cmake/boost_atomic-1.90.0/libboost_atomic-variant-static.cmake
--   [ ] libboost_atomic.a
-- Adding boost_atomic dependencies: headers
-- Found boost_headers 1.90.0 at /Users/clausklein/.local/lib/cmake/boost_headers-1.90.0
-- Found boost_headers 1.90.0 at /Users/clausklein/.local/lib/cmake/boost_headers-1.90.0
-- Configuring done (0.6s)
-- Generating done (0.0s)
-- Build files have been written to: /Users/clausklein/cmake/test/build
bash-5.3$
6

Hi Craig,

Thank you for the follow-up! I’m using the default CMake for Ubuntu 25.10, which is CMake version 3.31.6 .

My installation has two BoostConfig.cmake:

  • /usr/local/Boost_1_90_0/tools/boost_install/BoostConfig.cmake
  • /usr/local/Boost_1_90_0/tools/cmake/config/BoostConfig.cmake

I’m not sure which one I should use as they don’t seem identical.

Since Claus provided a minimum working example, I gave it a try with a few minor changes (i.e., removed “include (AddUninstallTarget)”). This is what I get (/usr/local/boost from my earlier message is a symbolic link to /usr/local/Boost_1_90_0/):

$ env | grep BOOST_ROOT
BOOST_ROOT=/usr/local/Boost_1_90_0
$ cmake ..
CMake Error at CMakeLists.txt:32 (find_package):
Could not find a configuration file for package “Boost” that exactly
matches requested version “1.90.0”.

The following configuration files were considered but not accepted:

/usr/lib/x86_64-linux-gnu/cmake/Boost-1.88.0/BoostConfig.cmake, version: 1.88.0
/lib/x86_64-linux-gnu/cmake/Boost-1.88.0/BoostConfig.cmake, version: 1.88.0

– Configuring incomplete, errors occurred!

With both Boost_VERBOSE and Boost_DEBUG turned ON, I was hoping it would print a message indicating that it tried searching in BOOST_ROOT. But, no…

If I change BOOST_MIN_VERSION to 1.88.0, then it works since it finds the system installed files (after having installed the Ubuntu “program_options” and “filesystem” packages).

I just played around a bit more and changed BOOST_MIN_VERSION back to 1.90.0. Then, I changed the value of BOOST_ROOT by adding tools to the end (I naively thought maybe I could help it a bit…). And I got this:

$ export BOOST_ROOT=/usr/local/Boost_1_90_0/tools
$ cmake ..
CMake Error at CMakeLists.txt:32 (find_package):
Could not find a configuration file for package “Boost” that exactly
matches requested version “1.90.0”.

The following configuration files were considered but not accepted:

/usr/local/Boost_1_90_0/tools/boost_install/BoostConfig.cmake, version: unknown
/usr/lib/x86_64-linux-gnu/cmake/Boost-1.88.0/BoostConfig.cmake, version: 1.88.0
/lib/x86_64-linux-gnu/cmake/Boost-1.88.0/BoostConfig.cmake, version: 1.88.0

– Configuring incomplete, errors occurred!

So…it is accepting BOOST_ROOT but it’s not using it as I (we?) expect?

Maybe you can see something that I cannot… Thank you for your help!

Ray

7

It seems to me, you have downloaded the source file archive without cmake, that is not usable out of the box!

If you want to build boost yourself it only works like this:

cmake_minimum_required(VERSION 3.30...4.3)

project(BoostExamples LANGUAGES CXX)

enable_testing()

# ---- Dependencies ----

if(PROJECT_IS_TOP_LEVEL)
    include(../cmake/ccache.cmake)

    set(CMAKE_SKIP_TEST_ALL_DEPENDENCY NO)
    if(NOT DEFINED CMAKE_CXX_STANDARD)
        set(CMAKE_CXX_STANDARD 20)
    endif()
    if(NOT DEFINED CMAKE_PREFIX_PATH)
        list(APPEND CMAKE_PREFIX_PATH ../stagedir)
    endif()
    if(NOT DEFINED BOOST_USE_MODULES)
        set(BOOST_USE_MODULES OFF)
    endif()
    if(BOOST_USE_MODULES)
        set(CMAKE_CXX_SCAN_FOR_MODULES ON)
        set(CMAKE_CXX_MODULE_STD OFF) # TODO(CK): not yet!
    else()
        set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
    endif()

    block()
        set(BOOST_DEBUG YES)
        set(BOOST_VERBOSE YES)
        list(APPEND BOOST_INCLUDE_LIBRARIES any asio regex test)

        set(CMAKE_SKIP_INSTALL_RULES ON)

        set(BUILD_SHARED_LIBS ON)
        set(BOOST_SKIP_INSTALL_RULES ${CMAKE_SKIP_INSTALL_RULES})
        set(BOOST_VERSION 1.90.0)

        include(FetchContent)
        FetchContent_Declare(
            Boost
            URL
                https://github.com/boostorg/boost/releases/download/boost-${BOOST_VERSION}/boost-${BOOST_VERSION}-cmake.7z
            URL_HASH
                SHA256=218e74c4aa362a994b7b7a23b2920f455a00205c656405fcf262cf60b8871921
            EXCLUDE_FROM_ALL
            SYSTEM
            FIND_PACKAGE_ARGS
                ${BOOST_VERSION}
                COMPONENTS
                any
                asio
                regex
                unit_test_framework
        )
        FetchContent_MakeAvailable(Boost)
    endblock()
endif()

You find my current version of here boost-cmake ; use if as you need.

The most important variable for you to set is BOOST_INCLUDE_LIBRARIES

1 Like
8

Hi Claus,

Thank you for the follow-up!

/usr/local/boost/ has Boost downloaded from Boost 1.90.0 and installed using the installation instructions ( Boost Getting Started on Unix Variants ) – i.e., ./bootstrap.h and ./b2.

This cannot be used directly by CMake? I thought a C++ project configured using CMake could use it directly, just like other shared libraries on my system. (I have heard from others that Boost support in “CMake” is special and not straight-forward…I didn’t know why, but I guess I do now!)

Thank you for your advice and the sample code! I now know what I was trying wasn’t possible and the only way is what your code does.

Thank you!

Ray

9

Original boost Easy Build and Install works too, but you have to install it and not use the build tree!

My boost-cmake helps if you wand to build only a view boost libs and their dependentcies and install it from you own cmake project using FetchContent.