diff --git a/cmake/xo_cxx.cmake b/cmake/xo_cxx.cmake
index 018f75fe..1e5d8897 100644
--- a/cmake/xo_cxx.cmake
+++ b/cmake/xo_cxx.cmake
@@ -29,7 +29,8 @@ macro(xo_toplevel_compile_options)
 endmacro()
 
 # ----------------------------------------------------------------
-# use this in subdirs that compile c++ code
+# use this in subdirs that compile c++ code.
+# do not use for header-only subsystems;  see xo_include_headeronly_options2()
 #
 macro(xo_include_options2 target)
     # ----------------------------------------------------------------
@@ -62,6 +63,37 @@ macro(xo_include_options2 target)
     endif()
 endmacro()
 
+macro(xo_include_headeronly_options2 target)
+    # ----------------------------------------------------------------
+    # PROJECT_SOURCE_DIR:
+    #   so we can for example write
+    #     #include "ordinaltree/foo.hpp"
+    #   from anywhere in the project
+    # PROJECT_BINARY_DIR:
+    #   since generated version file will be in build directory,
+    #   need that build directory to also appear in
+    #   compiler's include path
+    #
+    target_include_directories(
+      ${target} INTERFACE
+      $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>              # e.g. for #include "indentlog/scope.hpp"
+      $<INSTALL_INTERFACE:include>
+      $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/${target}>    # e.g. for #include "Refcounted.hpp" in refcnt/src
+      $<INSTALL_INTERFACE:include/${target}>
+      $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}>                      # e.g. for generated .hpp files
+    )
+
+    # ----------------------------------------------------------------
+    # make standard directories for std:: includes explicit
+    # so that
+    # (1) they appear in compile_commands.json.
+    # (2) clangd (run from emacs lsp-mode) can find them
+    #
+    if(CMAKE_EXPORT_COMPILE_COMMANDS)
+      set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
+    endif()
+endmacro()
+
 # ----------------------------------------------------------------
 #
 # Require: