feat(cmake): find_package(mrdocs)

.github/scripts/install-mrdocs-package.sh

@@ -49,6 +49,12 @@ echo "::endgroup::"
 echo "::group::Export environment variables"
 echo "MRDOCS_ROOT=$MRDOCS_INSTALL_DIR"
 echo "MRDOCS_ROOT=$MRDOCS_INSTALL_DIR" >> "$GITHUB_ENV"
+# CMake-valid absolute prefix for find_package(mrdocs). MRDOCS_ROOT above is the
+# Git Bash /d/... form on Windows, which CMake rejects; derive this one from
+# GITHUB_WORKSPACE and normalize backslashes instead.
+MRDOCS_PREFIX="${GITHUB_WORKSPACE//\\//}/.install/mrdocs"
+echo "MRDOCS_PREFIX=$MRDOCS_PREFIX"
+echo "MRDOCS_PREFIX=$MRDOCS_PREFIX" >> "$GITHUB_ENV"
 echo "PATH += $MRDOCS_INSTALL_DIR/bin"
 echo "$MRDOCS_INSTALL_DIR/bin" >> "$GITHUB_PATH"
 echo "::endgroup::"

.github/workflows/ci-build.yml

@@ -79,6 +79,8 @@ jobs:
             ${{ matrix.bootstrap-sanitizer && format('--sanitizer {0}', matrix.bootstrap-sanitizer) || '' }} \
             ${{ matrix.common-ccflags && format('--cflags="{0}" --cxxflags="{0}"', matrix.common-ccflags) || '' }}
           cat "$RUNNER_TEMP/bootstrap-env.txt" >> "$GITHUB_ENV"
+          # mrdocs install prefix, reused for the install and the consumer test
+          echo "MRDOCS_PREFIX=${GITHUB_WORKSPACE//\\//}/.local" >> "$GITHUB_ENV"
 
       # Save the LLVM cache when bootstrap rebuilt it (cache miss or
       # stale stamp). BOOTSTRAP_REBUILT lists rebuilt recipes.
@@ -129,7 +131,7 @@ jobs:
           generator: Ninja
           build-dir: build/mrdocs
           build-type: ${{ matrix.build-type }}
-          install-prefix: .local
+          install-prefix: ${{ env.MRDOCS_PREFIX }}
           export-compile-commands: true
           run-tests: true
           install: true
@@ -139,6 +141,58 @@ jobs:
           package-artifact: false
           ctest-timeout: 9000
 
+      # Consume the freshly installed mrdocs through its exported CMake package,
+      # from an out-of-tree project (tests/cmake): find_package(mrdocs), link
+      # mrdocs::mrdocs-core, and run the installed binary via MRDOCS_EXECUTABLE.
+      # This is the only coverage of mrdocs-as-a-library, so it runs on every
+      # normal build, on every platform (the default static library bundles its
+      # private toolchain, so this is where we prove a consumer links it with no
+      # LLVM/Clang/JerryScript/Lua present). It goes through the same
+      # cmake-workflow action as the main build (configure + build + ctest),
+      # pointed at tests/cmake, discovering the install through mrdocs_ROOT -- the
+      # package-specific find_package hint rather than CMAKE_PREFIX_PATH, so the
+      # <PackageName>_ROOT search path is exercised. Only the ABI flags mrdocs was
+      # built with are reused (the consumer must match the same standard library),
+      # not mrdocs's own -Werror/-static/-WX matrix flags. Coverage/sanitizer
+      # builds use instrumented toolchains an out-of-tree consumer would have to
+      # mirror exactly, so those are skipped. mrdocs_ROOT gets the MRDOCS_PREFIX
+      # resolved above.
+      - name: CMake Consumer Test (cmake test)
+        if: ${{ !matrix.coverage && !matrix.bootstrap-sanitizer }}
+        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
+        with:
+          cmake-version: '>=3.26'
+          source-dir: tests/cmake
+          build-dir: build/cmake-consumer
+          cxxstd: ${{ matrix.cxxstd }}
+          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
+          cxxflags: ${{ env.BOOTSTRAP_CXXFLAGS }}
+          ldflags: ${{ env.BOOTSTRAP_LDFLAGS }}
+          generator: Ninja
+          build-type: ${{ matrix.build-type }}
+          extra-args: -D mrdocs_ROOT=${{ env.MRDOCS_PREFIX }}
+          run-tests: true
+          install: false
+
+      - name: CMake Consumer Test (library example)
+        if: ${{ !matrix.coverage && !matrix.bootstrap-sanitizer }}
+        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
+        with:
+          cmake-version: '>=3.26'
+          source-dir: examples/library/breaking-changes
+          build-dir: build/example-breaking-changes
+          cxxstd: ${{ matrix.cxxstd }}
+          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
+          cxxflags: ${{ env.BOOTSTRAP_CXXFLAGS }}
+          ldflags: ${{ env.BOOTSTRAP_LDFLAGS }}
+          generator: Ninja
+          build-type: ${{ matrix.build-type }}
+          extra-args: -D mrdocs_ROOT=${{ env.MRDOCS_PREFIX }}
+          run-tests: true
+          install: false
+
       # Upload packages for ci-releases.yml to pick up
       - name: Upload GitHub Release Artifacts
         if: matrix.is-release-build == 'true'

.github/workflows/ci-releases.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Install packages
         uses: alandefreitas/cpp-actions/package-install@v1.9.5
         with:
-          apt-get: build-essential asciidoctor cmake bzip2 git rsync
+          apt-get: build-essential asciidoctor cmake ninja-build bzip2 git rsync
 
       - name: Clone MrDocs
         uses: actions/checkout@v6
@@ -101,6 +101,24 @@ jobs:
       - name: Install MrDocs from Package
         run: .github/scripts/install-mrdocs-package.sh
 
+      # Discovers the package through mrdocs_ROOT (the package-specific
+      # find_package hint) rather than CMAKE_PREFIX_PATH. install-mrdocs-package.sh
+      # exports MRDOCS_PREFIX as its CMake-valid form.
+      - name: CMake Consumer Test (release package)
+        uses: alandefreitas/cpp-actions/cmake-workflow@v1.9.5
+        with:
+          cmake-version: '>=3.26'
+          source-dir: tests/cmake
+          build-dir: build/cmake-consumer
+          cxxstd: ${{ matrix.cxxstd }}
+          cc: ${{ steps.setup-cpp.outputs.cc || matrix.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx || matrix.cxx }}
+          generator: Ninja
+          build-type: ${{ matrix.build-type }}
+          extra-args: -D mrdocs_ROOT=${{ env.MRDOCS_PREFIX }}
+          run-tests: true
+          install: false
+
       - name: Clone Boost.URL
         uses: alandefreitas/cpp-actions/boost-clone@v1.9.5
         with:

CMakeLists.txt

@@ -32,34 +32,49 @@ include(utils/cmake/helpers.cmake)
 # Project options
 #
 #-------------------------------------------------
-option(MRDOCS_INSTALL "Configure install target" ON)
-option(MRDOCS_PACKAGE "Build install package" ON)
-option(MRDOCS_BUILD_SHARED "Link shared" ${BUILD_SHARED_LIBS})
+# What to build
+option(MRDOCS_MRDOCS_BUILD "Build only public-headers for documentation self-reference" OFF)
+if (MRDOCS_MRDOCS_BUILD)
+    include(docs/mrdocs-build.cmake)
+    return()
+endif()
 option(MRDOCS_BUILD_TESTS "Build tests" ${BUILD_TESTING})
+option(MRDOCS_BUILD_STRICT_TESTS "Enable costly strict tests" ON)
 option(MRDOCS_BUILD_EXAMPLES "Build the examples" ${MRDOCS_BUILD_TESTS})
+option(MRDOCS_BUILD_DOCS "Build documentation" OFF)
+option(MRDOCS_GENERATE_REFERENCE "Generate MrDocs reference" ${MRDOCS_BUILD_DOCS})
+option(MRDOCS_INSTALL "Configure install target" ON)
+option(MRDOCS_PACKAGE "Build install package" ON)
 if (MRDOCS_BUILD_TESTS OR MRDOCS_BUILD_EXAMPLES)
     enable_testing()
     include(CTest)
 endif()
-option(MRDOCS_BUILD_STRICT_TESTS "Enable strict tests" ON)
+
+# How to build
 option(MRDOCS_REQUIRE_GIT "Git is required: not being able to extract version build is an error" ON)
-option(MRDOCS_BUILD_DOCS "Build documentation" OFF)
-option(MRDOCS_BUILD_HEADERS_ONLY "Build only public-headers for self-reference" OFF)
-option(MRDOCS_GENERATE_REFERENCE "Generate MrDocs reference" ${MRDOCS_BUILD_DOCS})
+option(MRDOCS_BUNDLE_DEPENDENCIES "Bundle the private dependencies into the library" ON)
+option(MRDOCS_BUILD_SHARED "Link shared" ${BUILD_SHARED_LIBS})
 option(MRDOCS_GENERATE_ANTORA_REFERENCE "Generate MrDocs reference in Antora module pages" OFF)
 
+# Helper variables based on options
 set_ternary(MRDOCS_LINK_MODE MRDOCS_BUILD_SHARED SHARED "")
 set_ternary(MRDOCS_LINK_MODE_DEFINITION MRDOCS_BUILD_SHARED MRDOCS_SHARED_LINK MRDOCS_STATIC_LINK)
+set_ternary(MRDOCS_DO_BUNDLE_DEPENDENCIES "MRDOCS_BUNDLE_DEPENDENCIES AND NOT MRDOCS_BUILD_SHARED" ON OFF)
+set_ternary(MRDOCS_DO_REEXPORT_DEPENDENCIES "NOT MRDOCS_DO_BUNDLE_DEPENDENCIES AND NOT MRDOCS_BUILD_SHARED" ON OFF)
 set_ternary(MRDOCS_GCC   "CMAKE_CXX_COMPILER_ID STREQUAL \"GNU\"" ON OFF)
 set_ternary(MRDOCS_CLANG "CMAKE_CXX_COMPILER_ID MATCHES \"Clang$\"" ON OFF)
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
-
+# MSVC flags shared by every mrdocs target below (not installed consumers):
+#  - /EHs enables C++ exception handling. The mrdocs tool, the unit tests, and the
+#    examples are separate targets whose TUs include exception-using STL headers, so
+#    without it MSVC raises C4530 and /WX makes it fatal; the EH model must also be
+#    uniform across all TUs, so it belongs here rather than on mrdocs-core alone.
+#  - /wd4100 accepts unused parameters, an accepted style across mrdocs (visitor /
+#    tag_invoke / finalizer signatures) that the clang build already allows via
+#    -Wno-unused-parameter; mirror it so /W4 /WX does not fail on C4100.
 if (MSVC)
-    # Suppressions we use to get from LLVM's HandleLLVMOptions.cmake
-    add_compile_options(/wd4100 /wd4127 /wd4141 /wd4146 /wd4204 /wd4244 /wd4245 /wd4267 /wd4291 /wd4310 /wd4319 /wd4324 /wd4351 /wd4389 /wd4456 /wd4457 /wd4458 /wd4459 /wd4503 /wd4505 /wd4510 /wd4512 /wd4577 /wd4592 /wd4610 /wd4611 /wd4624 /wd4701 /wd4702 /wd4703 /wd4706 /wd4722 /wd4805 /wd5105)
-    # Conformance flags we used to get from LLVM's HandleLLVMOptions.cmake
-    add_compile_options(/Zc:__cplusplus /Zc:preprocessor)
+    add_compile_options(/EHs /wd4100)
 endif()
 
 #-------------------------------------------------
@@ -70,14 +85,17 @@ endif()
 add_subdirectory(utils)
 add_subdirectory(libs)
 add_subdirectory(src)
-if (MRDOCS_BUILD_HEADERS_ONLY)
-    return()
-else()
 add_subdirectory(tools)
-add_subdirectory(tests)
-add_subdirectory(examples)
-add_subdirectory(docs)
-add_subdirectory(data)
-include(utils/cmake/install.cmake)
-mrdocs_install()
+if (MRDOCS_BUILD_TESTS)
+    add_subdirectory(tests)
+endif()
+if (MRDOCS_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+if (MRDOCS_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
+if (MRDOCS_INSTALL)
+    add_subdirectory(data)
+    mrdocs_install()
 endif()

data/CMakeLists.txt

@@ -9,10 +9,6 @@
 #
 
 # This directory only installs assets, so it does nothing unless installing.
-if (MRDOCS_BUILD_HEADERS_ONLY OR NOT MRDOCS_INSTALL)
-    return()
-endif()
-
 # Install the shared assets this directory owns into the FHS share/ location.
 # (The LLVM-derived assets, bundled libc++ headers and the clang resource dir,
 # are installed by src/, next to the dependency that provides them.)
@@ -25,7 +21,7 @@ foreach (mrdocs_dir addons)
             DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs
             FILES_MATCHING PATTERN "*")
 endforeach ()
-foreach (data_dir cmake gdb)
+foreach (data_dir gdb)
     install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/${data_dir}
             DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs
             FILES_MATCHING PATTERN "*")

data/README.md

@@ -8,6 +8,5 @@ mirrored into the `share/` subtree; this README is not installed.
 ## Contents
 - `mrdocs/` — runtime assets installed with MrDocs: `addons/` (Handlebars
   templates and generator helpers) and `headers/` (bundled libc stubs).
-- `cmake/` — `MrDocs.cmake`, the consumer helper for downstream CMake projects.
 - `gdb/` — GDB pretty-printers for MrDocs types.
 - `lldb/` — LLDB data formatters for MrDocs types.