Add USE_VENDORED_JSON option to use the system nlohmann_json (fixes #959) (#1235)

* Add USE_VENDORED_JSON option to use the system nlohmann_json (fixes #959)

BT.CPP bundles nlohmann/json 3.11.3 and its public headers include it
unconditionally. A user that also includes a system nlohmann/json gets two
versions behind the same include guard: whichever comes first wins, and the
result is mismatched types or link errors (#959).

With -DUSE_VENDORED_JSON=OFF the library uses find_package(nlohmann_json 3.10):
- the public headers include <nlohmann/json.hpp> when BTCPP_SYSTEM_JSON is
  defined. The library exports that definition together with the
  nlohmann_json target (CMake config and ament), so its users see the same
  version it was built with;
- the bundled header is not installed: a user that bypasses the CMake target
  (plain include dirs, Makefiles, Bazel) fails to compile, instead of
  silently mixing two versions;
- the tests get nlohmann::json from the BT.CPP headers, like any user,
  instead of including the bundled copy directly.

The default (ON) is unchanged: it needs no new definition and the headers
preprocess to the same code, so the API and ABI are the same.

nlohmann::json is part of the public API, so an OFF build has a different ABI
than the default one: everything linking it must use the same nlohmann_json.

A new CI job builds and tests OFF on Ubuntu 22.04 with apt's nlohmann_json
3.10.5, the oldest supported version.

Supersedes #1080.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* CI: limit the system-json build to nproc jobs

'cmake --build --parallel' without a number runs an unbounded 'make -j' with
the default generator: the runner ran out of memory and was shut down.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: facontidavide

.github/workflows/cmake_ubuntu.yml

@@ -50,6 +50,27 @@ jobs:
     - name: run test (Linux)
       run: ctest --test-dir build/${{env.BUILD_TYPE}}
 
+  # USE_VENDORED_JSON=OFF, with the oldest supported nlohmann_json (3.10.5 on 22.04)
+  system-json:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y nlohmann-json3-dev libzmq3-dev libsqlite3-dev libgtest-dev
+
+    - name: Configure CMake
+      run: cmake -B build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} -DUSE_VENDORED_JSON=OFF
+
+    - name: Build
+      run: cmake --build build --parallel $(nproc)
+
+    - name: run test
+      run: ctest --test-dir build --output-on-failure
+
   coverage:
     runs-on: ubuntu-24.04
 

CMakeLists.txt

@@ -25,6 +25,7 @@ option(FORCE_STATIC_LINKING "Force static linking of all dependencies" OFF)
 
 option(USE_VENDORED_CPPZMQ "Use the bundled version of cppzmq" ON)
 option(USE_VENDORED_FLATBUFFERS "Use the bundled version of flatbuffers" ON)
+option(USE_VENDORED_JSON "Use the bundled version of nlohmann/json" ON)
 option(USE_VENDORED_MINICORO "Use the bundled version of minicoro" ON)
 option(USE_VENDORED_MINITRACE "Use the bundled version of minitrace" ON)
 
@@ -133,6 +134,10 @@ else()
     find_package(flatbuffers REQUIRED)
 endif()
 
+if(NOT USE_VENDORED_JSON)
+    find_package(nlohmann_json 3.10 REQUIRED)
+endif()
+
 if(USE_VENDORED_MINICORO)
     add_subdirectory(3rdparty/minicoro)
 else()
@@ -259,6 +264,12 @@ target_include_directories(${BTCPP_LIBRARY}
 
 target_compile_definitions(${BTCPP_LIBRARY} PUBLIC BTCPP_LIBRARY_VERSION="${PROJECT_VERSION}")
 
+if(NOT USE_VENDORED_JSON)
+    # The public headers include <nlohmann/json.hpp> instead of the bundled copy
+    target_compile_definitions(${BTCPP_LIBRARY} PUBLIC BTCPP_SYSTEM_JSON)
+    target_link_libraries(${BTCPP_LIBRARY} PUBLIC nlohmann_json::nlohmann_json)
+endif()
+
 target_compile_features(${BTCPP_LIBRARY} PUBLIC cxx_std_17)
 
 if(MSVC)
@@ -327,8 +338,14 @@ INSTALL(TARGETS ${BTCPP_LIBRARY}
     INCLUDES DESTINATION ${BTCPP_INCLUDE_DESTINATION}
     )
 
+if(NOT USE_VENDORED_JSON)
+    # Don't install the bundled copy: a user that doesn't get BTCPP_SYSTEM_JSON
+    # must fail to compile, rather than mix two versions of nlohmann::json
+    set(BTCPP_INSTALL_EXCLUDE REGEX "contrib/json\\.hpp$" EXCLUDE)
+endif()
+
 INSTALL( DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
     DESTINATION ${BTCPP_INCLUDE_DESTINATION}
-    FILES_MATCHING PATTERN "*.h*")
+    FILES_MATCHING PATTERN "*.h*" ${BTCPP_INSTALL_EXCLUDE})
 
 export_btcpp_package()

README.md

@@ -79,6 +79,11 @@ cmake -S . -B build_release
 cmake --build build_release --parallel
 ```
 
+BT.CPP includes its own copy of [nlohmann/json](https://github.com/nlohmann/json).
+To use the one installed in your system instead (version 3.10 or newer), add `-DUSE_VENDORED_JSON=OFF`.
+Since `nlohmann::json` is part of the public API, everything that links BT.CPP must then be
+compiled with that same version.
+
 If you want to build in a [pixi](https://pixi.sh/) project (conda virtual environment).
 ```
 pixi run build

cmake/Config.cmake.in

@@ -1,5 +1,10 @@
 @PACKAGE_INIT@
 
+if(NOT "@USE_VENDORED_JSON@")
+    include(CMakeFindDependencyMacro)
+    find_dependency(nlohmann_json 3.10)
+endif()
+
 include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
 
 set(@PROJECT_NAME@_TARGETS "BT::@PROJECT_NAME@")

cmake/ament_build.cmake

@@ -14,6 +14,9 @@ set( BTCPP_EXTRA_LIBRARIES
 )
 
 ament_export_dependencies(ament_index_cpp)
+if(NOT USE_VENDORED_JSON)
+    ament_export_dependencies(nlohmann_json)
+endif()
 
 # The ROS build farm (bloom/debhelper) configures with
 # -DCMAKE_INSTALL_LIBDIR=lib/<multiarch-triplet>, but ament tooling

include/behaviortree_cpp/blackboard.h

@@ -1,7 +1,11 @@
 #pragma once
 
 #include "behaviortree_cpp/basic_types.h"
+#ifdef BTCPP_SYSTEM_JSON
+#include <nlohmann/json.hpp>
+#else
 #include "behaviortree_cpp/contrib/json.hpp"
+#endif
 #include "behaviortree_cpp/exceptions.h"
 #include "behaviortree_cpp/utils/locked_reference.hpp"
 #include "behaviortree_cpp/utils/polymorphic_cast_registry.hpp"

include/behaviortree_cpp/bt_factory.h

@@ -15,7 +15,11 @@
 #define BT_FACTORY_H
 
 #include "behaviortree_cpp/behavior_tree.h"
+#ifdef BTCPP_SYSTEM_JSON
+#include <nlohmann/json.hpp>
+#else
 #include "behaviortree_cpp/contrib/json.hpp"
+#endif
 #include "behaviortree_cpp/contrib/magic_enum.hpp"
 #include "behaviortree_cpp/utils/polymorphic_cast_registry.hpp"
 

include/behaviortree_cpp/json_export.h

@@ -3,8 +3,13 @@
 #include "behaviortree_cpp/basic_types.h"
 #include "behaviortree_cpp/utils/safe_any.hpp"
 
-// Use the version nlohmann::json embedded in BT.CPP
+// Use the version of nlohmann::json embedded in BT.CPP,
+// or the system one if BT.CPP was built with USE_VENDORED_JSON=OFF
+#ifdef BTCPP_SYSTEM_JSON
+#include <nlohmann/json.hpp>
+#else
 #include "behaviortree_cpp/contrib/json.hpp"
+#endif
 
 namespace BT
 {

include/behaviortree_cpp/loggers/groot2_protocol.h

@@ -1,7 +1,11 @@
 #pragma once
 
 #include "behaviortree_cpp/basic_types.h"
+#ifdef BTCPP_SYSTEM_JSON
+#include <nlohmann/json.hpp>
+#else
 #include "behaviortree_cpp/contrib/json.hpp"
+#endif
 
 #include <array>
 #include <condition_variable>

tests/groot2_test_utils.hpp

@@ -10,7 +10,6 @@
 #include <behaviortree_cpp/loggers/groot2_protocol.h>
 #include <behaviortree_cpp/loggers/groot2_publisher.h>
 
-#include <behaviortree_cpp/contrib/json.hpp>
 #include <zmq_addon.hpp>
 
 namespace Groot2Test