feat(text): optional vendored stb_truetype backend for runtime external fonts

cmake/plot_umbrella_check.cmake

@@ -6,6 +6,18 @@
 # */detail/ instrumentation, which is documented as not part of the surface and
 # deliberately stays out of the umbrella.
 #
+# One more class is exempt: a header owned by an *optional* target. Such a target
+# can be switched off (PLOT_BUILD_TTF_FONT), so its header cannot be named by an
+# umbrella every consumer compiles -- that would make plot.hpp unbuildable in a
+# configuration where the target does not exist. The list below holds those
+# headers by exact path, one per target, because an exemption is a hole in this
+# check and a hole should be a list of files rather than a wildcard or a
+# directory prefix: a header that is merely inconvenient cannot slip in behind
+# one. The run names what it exempted, so the hole is visible in the configure
+# log, and the header is still held to standalone compilation like any other
+# (tests/CMakeLists.txt generates a self-containment TU for every globbed header
+# regardless of which targets are on).
+#
 # Runs twice: tests/CMakeLists.txt includes it at configure time (so a header
 # added without its umbrella line stops the configure rather than the run), and
 # ctest runs it again as `plot_umbrella_covers_public_headers` via `cmake -P`.
@@ -15,6 +27,20 @@
 # Inputs (set by the including scope, or passed with -D in script mode):
 #   PLOT_INCLUDE_DIR  the installed-header root, e.g. <source>/include
 #   PLOT_UMBRELLA     the umbrella header, e.g. <PLOT_INCLUDE_DIR>/plot/plot.hpp
+#   PLOT_OPTIONAL_HEADERS  optional-target headers, relative to PLOT_INCLUDE_DIR,
+#                          that the umbrella deliberately does not name. Defaults
+#                          to the list below; a caller may override it, and
+#                          emptying it is how a test proves the exemption is what
+#                          keeps a header out of the "missing" report.
+
+if(NOT DEFINED PLOT_OPTIONAL_HEADERS)
+  set(PLOT_OPTIONAL_HEADERS
+    # plot::text::TrueTypeFont, built only by the PLOT_BUILD_TTF_FONT target
+    # because it is the one thing in the project that reaches the vendored
+    # third_party/stb_truetype.h. That target is off wherever the vendored
+    # header is absent, so the umbrella must not require this one.
+    "plot/text/true_type_font.hpp")
+endif()
 
 if(NOT DEFINED PLOT_INCLUDE_DIR)
   message(FATAL_ERROR "plot: PLOT_INCLUDE_DIR is not set")
@@ -34,10 +60,15 @@ file(RELATIVE_PATH plot_umbrella_relative "${PLOT_INCLUDE_DIR}" "${PLOT_UMBRELLA
 
 # Every other public header is named by the umbrella.
 set(plot_umbrella_missing "")
+set(plot_umbrella_exempt "")
 foreach(header IN LISTS plot_umbrella_headers)
   if(header MATCHES "/detail/" OR header STREQUAL plot_umbrella_relative)
     continue()
   endif()
+  if(header IN_LIST PLOT_OPTIONAL_HEADERS)
+    list(APPEND plot_umbrella_exempt "${header}")
+    continue()
+  endif()
   string(FIND "${plot_umbrella_text}" "#include <${header}>" plot_umbrella_pos)
   if(plot_umbrella_pos EQUAL -1)
     list(APPEND plot_umbrella_missing "${header}")
@@ -53,6 +84,16 @@ if(plot_umbrella_missing)
     "if it is implementation-only and not part of the public surface.")
 endif()
 
+# Said out loud rather than kept quiet: this is the one place the coverage rule
+# is not applied, so a configure log that does not list it would hide the fact
+# that a header is unchecked against the umbrella.
+if(plot_umbrella_exempt)
+  string(REPLACE ";" "\n  " plot_umbrella_exempt_text "${plot_umbrella_exempt}")
+  message(STATUS
+    "plot: umbrella check exempts optional-target header(s) the umbrella does "
+    "not name by design:\n  ${plot_umbrella_exempt_text}")
+endif()
+
 # And every header the umbrella names is a file that exists (a rename or a
 # deleted header cannot leave a dangling include behind).
 string(REGEX MATCHALL "#include <plot/[^>]+>" plot_umbrella_includes "${plot_umbrella_text}")