commit f25389cda2da75ba225d1a663d30dea9660af31b
Author: Roland Conybeare <rconybeare@gmail.com>
Date:   Sat Oct 7 00:02:05 2023 -0400

    initial commit

diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 0000000..ea3f423
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,67 @@
+# pyutil/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project(xo_pyutil VERSION 0.1)
+enable_language(CXX)
+
+# common XO cmake macros (see github:Rconybea/xo-cmake)
+include(xo_macros/xo_cxx)
+#include(xo_macros/code-coverage)   # very little to unit test here
+
+# ----------------------------------------------------------------
+# unit test setup
+
+#enable_testing()
+## enable code coverage for all executables+libraries
+## (when configured with -DCODE_COVERAGE=ON)
+##
+#add_code_coverage()
+#add_code_coverage_all_targets(
+#  EXCLUDE
+#  /nix/store/*
+#  ${PROJECT_SOURCE_DIR}/utest/*)
+
+# ----------------------------------------------------------------
+# bespoke (usually temporary) c++ settings
+
+set(PROJECT_CXX_FLAGS "")
+#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+# c++ settings
+
+xo_toplevel_compile_options()
+
+# ----------------------------------------------------------------
+# external dependencies
+#
+# set CMAKE_INSTALL_PREFIX to analog of /usr
+# to use .cmake assistants from /usr/lib/cmake/indentlog
+#
+# xo_dependency(..)
+
+# ----------------------------------------------------------------
+
+#add_subdirectory(example)
+#add_subdirectory(utest)
+
+# ----------------------------------------------------------------
+# output targets
+
+set(SELF_LIB xo_pyutil)
+add_library(${SELF_LIB} INTERFACE)
+xo_include_headeronly_options2(${SELF_LIB})
+
+# ----------------------------------------------------------------
+# standard install + provide find_package() support
+
+xo_install_library2(${SELF_LIB})
+xo_install_include_tree()
+xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
+
+# ----------------------------------------------------------------
+# install any additional components
+
+#install(TARGETS ex1 DESTINATION bin/${PROJECT_NAME}/example)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d9bbae3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,13 @@
+# pybind11 utilities for XO projects
+
+# to build + install locally
+
+```
+$ cd xo-pyutil
+$ mkdir build
+$ cd build
+$ PREFIX=/usr/local # for example
+$ cmake -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=$(PREFIX) -DCMAKE_INSTALL_PREFIX=${PREFIX} ..
+$ make
+$ make install
+```
diff --git a/cmake/xo_pyutilConfig.cmake.in b/cmake/xo_pyutilConfig.cmake.in
new file mode 100644
index 0000000..9c15f36
--- /dev/null
+++ b/cmake/xo_pyutilConfig.cmake.in
@@ -0,0 +1,4 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
+check_required_components("@PROJECT_NAME@")
diff --git a/include/xo/pyutil/pyutil.hpp b/include/xo/pyutil/pyutil.hpp
new file mode 100644
index 0000000..a450f5d
--- /dev/null
+++ b/include/xo/pyutil/pyutil.hpp
@@ -0,0 +1,30 @@
+/* @file pyutil.hpp
+ *
+ * utility stuff to be used across multiple pybind11 .cpp files
+ */
+
+#pragma once
+
+#include "xo/refcnt/Refcounted.hpp"
+#include "xo/refcnt/Unowned.hpp"
+#include <pybind11/pybind11.h>
+
+/* xo::ref::intrusive_ptr<T> is an intrusively-reference-counted pointer.
+ * always safe to create one from a T* p
+ * (since refcount is directly accessible from p)
+ *
+ * Need declaration like this before any pybind11 bindings
+ * that expose an object of types like
+ * (a) intrusive_ptr<T> or
+ * (b) T * / T const * / T & / T const & to python.
+ * If this were not done,  pybind11 would by default use unique_ptr<intrusive_ptr<T>>
+ * (ok but inefficient) or unique_ptr<T> (fatal!)
+ */
+PYBIND11_DECLARE_HOLDER_TYPE(T, xo::ref::intrusive_ptr<T>, true);
+
+/* xo::ref::unowned_ptr<T> is an unmanaged pointer.
+ * use this for immortal objects that pybind11 must not delete.
+ */
+PYBIND11_DECLARE_HOLDER_TYPE(T, xo::ref::unowned_ptr<T>, true);
+
+/* end pyutil.hpp */