xo-alloc: + gc history xo-imgui: gui examples

CMakeLists.txt

@@ -116,6 +116,7 @@ add_subdirectory(xo-reader)
 add_subdirectory(xo-jit)
 add_subdirectory(xo-pyjit)
 #
+add_subdirectory(xo-imgui)
 
 # ----------------------------------------------------------------
 # documentation.  must follow add_subdirectory() for satellite projects

xo-alloc/include/xo/alloc/ArenaAlloc.hpp

@@ -36,9 +36,24 @@ namespace xo {
                                        std::size_t z,
                                        bool debug_flag);
 
+            /** size of virtual address range reserved for this allocator **/
+            std::size_t reserved() const { return this->size(); }
+
+            std::size_t page_size() const { return page_z_; }
             std::byte * free_ptr() const { return free_ptr_; }
             void       set_free_ptr(std::byte * x);
 
+            /** if address @p x is allocated from this arena,
+             *  return true along with offset relative to base address @ref lo_
+             *  otherwise return false with 0
+             **/
+            std::pair<bool, std::size_t> location_of(const void * x) const;
+
+            /** allocated span **/
+            std::pair<const std::byte *, const std::byte *> allocated_span() const {
+                return std::make_pair(lo_, free_ptr_);
+            }
+
             /** Reset to empty state **/
             void reset(std::size_t /*z_ignored*/) { this->clear(); }
 

xo-alloc/include/xo/alloc/GC.hpp

@@ -50,6 +50,8 @@ namespace xo {
             bool allow_incremental_gc_ = true;
             /** true to report statistics **/
             bool stats_flag_ = false;
+            /** remember basic gc statistics for this many GC's; separately for incremental + full GCs **/
+            std::size_t stats_history_z_ = 256;
             /** true to enable debug logging **/
             bool debug_flag_ = false;
         };
@@ -147,17 +149,24 @@ namespace xo {
             const GCRunstate & runstate() const { return runstate_; }
             const GcStatistics & native_gc_statistics() const { return gc_statistics_; }
             GcStatisticsExt get_gc_statistics() const;
+            const GcStatisticsHistory & gc_history() const { return gc_history_; }
 
             /** true iff GC permitted in current state **/
             bool is_gc_enabled() const { return gc_enabled_ == 0; }
             /** true during (and only during) a GC cycle **/
             bool gc_in_progress() const { return runstate_.in_progress(); }
+            /** @return reserved size of Nursery to-space **/
+            std::size_t nursery_to_reserved() const;
             /** @return committed size of Nursery to-space **/
             std::size_t nursery_to_committed() const;
             /** @return nursery bytes used before checkpoint **/
             std::size_t nursery_before_checkpoint() const;
             /** @return nursery bytes used after checkpoint **/
             std::size_t nursery_after_checkpoint() const;
+            /** @return allocated memory range for nursery **/
+            std::pair<const std::byte *, const std::byte *> nursery_span(role role) const;
+            /** @return reserved size of Tenured to-space **/
+            std::size_t tenured_to_reserved() const;
             /** @return committed size of Tenured to-space **/
             std::size_t tenured_to_committed() const;
             /** @return tenured bytes used before checkpoint **/
@@ -167,8 +176,24 @@ namespace xo {
 
             /** @return generation to which object at @p x belongs **/
             generation_result tospace_generation_of(const void * x) const;
+            /** @return generation to which object at @p x belongs,
+             *          location relative to base address for that generation,
+             *          and allocated size of that generation
+             *          @p role chooses between to-space and from-space
+             **/
+            std::tuple<generation_result, std::size_t, std::size_t> location_of(role role, const void * x) const;
+            /** @return generation to which object at @p x belongs,
+             *          location relative to base address for @p x,
+             *          and allocated size of generation
+             **/
+            std::tuple<generation_result,std::size_t,std::size_t> tospace_location_of(const void * x) const;
             /** @return generation that contains @p x, given it's in from-space **/
             generation_result fromspace_generation_of(const void * x) const;
+            /** @return generation to which object at @p x belongs,
+             *          location relative to base address for @p x,
+             *          and allocated size of generation
+             **/
+            std::tuple<generation_result,std::size_t,std::size_t> fromspace_location_of(const void * x) const;
             /** true iff from-space contains @p x **/
             bool fromspace_contains(const void * x) const;
             /** @return free pointer for generation @p gen, i.e. nursery or tenured space **/
@@ -361,6 +386,9 @@ namespace xo {
             /** enabled when 0.  disabled when <0 **/
             int gc_enabled_ = 0;
 
+            /** rotating per-gc statistics history **/
+            GcStatisticsHistory gc_history_;
+
             /** for (optional) viz: invoke when copying individual objects **/
             GcCopyCallbackSet gc_copy_cbset_;
         };

xo-alloc/include/xo/alloc/GcStatistics.hpp

@@ -6,6 +6,7 @@
 #pragma once
 
 #include "generation.hpp"
+#include "CircularBuffer.hpp"
 #include "xo/reflect/TypeDescr.hpp"
 #include "xo/indentlog/print/pretty.hpp"
 #include <ostream>
@@ -57,6 +58,8 @@ namespace xo {
          **/
         class GcStatistics {
         public:
+            GcStatistics() = default;
+
             /** update statistics after a GC cycle
              *  @param upto.      nursery -> incremental collection; tenured -> full collection
              *  @param alloc_z.   new allocations (since preceding GC)
@@ -108,6 +111,7 @@ namespace xo {
          **/
         class GcStatisticsExt : public GcStatistics {
         public:
+            GcStatisticsExt() = default;
             explicit GcStatisticsExt(const GcStatistics & x) : GcStatistics{x} {}
 
             /** @param os. write stats on this output stream **/
@@ -128,6 +132,63 @@ namespace xo {
             return os;
         }
 
+        /** @class GcStatisticsHistoryItem
+         *  @brief info we want to record over time (won't have cumulative things in it)
+         **/
+        class GcStatisticsHistoryItem {
+        public:
+            GcStatisticsHistoryItem() = default;
+            GcStatisticsHistoryItem(generation upto,
+                                    std::size_t new_alloc_z,
+                                    std::size_t survive_z,
+                                    std::size_t promote_z,
+                                    std::size_t persist_z,
+                                    std::size_t effort_z,
+                                    std::size_t garbage0_z,
+                                    std::size_t garbage1_z,
+                                    std::size_t garbageN_z)
+                : upto_{upto},
+                  new_alloc_z_{new_alloc_z},
+                  survive_z_{survive_z},
+                  promote_z_{promote_z},
+                  persist_z_{persist_z},
+                  effort_z_{effort_z},
+                  garbage0_z_{garbage0_z},
+                  garbage1_z_{garbage1_z},
+                  garbageN_z_{garbageN_z}
+                {}
+
+            /** @param os. write stats on this output stream **/
+            void display(std::ostream & os) const;
+
+            /** type of GC that generated this record **/
+            generation upto_;
+            /** #of bytes new allocation **/
+            std::size_t new_alloc_z_ = 0;
+            /** #of bytes surviving their first collection (i.e. N0->N1) **/
+            std::size_t survive_z_ = 0;
+            /** #of bytes promoted to tenured.
+             *  Comprises all objects surviving their 2nd collection (i.e. N1->T)
+             **/
+            std::size_t promote_z_ = 0;
+            /** #of bytes surviving 3rd of later collection **/
+            std::size_t persist_z_ = 0;
+            /** #of bytes copied **/
+            std::size_t effort_z_ = 0;
+            /** #of bytes garbage from N0 (i.e. survived 0 GCs) **/
+            std::size_t garbage0_z_ = 0;
+            /** #of bytes garbage from N1 (i.e. survived 1 GCs) **/
+            std::size_t garbage1_z_ = 0;
+            /** #of bytes garbage from T (i.e. survived 2+ GCs) **/
+            std::size_t garbageN_z_ = 0;
+        };
+
+        inline std::ostream & operator<< (std::ostream & os, const GcStatisticsHistoryItem & x) {
+            x.display(os);
+            return os;
+        }
+
+        using GcStatisticsHistory = CircularBuffer<GcStatisticsHistoryItem>;
     } /*namespace gc*/
 
     namespace print {
@@ -145,6 +206,11 @@ namespace xo {
         struct ppdetail<xo::gc::GcStatisticsExt> {
             static bool print_pretty(const ppindentinfo &, const xo::gc::GcStatisticsExt &);
         };
+
+        template<>
+        struct ppdetail<xo::gc::GcStatisticsHistoryItem> {
+            static bool print_pretty(const ppindentinfo &, const xo::gc::GcStatisticsHistoryItem &);
+        };
     } /*namespace print*/
 } /*namespace xo*/
 

xo-alloc/include/xo/alloc/ListAlloc.hpp

@@ -34,6 +34,9 @@ namespace xo {
 
             static up<ListAlloc> make(const std::string & name, std::size_t cz, std::size_t nz, bool debug_flag);
 
+            /** page size used by underlying ArenaAlloc **/
+            std::size_t page_size() const;
+
             /** reset to have at least @p z bytes of storage **/
             bool reset(std::size_t z);
 

xo-alloc/include/xo/alloc/generation.hpp

@@ -30,6 +30,7 @@ namespace xo {
             tenured,
             not_found
         };
+
     } /*namespace gc*/
 } /*namespace xo*/
 

xo-alloc/src/alloc/ArenaAlloc.cpp

@@ -113,6 +113,7 @@ namespace xo {
             }
 
             this->committed_z_ = align_offset_z;
+            this->limit_ = this->lo_ + committed_z_;
 
             return true;
         }
@@ -133,6 +134,16 @@ namespace xo {
             }
         }
 
+        std::pair<bool, std::size_t>
+        ArenaAlloc::location_of(const void * x) const
+        {
+            if ((lo_ <= x) && (x < hi_)) {
+                return std::make_pair(true, reinterpret_cast<const std::byte *>(x) - lo_);
+            } else {
+                return std::make_pair(false, 0);
+            }
+        }
+
         void
         ArenaAlloc::capture_object_statistics(capture_phase phase,
                                               ObjectStatistics * p_dest) const
@@ -276,6 +287,7 @@ namespace xo {
                        xtag("z0", z0),
                        xtag("+pad", dz),
                        xtag("z1", z1),
+                       xtag("size", this->size()),
                        xtag("avail", this->available()));
 
             this->free_ptr_ += z1;

xo-alloc/src/alloc/GC.cpp

@@ -79,6 +79,8 @@ namespace xo {
             mutation_log_[role2int(role::to_space)] = std::make_unique<MutationLog>();
             defer_mutation_log_ = std::make_unique<MutationLog>();
 
+            this->gc_history_ = CircularBuffer<GcStatisticsHistoryItem>(config.stats_history_z_);
+
             this->checkpoint();
         }
 
@@ -191,6 +193,12 @@ namespace xo {
             return retval;
         }
 
+        std::size_t
+        GC::nursery_to_reserved() const
+        {
+            return nursery_to()->reserved();
+        }
+
         std::size_t
         GC::nursery_to_committed() const
         {
@@ -209,6 +217,17 @@ namespace xo {
             return nursery_to()->after_checkpoint();
         }
 
+        std::pair<const std::byte *, const std::byte *>
+        GC::nursery_span(role role) const {
+            return nursery(role)->allocated_span();
+        }
+
+        std::size_t
+        GC::tenured_to_reserved() const
+        {
+            return tenured_to()->reserved();
+        }
+
         std::size_t
         GC::tenured_to_committed() const
         {
@@ -239,6 +258,40 @@ namespace xo {
             return generation_result::not_found;
         }
 
+        std::tuple<generation_result, std::size_t, std::size_t>
+        GC::location_of(role role, const void *x) const
+        {
+            {
+                auto space = this->tenured(role);
+                auto [is_tenured, offset] = space->location_of(x);
+
+                if (is_tenured)
+                    return std::make_tuple(generation_result::tenured, offset, space->allocated());
+            }
+
+            {
+                auto space = this->nursery(role);
+                auto [is_nursery, offset] = nursery(role)->location_of(x);
+
+                if (is_nursery)
+                    return std::make_tuple(generation_result::nursery, offset, space->allocated());
+            }
+
+            return std::make_tuple(generation_result::not_found, 0, 0);
+        }
+
+        std::tuple<generation_result, std::size_t, std::size_t>
+        GC::tospace_location_of(const void * x) const
+        {
+            return location_of(role::to_space, x);
+        }
+
+        std::tuple<generation_result, std::size_t, std::size_t>
+        GC::fromspace_location_of(const void * x) const
+        {
+            return location_of(role::from_space, x);
+        }
+
         generation_result
         GC::fromspace_generation_of(const void * x) const
         {
@@ -988,8 +1041,11 @@ namespace xo {
         {
             scope log(XO_DEBUG(config_.debug_flag_));
 
-            std::size_t N_allocated = nursery_from()->after_checkpoint();
+            std::size_t N0_before_gc = nursery_from()->after_checkpoint();
-            std::size_t T_allocated = tenured_from()->after_checkpoint();
+            std::size_t N1_before_gc = nursery_from()->before_checkpoint();
+
+            std::size_t T0_before_gc = tenured_from()->after_checkpoint();
+            std::size_t T1_before_gc = tenured_from()->before_checkpoint();
 
             std::size_t N_before_gc = nursery_from()->allocated();
             std::size_t T_before_gc = tenured_from()->allocated();
@@ -998,9 +1054,37 @@ namespace xo {
             std::size_t T_after_gc = tenured_to()->allocated();
             //std::byte * N_free_ptr = nursery_[role2int(role::to_space)]->free_ptr();
 
+            std::size_t new_alloc_z = N0_before_gc;
+            /* survive_z: bytes surviving first collection */
+            std::size_t survive_z = N_after_gc;
+            /* promote_z: bytes surviving 2nd collection */
             std::size_t promote_z = (gc_statistics_.total_promoted_
                                      - gc_statistics_.total_promoted_sab_);
 
+            /* #of bytes copied by this collection cycle */
+            std::size_t effort_z = 0;
+            if (upto == generation::nursery) {
+                effort_z = N_after_gc + promote_z;
+            } else {
+                effort_z += N_after_gc + T_after_gc;
+            }
+
+            /* persist_z: bytes surviving 3rd or later collection */
+            std::size_t persist_z = 0;
+            if (upto == generation::tenured)
+                persist_z = T_after_gc - promote_z;
+            /* #of bytes found to be garbage on first collection
+             * (reminder: N_after_gc consists *entirely* of survives from N0_before_gc;
+             *            + all such survivors are in N_after_gc)
+             */
+            std::size_t garbage0_z = (N0_before_gc - N_after_gc);
+            /* #of bytes found to be garbage on 2nd collection */
+            std::size_t garbage1_z = (N1_before_gc - promote_z);
+            /* #of bytes found to be garbage on 3rd or later collection */
+            std::size_t garbageN_z = 0;
+            if (upto == generation::tenured)
+                garbageN_z = (T_before_gc - T_after_gc + promote_z);
+
             /* Don't reset from-space here, it's unnecessary.
              * Would be permissible, but interferes with GC object modelling in
              * xo-object/utest/GC.test.cpp
@@ -1014,25 +1098,38 @@ namespace xo {
                 this->tenured_to()->checkpoint();
 
             if (log) {
-                log(xtag("N_allocated", N_allocated));
+                log(xtag("N0_before_gc", N0_before_gc));
-                log(xtag("N_before_gc", N_before_gc));
+                log(xtag("N1_before_gc", N1_before_gc));
                 log(xtag("N_after_gc", N_after_gc));
-                log(xtag("T_allocated", T_allocated));
+
-                log(xtag("T_before_gc", T_before_gc));
+                log(xtag("T0_before_gc", T0_before_gc));
+                log(xtag("T1_before_gc", T1_before_gc));
                 log(xtag("T_after_gc", T_after_gc));
             }
 
+            GcStatisticsHistoryItem item(upto,
+                                         new_alloc_z,
+                                         survive_z,
+                                         promote_z,
+                                         persist_z,
+                                         effort_z,
+                                         garbage0_z,
+                                         garbage1_z,
+                                         garbageN_z);
+
+            this->gc_history_.push_back(item);
+
             this->incr_gc_pending_ = false;
-            this->gc_statistics_.include_gc(generation::nursery, N_allocated, N_before_gc, N_after_gc, promote_z);
+            this->gc_statistics_.include_gc(generation::nursery, N0_before_gc, N_before_gc, N_after_gc, promote_z);
 
             if (upto == generation::tenured) {
                 this->full_gc_pending_ = false;
-                this->gc_statistics_.include_gc(generation::tenured, T_allocated, T_before_gc, T_after_gc, 0);
+                this->gc_statistics_.include_gc(generation::tenured, T0_before_gc, T_before_gc, T_after_gc, 0);
             } else {
                 // still want to update tenured stats for current alloc size
                 this->gc_statistics_.update_snapshot(generation::tenured, T_after_gc);
             }
-        }
+        } /*cleanup_phase*/
 
         void
         GC::execute_gc(generation upto)
@@ -1090,6 +1187,9 @@ namespace xo {
 
             this->runstate_ = GCRunstate();
 
+            // not this way.. reports cumulative stats
+            //   this->gc_history_.push_back(this->get_gc_statistics());
+
             log && log("statistics:");
             log && log(gc_statistics_);
         }

xo-alloc/src/alloc/GcStatistics.cpp

@@ -92,6 +92,22 @@ namespace xo {
                 // << xtag("per_type_stats", per_type_stats_)
                << ">";
         }
+
+        void
+        GcStatisticsHistoryItem::display(std::ostream & os) const
+        {
+            os << "<GcStatisticsHistoryItem"
+               << xrtag("upto", upto_)
+               << xrtag("survive_z", survive_z_)
+               << xrtag("promote_z", promote_z_)
+               << xrtag("persist_z", persist_z_)
+               << xrtag("effort_z", effort_z_)
+               << xrtag("garbage0_z", garbage0_z_)
+               << xrtag("garbage1_z", garbage1_z_)
+               << xrtag("garbageN_z", garbageN_z_)
+               << ">";
+        }
+
     } /*namespace gc*/
 
     namespace print {
@@ -148,7 +164,21 @@ namespace xo {
                                              refrtag("tenured_z", x.tenured_z_));
         }
 
-
+        bool
+        ppdetail<xo::gc::GcStatisticsHistoryItem>::print_pretty(const ppindentinfo & ppii,
+                                                                const xo::gc::GcStatisticsHistoryItem & x)
+        {
+            return ppii.pps()->pretty_struct(ppii,
+                                             "GcStatisticsHistoryItem",
+                                             refrtag("upto", gen2str(x.upto_)),
+                                             refrtag("survive_z", x.survive_z_),
+                                             refrtag("promote_z", x.promote_z_),
+                                             refrtag("persist_z", x.persist_z_),
+                                             refrtag("effort_z", x.effort_z_),
+                                             refrtag("garbage0_z", x.garbage0_z_),
+                                             refrtag("garbage1_z", x.garbage1_z_),
+                                             refrtag("garbageN_z", x.garbageN_z_));
+        }
     } /*namespace print*/
 } /*namespace xo*/
 

xo-alloc/src/alloc/ListAlloc.cpp

@@ -70,6 +70,11 @@ namespace xo {
             return s_default_name;
         }
 
+        std::size_t
+        ListAlloc::page_size() const {
+            return hd_->page_size();
+        }
+
         std::size_t
         ListAlloc::size() const {
             return total_z_;
@@ -109,8 +114,9 @@ namespace xo {
         ListAlloc::allocated() const {
             std::size_t total = 0;
 
-            if (hd_)
+            if (hd_) {
                 total += hd_->allocated();
+            }
 
             for (const auto & alloc : full_l_)
                 total += alloc->allocated();
@@ -363,10 +369,17 @@ namespace xo {
         ListAlloc::alloc(std::size_t z) {
             scope log(XO_DEBUG(debug_flag_));
 
+            /* ArenaAlloc::alloc() may modify its own size */
+
+            std::size_t z_pre = hd_->size();
             std::byte * retval = hd_->alloc(z);
 
-            if (retval)
+            if (retval) {
+                std::size_t z_post = hd_->size();
+                this->total_z_ += (z_post - z_pre);
+
                 return retval;
+            }
 
             log && log("space exhausted -> expand");
 

xo-alloc/utest/CMakeLists.txt

@@ -12,6 +12,7 @@ set(UTEST_SRCS
     GcStatistics.test.cpp
     ObjectStatistics.test.cpp
     Forwarding1.test.cpp
+    CircularBuffer.test.cpp
     generation.test.cpp
 )
 

xo-alloc/utest/GcStatistics.test.cpp

@@ -76,7 +76,7 @@ namespace xo {
 
             tag_config::tag_color_enabled = false;
 
-            GcStatisticsExt stats({});
+            GcStatisticsExt stats;
 
             std::string s = tostr(stats);
 
@@ -154,7 +154,7 @@ namespace xo {
 
             std::stringstream ss;
             ppconfig ppc;
-            GcStatisticsExt stats({});
+            GcStatisticsExt stats;
 
             std::string actual = toppstr2(ppc, stats);
             std::string expected

xo-alloc/utest/ListAlloc.test.cpp

@@ -12,7 +12,10 @@ namespace xo {
     namespace ut {
         TEST_CASE("ListAlloc", "[alloc][gc]")
         {
-            /** teeny weeny allocator **/
+            /** teeny weeny allocator.
+             *  but underlying ArenaAlloc works in multiples of VM page size
+             *  (most likely 4k)
+             **/
             up<ListAlloc> alloc = ListAlloc::make("test", 16, 32, false);
 
             REQUIRE(alloc->name() == "test");
@@ -24,7 +27,7 @@ namespace xo {
             std::byte * mem1 = alloc->alloc(20);
 
             REQUIRE(mem1);
-            REQUIRE(alloc->size() == 16 + 32);
+            REQUIRE(alloc->size() == alloc->page_size());
             /* round up to multiple of 8 */
             REQUIRE(alloc->before_checkpoint() == 24);
             REQUIRE(alloc->after_checkpoint() == 0);
@@ -34,7 +37,7 @@ namespace xo {
             std::byte * mem2 = alloc->alloc(30);
 
             REQUIRE(mem2);
-            REQUIRE(alloc->size() == 16 + 32 + 48);
+            REQUIRE(alloc->size() == alloc->page_size());
             REQUIRE(alloc->before_checkpoint() == 24);
             /* round up to multiple of 8 */
             REQUIRE(alloc->after_checkpoint() == 32);
@@ -42,7 +45,7 @@ namespace xo {
             std::byte * mem3 = alloc->alloc(40);
 
             REQUIRE(mem3);
-            REQUIRE(alloc->size() == 16 + 32 + 48 + 80);
+            REQUIRE(alloc->size() == alloc->page_size());
             REQUIRE(alloc->before_checkpoint() == 24);
             /* already multiple of 8 */
             REQUIRE(alloc->after_checkpoint() == 32 + 40);

xo-imgui/CMakeLists.txt

@@ -0,0 +1,36 @@
+# xo-imgui/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project(xo_imgui VERSION 0.1)
+
+include(GNUInstallDirs)
+include(cmake/xo-bootstrap-macros.cmake)
+
+xo_cxx_toplevel_options3()
+
+# ----------------------------------------------------------------
+# c++ settings
+
+set(PROJECT_CXX_FLAGS "")
+#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")  # gcc-only!
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+
+add_subdirectory(example)
+# add_subdirectory(utest)
+
+# set(SELF_LIB. ..)
+# xo_install_library4(${SELF_LIB} ...)
+# xo_export_cmake_config(${PROJECT_NAME} ...)
+
+if (XO_ENABLE_EXAMPLES)
+    install(TARGETS imgui_ex1 DESTINATION bin/imgui/example)
+endif()
+
+# ----------------------------------------------------------------
+# docs targets depends on other library/utest/exec targets,
+# must come after them
+#
+#add_subdirectory(docs)

xo-imgui/cmake/xo-bootstrap-macros.cmake

@@ -0,0 +1,35 @@
+# ----------------------------------------------------------------
+# for example:
+#   $ PREFIX=/usr/local   # for example
+#   $ cmake -DCMAKE_MODULE_PATH=prefix -DCMAKE_INSTALL_PREFIX=$PREFIX -B .build
+#
+# will get
+#   CMAKE_MODULE_PATH
+# from xo-cmake-config --cmake-module-path
+#
+# and expect .cmake macros in
+#   CMAKE_MODULE_PATH/xo_macros/xo_cxx.cmake
+# ----------------------------------------------------------------
+
+find_program(XO_CMAKE_CONFIG_EXECUTABLE NAMES xo-cmake-config REQUIRED)
+
+if ("${XO_CMAKE_CONFIG_EXECUTABLE}" STREQUAL "XO_CMAKE_CONFIG_EXECUTABLE-NOT_FOUND")
+    message(FATAL "could not find xo-cmake-config executable")
+endif()
+
+message(STATUS "XO_CMAKE_CONFIG_EXECUTABLE=${XO_CMAKE_CONFIG_EXECUTABLE}")
+
+if (NOT XO_SUBMODULE_BUILD)
+    if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL prefix))
+        # default to typical install location for xo-project-macros
+        execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --cmake-module-path OUTPUT_VARIABLE CMAKE_MODULE_PATH)
+        message(STATUS "CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
+    endif()
+endif()
+
+# 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_cxx)
+
+xo_cxx_bootstrap_message()

xo-imgui/example/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_subdirectory(ex1)
+add_subdirectory(ex2)

xo-imgui/example/ex1/CMakeLists.txt

@@ -0,0 +1,66 @@
+if (XO_ENABLE_EXAMPLES)
+    # imgui dependency
+
+    find_path(IMGUI_INCLUDE_DIR
+        NAMES imgui/imgui.h
+        DOC "path to imgui header"
+    )
+    if (IMGUI_INCLUDE_DIR)
+        message(STATUS "found imgui/imgui.h in IMGUI_INCLUDE_DIR=[${IMGUI_INCLUDE_DIR}]")
+    else()
+        message(FATAL_ERROR "unable to find imgui.h")
+    endif()
+
+    # target executable
+
+    set(SELF_EXE imgui_ex1)
+    add_executable(${SELF_EXE} imgui_ex1.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_demo.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_draw.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_widgets.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_tables.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/backends/imgui_impl_sdl2.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/backends/imgui_impl_opengl3.cpp
+    )
+    xo_include_options2(${SELF_EXE})
+
+    # OpenGL dependency
+
+    # have to choose between
+    #   libGL.so
+    # or
+    #   libOpenGL.so + libGLX.so    # GLVND = OpenGL Vendor Neutral Dispatch (e.g. mesa|nvda)
+    #
+    # expect in .build/CMakeCache.txt:
+    #   OPENGL_opengl_LIBRARY:FILEPATH=/path/to/libOpenGL.so
+    #   OpenGL_DIR:PATH=OpenGL_DIR-NOTFOUND  # no cmake config file
+
+    set(OpenGL_GL_PREFERENCE GLVND)  # or LEGACY
+    find_package(OpenGL REQUIRED)  # find_package(OpenGL CONFIG REQUIRE) won't work
+
+    target_link_libraries(${SELF_EXE} PUBLIC OpenGL::GL)
+#    target_link_libraries(${SELF_EXE} PUBLIC ${OPENGL_opengl_LIBRARY})
+#    target_include_directories(${SELF_EXE} PUBLIC OpenGL_INCLUDE_DIRS)
+    #target_compile_options(${SELF_EXE} PUBLIC OpenGL_CFLAGS_OTHER)
+    #xo_external_dependency(${SELF_EXE} OpenGL)
+
+    # GLEW dependency
+
+    xo_external_pkgconfig_dependency(${SELF_EXE} GLEW glew)
+
+    # GLFW dependency
+
+#    find_package(glfw3 CONFIG REQUIRED)
+#    target_link_libraries(${SELF_EXE} PUBLIC glfw) # want -lglfw
+
+    # SDL2 dependency
+
+    xo_external_pkgconfig_dependency(${SELF_EXE} SDL2 sdl2)
+
+    # would prefer to use jsut IMGUI_INCLUD_DIR,
+    # but imgui/backends/ .h files don't quote the imgui/ stem
+    #
+    target_include_directories(${SELF_EXE} PUBLIC ${IMGUI_INCLUDE_DIR}/imgui)
+
+endif()

xo-imgui/example/ex1/imgui_ex1.cpp

@@ -0,0 +1,329 @@
+/* xo-imgui/example/ex1/imgui_ex1.cpp
+ *
+ * author: Roland Conybeare, Aug 2025
+ */
+
+#include <SDL.h>
+#include <GL/glew.h>
+
+#include "SDL_events.h"
+#include "imgui.h"
+#include "backends/imgui_impl_sdl2.h"
+#include "backends/imgui_impl_opengl3.h"
+
+//#include <GLFW/glfw3.h>
+
+#ifdef NOPE
+#include <SDL_opengl.h>
+#endif
+
+#include <iostream>
+#include <unistd.h>
+
+int main(int, char **)
+{
+    using namespace std;
+
+    std::cout << "Hello, world!" << std::endl;
+
+    SDL_SetHint(SDL_HINT_VIDEO_X11_FORCE_EGL, "0");
+
+    SDL_Init(SDL_INIT_VIDEO);
+
+    SDL_version compiled;
+    SDL_VERSION(&compiled);
+    std::cerr << "SDL version: "
+              << (int)compiled.major
+              << "." << (int)compiled.minor
+              << "." << (int)compiled.patch
+              << std::endl;
+
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 0);
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK,
+                        SDL_GL_CONTEXT_PROFILE_CORE);
+    SDL_GL_SetAttribute(SDL_GL_DOUBLEBUFFER, 1);
+
+#if 0
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS,
+                        SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG);
+#endif
+
+    std::cerr << "SDL video driver: " << SDL_GetCurrentVideoDriver() << std::endl;
+
+    SDL_Window * window = SDL_CreateWindow("imgui + sdl2 + opengl",
+                                           SDL_WINDOWPOS_CENTERED,
+                                           SDL_WINDOWPOS_CENTERED,
+                                           1280,
+                                           720,
+                                           SDL_WINDOW_OPENGL | SDL_WINDOW_RESIZABLE | SDL_WINDOW_ALLOW_HIGHDPI);
+    if (window) {
+        std::cerr << "SDL_CreateWindow done" << std::endl;
+    } else {
+        std::cerr << "SDL_CreateWindow failed: [" << SDL_GetError() << "]" << std::endl;
+        SDL_Quit();
+        return -1;
+    }
+
+    SDL_GLContext gl_context = SDL_GL_CreateContext(window);
+
+    int major, minor;
+    SDL_GL_GetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, &major);
+    SDL_GL_GetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, &minor);
+
+    std::cerr << "Requested OpenGL version: " << major << "." << minor << std::endl;
+
+    if (gl_context) {
+        std::cerr << "SDL_GL_CreateContext done" << std::endl;
+    } else {
+        std::cerr << "SDL_GL_CreateContext failed: [" << SDL_GetError() << "]" << std::endl;
+        return -1;
+    }
+
+    if (SDL_GL_MakeCurrent(window, gl_context) != 0) {
+        std::cerr << "SDL_GL_MakeCurrent failed: [" << SDL_GetError() << "]" << std::endl;
+        SDL_GL_DeleteContext(gl_context);
+        SDL_DestroyWindow(window);
+        SDL_Quit();
+        return -1;
+    }
+
+    SDL_GL_SetSwapInterval(1); // enable vsync
+
+    GLenum glew_status = glewInit();
+    if (glew_status == GLEW_OK) {
+        std::cerr << "glewInit done" << std::endl;
+    } else {
+        std::cerr << "glewInit failed: [" << glewGetErrorString(glew_status) << std::endl;
+        return -1;
+    }
+
+    const GLubyte * version = glGetString(GL_VERSION);
+
+    glEnable(GL_BLEND);
+    glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+
+    if (version) {
+        std::cerr << "OpenGL version: [" << version << "]" << std::endl;
+    } else {
+        std::cerr << "OpenGL version not available" << std::endl;
+    }
+
+    IMGUI_CHECKVERSION();
+    ImGui::CreateContext();
+    ImGuiIO & io = ImGui::GetIO(); (void)io;
+    io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard;
+
+    ImGui::StyleColorsDark();
+
+    ImGui_ImplSDL2_InitForOpenGL(window, gl_context);
+    ImGui_ImplOpenGL3_Init("#version 330");
+
+    bool show_demo_window = true;
+    bool show_another_window = false;
+    ImVec4 clear_color = ImVec4(0.45f, 0.55f, 0.60f, 1.00f);
+    float counter_value = 0.0f;
+
+    // Main Loop
+    bool done = false;
+
+    while (!done) {
+        /** poll + handle events */
+        SDL_Event event;
+
+        while (SDL_PollEvent(&event)) {
+            ImGui_ImplSDL2_ProcessEvent(&event);
+            if (event.type == SDL_QUIT)
+                done = true;
+
+            if ((event.type == SDL_WINDOWEVENT)
+                && (event.window.event == SDL_WINDOWEVENT_CLOSE)
+                && (event.window.windowID == SDL_GetWindowID(window)))
+            {
+                done = true;
+            }
+        }
+
+        int w, h;
+        SDL_GetWindowSize(window, &w, &h);
+        glViewport(0, 0, w, h);
+        glClearColor(clear_color.x * clear_color.w,
+                     clear_color.y * clear_color.w,
+                     clear_color.z * clear_color.w,
+                     clear_color.w);
+        glClear(GL_COLOR_BUFFER_BIT);
+
+        // draw dear imgui frame
+        ImGui_ImplOpenGL3_NewFrame();
+        ImGui_ImplSDL2_NewFrame();
+        ImGui::NewFrame();
+
+        ImGui::SetNextWindowPos(ImVec2(0, 0));
+        ImGui::SetNextWindowSize(io.DisplaySize);
+        ImGui::Begin("Background", nullptr,
+                     ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoResize
+                     | ImGuiWindowFlags_NoMove | ImGuiWindowFlags_NoBringToFrontOnFocus
+                     | ImGuiWindowFlags_NoNavFocus | ImGuiWindowFlags_NoDecoration);
+        ImGui::End();
+
+        // 1. big demo window
+        if (show_demo_window)
+            ImGui::ShowDemoWindow(&show_demo_window);
+
+        // 2. show window that we create ourselves
+        {
+            static int counter = 0;
+
+            ImGui::Begin("Hello, world!");
+            ImGui::Text("This is totes useful text...");
+            ImGui::Checkbox("demo window", &show_demo_window);
+            ImGui::Checkbox("second window", &show_another_window);
+
+            ImGui::SliderFloat("float", &counter_value, 0.0f, 1.0f);
+            ImGui::ColorEdit3("clear color", (float*)&clear_color);
+
+            if (ImGui::Button("Button"))
+                ++counter;
+            ImGui::SameLine();
+            ImGui::Text("counter = %d", counter);
+
+            ImGui::Text("appl average %.3f ms/frame (%.1f fps)",
+                        1000.0f / io.Framerate, io.Framerate);
+
+            ImGui::End();
+        }
+
+        // 3. another window
+        if (show_another_window) {
+            ImGui::Begin("another window", &show_another_window);
+
+            ImGui::Text("hello from second window");
+            if (ImGui::Button("close me"))
+                show_another_window = false;
+
+            ImGui::End();
+        }
+
+        // rendering
+        ImGui::Render();
+
+        ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
+
+        SDL_GL_SwapWindow(window);
+    }
+
+    std::cerr << "cleanup.." << std::endl;
+
+    ImGui_ImplOpenGL3_Shutdown();
+    ImGui_ImplSDL2_Shutdown();
+    ImGui::DestroyContext();
+
+    SDL_GL_DeleteContext(gl_context);
+    SDL_DestroyWindow(window);
+    SDL_Quit();
+
+    std::cerr << "All done, goodbye..." << std::endl;
+
+    return 0;
+
+#ifdef NOPE2
+    if (!glfwInit()) {
+        std::cerr << "glfwInit failed!" << std::endl;
+        return -1;
+    }
+
+    std::cout << "GLFW version: " << glfwGetVersionString() << std::endl;
+
+    // configure glfw
+    glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
+    glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
+    // this fails in nix-on-wsl
+    //glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
+    glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_ANY_PROFILE);
+    // maybe:
+    //glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GL_TRUE);
+    // may need explicit hints
+    //glfwWindowHint(GLFW_RED_BITS, 8)
+    //glfwWindowHint(GLFW_GREEN_BITS, 8)
+    //glfwWindowHint(GLFW_BLUE_BITS, 8)
+    //glfwWindowHint(GLFW_ALPHA_BITS, 8)
+    //glfwWindowHint(GLFW_DEPTH_BITS, 24)
+    //glfwWindowHint(GLFW_STENCIL_BITS, 8)
+    //glfwWindowHint(GLFW_DOUBLEBUFFER, GL_TRUE)
+    //
+    // try
+    //   $ glxinfo
+    // to get framebuffer info
+
+    // Not working because:
+    //   eglinfo
+    // looks in
+    //   /run/opengl-driver/share/glvnd/egl_vendor.d
+    //   /etc/glvnd/egl_vendor.d
+    //   /usr/share/glvnd/egl_vendor.d
+    //
+    // these tell EGL which vendor libraries to load (mesa | nvidia)
+
+    // create window
+    GLFWwindow * window = glfwCreateWindow(800, 600, "simple opengl triangle", NULL, NULL);
+
+    if (!window) {
+        // getting error couldn't find framebuffer configuration matching requested
+        // opengl context.  used by GLX (opengl extension to x11).
+        // defines things like: color depth, double buffering, stencil bits etc.
+
+
+        const char * descr = nullptr;
+        int code = glfwGetError(&descr);
+        std::cerr << "glfwCreateWindow failed :code " << code << " :msg "
+                  << (descr ? descr : "?unknown")
+                  << std::endl;
+    }
+#endif
+
+#ifdef NOPE
+
+    if (SDL_Init(SDL_INIT_VIDEO
+                 | SDL_INIT_TIMER
+                 | SDL_INIT_GAMECONTROLLER) != 0)
+    {
+        std::cerr << "SDL_Init failed: " << SDL_GetError() << std::endl;
+        return -1;
+    }
+
+    // OpenGL attributes
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_FLAGS, 0);
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK, SDL_GL_CONTEXT_PROFILE_CORE);
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
+    SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 3);
+
+    // SDL window
+    SDL_Window * window
+        = SDL_CreateWindow("xo imgui ex1",
+                           SDL_WINDOWPOS_CENTERED,
+                           SDL_WINDOWPOS_CENTERED,
+                           800 /*width ?*/,
+                           600 /*height ?*/,
+                           SDL_WINDOW_OPENGL | SDL_WINDOW_RESIZABLE);
+
+    SDL_GLContext gl_context = SDL_GLContext(window);
+    SDL_GL_MakeCurrent(window, gl_context);
+    SDL_GL_SetSwapInterval(1);  // enable vsync.. (wut!?)
+
+    // imgui
+
+    IMGUI_CHECKVERSION();
+    ImGui::CreateContext();
+    ImGuiIO & io = ImGui::GetIO(); (void)io;
+
+    ImGui::StyleColorsDark();
+    ImGui_ImplSDL2_InitForOpenGL(window, gl_context);
+#endif
+
+#ifdef NOPE
+    // this gets: Failed to initialize OpenGL loader!
+    ImGui_ImplOpenGL3_Init("#version 330");
+#endif
+}
+
+/* imgui_ex1.cpp */

xo-imgui/example/ex2/CMakeLists.txt

@@ -0,0 +1,62 @@
+if (XO_ENABLE_EXAMPLES)
+    # imgui dependency
+
+    find_path(IMGUI_INCLUDE_DIR
+        NAMES imgui/imgui.h
+        DOC "path to imgui header"
+    )
+    if (IMGUI_INCLUDE_DIR)
+        message(STATUS "found imgui/imgui.h in IMGUI_INCLUDE_DIR=[${IMGUI_INCLUDE_DIR}]")
+    else()
+        message(FATAL_ERROR "unable to find imgui.h")
+    endif()
+
+    # target executable
+
+    set(SELF_EXE imgui_ex2)
+    add_executable(${SELF_EXE} imgui_ex2.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_demo.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_draw.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_widgets.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/imgui_tables.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/backends/imgui_impl_sdl2.cpp
+        ${IMGUI_INCLUDE_DIR}/imgui/backends/imgui_impl_opengl3.cpp
+    )
+    xo_include_options2(${SELF_EXE})
+
+    # OpenGL dependency
+
+    # have to choose between
+    #   libGL.so
+    # or
+    #   libOpenGL.so + libGLX.so    # GLVND = OpenGL Vendor Neutral Dispatch (e.g. mesa|nvda)
+    #
+    # expect in .build/CMakeCache.txt:
+    #   OPENGL_opengl_LIBRARY:FILEPATH=/path/to/libOpenGL.so
+    #   OpenGL_DIR:PATH=OpenGL_DIR-NOTFOUND  # no cmake config file
+
+    set(OpenGL_GL_PREFERENCE GLVND)  # or LEGACY
+    find_package(OpenGL REQUIRED)  # find_package(OpenGL CONFIG REQUIRE) won't work
+
+    target_link_libraries(${SELF_EXE} PUBLIC OpenGL::GL)
+
+    # GLEW dependency
+    xo_external_pkgconfig_dependency(${SELF_EXE} GLEW glew)
+
+    # GLFW dependency
+#    find_package(glfw3 CONFIG REQUIRED)
+#    target_link_libraries(${SELF_EXE} PUBLIC glfw) # want -lglfw
+
+    # SDL2 dependency
+    xo_external_pkgconfig_dependency(${SELF_EXE} SDL2 sdl2)
+
+    # would prefer to use just IMGUI_INCLUDE_DIR,
+    # but imgui/backends/ .h files don't quote the imgui/ stem
+    #
+    target_include_directories(${SELF_EXE} PUBLIC ${IMGUI_INCLUDE_DIR}/imgui)
+
+    xo_dependency(${SELF_EXE} xo_object)
+    xo_dependency(${SELF_EXE} randomgen)
+    xo_dependency(${SELF_EXE} xo_alloc)
+endif()