diff options
| author | _ov4 <ov4@ov4.org> | 2026-10-13 05:08:14 +0000 |
|---|---|---|
| committer | _ov4 <ov4@ov4.org> | 2026-10-13 05:08:14 +0000 |
| commit | 84cbd5fef8c67586f08cb7396f9d60ef4a07622f (patch) | |
| tree | 229029f00ebb977bcc93889fb5f7189f6ba8de1f | |
| parent | 26b378e7e90f950e8d64a294e56fbe9e06d19214 (diff) | |
build: render standalone HTML documentation on Windows
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
| -rw-r--r-- | AGENTS/ARCH.md | 3 | ||||
| -rw-r--r-- | CMakeLists.txt | 20 | ||||
| -rw-r--r-- | README.md | 13 |
3 files changed, 29 insertions, 7 deletions
diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index 2707ba3..f235295 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -81,6 +81,9 @@ to the user PATH without copying the combined process PATH, and creates a per-user Start Menu help shortcut. `-SourceDir` selects the artifact directory; `DESTDIR` staging is unsupported on Windows. The script is compatible with Windows PowerShell 5.1; its Windows actions have only been reviewed statically. +The `doc` target uses CMake's `WIN32` target-platform detection: Windows generates +standalone HTML with inline styles at `build/doc/cpsc.html`; other platforms +generate `build/doc/cpsc.1`. Both render the same `doc/cpsc.md` using Pandoc. Build pin: developed and tested against **LLVM 18**. (The historical LLVM 19 breakage — `ArithmeticHandler.cc` touching `llvm::Module` through a transitive include — is gone diff --git a/CMakeLists.txt b/CMakeLists.txt index b3986eb..baf337a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -68,17 +68,27 @@ target_link_libraries(cpsc ${llvm_libs} ) +if(WIN32) + set(cpsc_manual_file "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.html") + set(cpsc_manual_format html5) + set(cpsc_manual_options --metadata "title=cpsc manual") +else() + set(cpsc_manual_file "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.1") + set(cpsc_manual_format man) + set(cpsc_manual_options) +endif() add_custom_command( - OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.1" + OUTPUT "${cpsc_manual_file}" COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/doc" - COMMAND pandoc --standalone --from=markdown --to=man + COMMAND pandoc --standalone --from=markdown "--to=${cpsc_manual_format}" + ${cpsc_manual_options} "${CMAKE_CURRENT_SOURCE_DIR}/doc/cpsc.md" - --output "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.1" + --output "${cpsc_manual_file}" DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/doc/cpsc.md" - COMMENT "Generating cpsc(1) manual" + COMMENT "Generating cpsc manual (${cpsc_manual_format})" VERBATIM ) -add_custom_target(doc DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.1") +add_custom_target(doc DEPENDS "${cpsc_manual_file}") configure_file(cmake/Install.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/Install.cmake" @ONLY) install(SCRIPT "${CMAKE_CURRENT_BINARY_DIR}/Install.cmake") @@ -134,7 +134,7 @@ and kept even if execution fails. ## Manual -The command-line quick reference is in `doc/cpsc.md`. Generating the man page requires Pandoc; ordinary builds do not. +The command-line quick reference is in `doc/cpsc.md`. Generating the manual requires Pandoc; ordinary builds do not. From the project root on Linux: @@ -146,7 +146,16 @@ man ./build/doc/cpsc.1 ``` You can also run `make doc` inside the configured `build/` directory. -The output is `build/doc/cpsc.1` and is regenerated when the Markdown source changes. +The output is `build/doc/cpsc.1` on Unix and `build/doc/cpsc.html` on Windows, +and is regenerated when the Markdown source changes. On Windows, install Pandoc, +then generate and open the standalone HTML manual from PowerShell: + +```powershell +cmake --build build --target doc +Start-Process .\build\doc\cpsc.html +``` + +The HTML contains its own styles and can be read offline in a browser. ## Install and release |