From fb63bd1261756cb2645a13769508ecf121794bf0 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Wed, 12 Jun 2024 12:31:37 -0400
Subject: [PATCH] ++ README improvements -- bring up-to-date

---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 40 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index c5c6353d..db3b4dd8 100644
--- a/README.md
+++ b/README.md
@@ -6,23 +6,54 @@ Collects cmake macros to be shared across XO projects (e.g. indentlog, reflect,
 
 - support for both manyrepo and monorepo projects
 - support for generating cmake `xxxConfig.cmake` files,  so cmake `find_package()` works reliably
+- support for header-only libraries
+- support for pybind11 libraries
+- documentation generation using doxygen + breathe + sphinx
+- code coverage using ccov + lcov
 
-## Example
+## Getting Started
+
+### copy repo
 
-In some XO project `foo`:
 ```
-$ cd build
-$ PREFIX=/usr/local # or wherever you prefer
-$ cmake -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake -DCMAKE_INSTALL_PREFIX=${PREFIX} ..
-$ make install
+$ git clone https://github.com:rconybea/xo-cmake.git
 ```
 
+### configure + install
+```
+$ cd xo-cmake
+$ cmake -DCMAKE_INSTALL_PREFIX=/usr/local -B .build -S .   # ..or desired prefix
+$ cmake --install .build
+```
+
+## use from a cmake project
+
+In some project `foo`:
+```
+$ cd foo
+$ mkdir cmake
+$ cp $PREFIX/share/xo-macros/xo-bootstrap-macros.cmake cmake/
+```
+
+`xo-bootstrap-macros-cmake` has two vital jobs:
+1. set `XO_CMAKE_CONFIG_EXECUTABLE` (locate `xo-cmake-config`)
+2. set `CMAKE_MODULE_PATH` (obtained from `xo-cmake-config --cmake-module-path`)
+
 then in `foo/CMakeLists.txt`:
 ```
-include(xo_macros/xo_cxx)
+include(cmake/xo-bootstrap-macros.cmake)
 ```
 
-when configuring `foo`:
+Now as long as `$PREFIX/bin` is in `PATH`:
 ```
-$ cmake -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake path/to/foo
+$ cd mybuild
+$ cmake path/to/foo/source
+```
+
+### or set `XO_CMAKE_CONFIG_EXECUTABLE` and `CMAKE_MODULE_PATH`
+
+In some project `foo`:
+```
+$ cd mybuild
+$ cmake -DXO_CMAKE_CONFIG_EXECUTABLE=xo-cmake-config -DCMAKE_MODULE_PATH=$(xo-cmake-config --cmake-module-path) path/to/foo/source
 ```