From f7abb8fedba3f1ae98ae9f2af7c9ca6908dba824 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Fri, 15 Mar 2024 19:42:35 -0400
Subject: [PATCH] build: streamline CMAKE_MODULE_PATH interaction

---
 .gitignore                      |  6 ++-
 CMakeLists.txt                  |  3 +-
 README.md                       | 71 +++++++++++++++++++++++++++++++++
 cmake/xo-bootstrap-macros.cmake | 12 ++++++
 src/pywebsock/CMakeLists.txt    |  2 +-
 5 files changed, 90 insertions(+), 4 deletions(-)
 create mode 100644 README.md
 create mode 100644 cmake/xo-bootstrap-macros.cmake

diff --git a/.gitignore b/.gitignore
index d6536bad..13c0afb7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,6 @@
-build
+# clangd working space (see emacs+lsp)
+.cache
+# typical cmake build directory (source-tree-nephew)
+.build*
+# symlink to builddir/compile_commands.json;  should be set manually in dev sandbox
 compile_commands.json
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 20774e1c..56e9f2eb 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,10 +1,9 @@
 # xo-pywebsock/CMakeLists.txt
 
 cmake_minimum_required(VERSION 3.10)
-
 project(xo_pywebsock VERSION 1.0)
 
-include(xo_macros/xo-project-macros)
+include(cmake/xo-bootstrap-macros.cmake)
 
 xo_cxx_toplevel_options()
 
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..468c605d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# python bindings for c++ websocket library (xo-websock)
+
+## Getting Started
+
+### build + install dependencies
+
+- [github/Rconybea/xo-websock](https://github.com/Rconybea/xo-websock)
+- [github/Rconybea/xo-pyutil](https://github.com/Rconybea/xo-pyutil)
+- [github/Rconybea/xo-pyreactor](https://github.com/Rconybea/xo-pyreactor)
+
+### build + install
+
+```
+$ cd xo-pywebsock
+$ mkdir build
+$ cd build
+$ INSTALL_PREFIX=/usr/local  # or wherever you prefer, e.g. ~/local
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ..
+$ make
+$ make install
+```
+(also see .github/workflows/main.yml)
+
+## Examples
+
+Assumes `xo-pywebsock` installed to `~/local2/lib`
+```
+PYTHONPATH=~/local2/lib:$PYTHONPATH python
+>>> import xo_pywebsock
+>>> dir(xo_pywebsock)
+['Runstate', 'Webserver', 'WebserverConfig', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'make_webserver']
+>>>
+```
+
+## Development
+
+### build for unit test coverage
+```
+$ cd xo-pywebsock
+$ mkdir build-ccov
+$ cd build-ccov
+$ cmake \
+    -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake \
+    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
+    -DCODE_COVERAGE=ON \
+    -DCMAKE_BUILD_TYPE=Debug ..
+```
+
+### LSP (language server) support
+
+LSP looks for compile commands in the root of the source tree;
+while Cmake creates them in the root of its build directory.
+
+```
+$ cd xo-pywebsock
+$ ln -s build/compile_commands.json  # supply compile commands to LSP
+```
+
+### display cmake variables
+
+- `-L` list variables
+- `-A` include 'advanced' variables
+- `-H` include help text
+
+```
+$ cd xo-pywebsock/build
+$ cmake -LAH
+```
diff --git a/cmake/xo-bootstrap-macros.cmake b/cmake/xo-bootstrap-macros.cmake
new file mode 100644
index 00000000..16644435
--- /dev/null
+++ b/cmake/xo-bootstrap-macros.cmake
@@ -0,0 +1,12 @@
+if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL "prefix"))
+    # default to typical install location for xo-project-macros
+    set(CMAKE_MODULE_PATH ${CMAKE_INSTALL_PREFIX}/share/cmake)
+endif()
+
+message("-- CMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX}")
+message("-- CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
+
+# needs to have been installed somewhere on CMAKE_MODULE_PATH,
+# (e.g. from xo-cmake with the same value for CMAKE_INSTALL_PREFIX)
+#
+include(xo_macros/xo-project-macros)
diff --git a/src/pywebsock/CMakeLists.txt b/src/pywebsock/CMakeLists.txt
index 57c5d75a..1e40a064 100644
--- a/src/pywebsock/CMakeLists.txt
+++ b/src/pywebsock/CMakeLists.txt
@@ -1,6 +1,6 @@
 # xo_pywebsock/src/pywebsock/CMakeLists.txt
 
-set(SELF_LIB pywebsock)
+set(SELF_LIB xo_pywebsock)
 set(SELF_SRCS pywebsock.cpp)
 
 xo_pybind11_library(${SELF_LIB} ${PROJECT_NAME}Targets ${SELF_SRCS})