Skip to content

Commit 6cee4af

Browse files
mizvekovK-ballo
andauthored
use system libs by default (#1077)
This change makes mrdocs use the system includes by default instead of the bundled ones. This helps mrdocs build projects which rely on differences between standard library implementations, since now mrdocs sees the source code closer to what the original compiler did, with only potential differences in the compilers themselves and some minor command line manipulations remaining. It also stops bundling the clang resource directory, relying on the one installed with libclang. This makes it so installing both to the same prefix be necessary, which is the same as all the other libclang based tools. --------- Co-authored-by: Agustin Berge <[email protected]>
1 parent c136a46 commit 6cee4af

File tree

24 files changed

+177
-83
lines changed

24 files changed

+177
-83
lines changed

.clang-format

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,3 +227,7 @@ IncludeCategories:
227227
# Comments
228228
FixNamespaceComments: true
229229
CommentPragmas: '^ clang-format'
230+
231+
---
232+
Language: Json
233+
BasedOnStyle: llvm

.github/workflows/ci.yml

Lines changed: 44 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -726,6 +726,26 @@ jobs:
726726
contents: write
727727

728728
steps:
729+
# This calculates a bunch of variables, which would normally go in to the regular matrix extra-values
730+
# section, but which depend on paths not known at that point.
731+
- name: Resolved Matrix
732+
id: rmatrix
733+
run: |
734+
set -euvx
735+
736+
third_party_dir="$(realpath $(pwd)/..)/third-party"
737+
if [[ "${{ runner.os }}" == 'Windows' ]]; then
738+
third_party_dir="$(echo "$third_party_dir" | sed 's/\\/\//g; s|^/d/|D:/|')"
739+
fi
740+
echo "third-party-dir=$third_party_dir" >> $GITHUB_OUTPUT
741+
742+
llvm_path="$third_party_dir/llvm"
743+
echo "llvm-path=$llvm_path" >> $GITHUB_OUTPUT
744+
745+
llvm_cache_key="${{ matrix.llvm-archive-basename }}"
746+
llvm_cache_key="${llvm_cache_key//:/-}"
747+
echo "llvm-cache-key=$llvm_cache_key" >> $GITHUB_OUTPUT
748+
729749
- name: Ensure Node
730750
if: matrix.container != '' && env.ACT == 'true'
731751
run: |
@@ -768,6 +788,14 @@ jobs:
768788
compiler: ${{ matrix.compiler }}
769789
version: ${{ matrix.version }}
770790

791+
- name: Cached LLVM Binaries
792+
id: llvm-cache
793+
uses: actions/cache@v4
794+
with:
795+
path: ${{ steps.rmatrix.outputs.llvm-path }}
796+
key: ${{ steps.rmatrix.outputs.llvm-cache-key }}
797+
fail-on-cache-miss: true
798+
771799
- name: Download MrDocs package
772800
uses: actions/download-artifact@v4
773801
with:
@@ -776,28 +804,29 @@ jobs:
776804

777805
- name: Install MrDocs from Package
778806
run: |
779-
set -x
780-
807+
set -euvx
808+
781809
# Delete packages/_CPack_Packages files from previous runs
782810
rm -rf packages/_CPack_Packages
783-
811+
784812
# Print tree structure
785813
find packages -print | sed 's;[^/]*/;|____;g;s;____|; |;g'
786-
814+
815+
dest_dir="${{ steps.rmatrix.outputs.llvm-path }}"
816+
787817
if [[ ${{ runner.os }} != 'Windows' ]]; then
788-
dest_dir="$HOME/local"
789-
mkdir -p "$dest_dir"
790818
find packages -maxdepth 1 -name 'MrDocs-*.tar.gz' -exec tar -vxzf {} -C $dest_dir --strip-components=1 \;
791819
else
792-
dest_dir="$GITHUB_WORKSPACE/usr/local"
793-
dest_dir=$(echo "$dest_dir" | sed 's/\\/\//g')
794-
find packages -maxdepth 1 -name "MrDocs-*.7z" -exec 7z x {} -o$dest_dir \;
795-
if [[ $(ls -1 $dest_dir | wc -l) -eq 1 ]]; then
796-
single_dir=$(ls -1 $dest_dir)
797-
if [[ -d $dest_dir/$single_dir ]]; then
798-
mv $dest_dir/$single_dir/* $dest_dir/
799-
rmdir $dest_dir/$single_dir
800-
fi
820+
package=$(find packages -maxdepth 1 -name "MrDocs-*.7z" -print -quit)
821+
filename=$(basename "$package")
822+
name="${filename%.*}"
823+
7z x "${package}" -o${dest_dir}
824+
set +e
825+
robocopy "${dest_dir}/${name}" "${dest_dir}" //move //e //np //nfl
826+
exit_code=$?
827+
set -e
828+
if (( exit_code >= 8 )); then
829+
exit 1
801830
fi
802831
fi
803832
MRDOCS_ROOT="$dest_dir"

CMakeLists.txt

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -261,15 +261,6 @@ if (NOT EXISTS "${LIBCXX_DIR}")
261261
"Please provide a LLVM with libc++ enabled\n")
262262
endif()
263263

264-
set(STDLIB_INCLUDE_DIR "${LLVM_BINARY_DIR}/lib/clang/${Clang_VERSION_MAJOR}/include"
265-
CACHE PATH "Path to the clang headers include directory")
266-
message(STATUS "STDLIB_INCLUDE_DIR: ${STDLIB_INCLUDE_DIR}")
267-
if (NOT EXISTS "${STDLIB_INCLUDE_DIR}")
268-
message(FATAL_ERROR
269-
"STDLIB_INCLUDE_DIR (${STDLIB_INCLUDE_DIR}) does not exist.\n"
270-
"Missing clang headers\n")
271-
endif()
272-
273264
list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
274265
include(HandleLLVMOptions)
275266
add_definitions(${LLVM_DEFINITIONS})
@@ -407,6 +398,15 @@ if (MRDOCS_DOCUMENTATION_BUILD)
407398
return()
408399
endif()
409400

401+
# Replicate the clang resource directory structure within our own build,
402+
# so that libclang will find it when executing directly from the build directory.
403+
# The installed binary will use runtime path resolution to locate the resource directory
404+
# relative to the executable, so both LLVM and MrDocs must be installed to the same prefix.
405+
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "bin")
406+
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/lib/clang")
407+
set(RESOURCE_DIR "lib/clang/${Clang_VERSION_MAJOR}")
408+
file(CREATE_LINK "${LLVM_BINARY_DIR}/${RESOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/${RESOURCE_DIR}" SYMBOLIC)
409+
410410
#-------------------------------------------------
411411
#
412412
# Tool
@@ -484,7 +484,6 @@ if (MRDOCS_BUILD_TESTS)
484484
"--addons=${CMAKE_SOURCE_DIR}/share/mrdocs/addons"
485485
--generator=${testgenerator}
486486
"--stdlib-includes=${LIBCXX_DIR}"
487-
"--stdlib-includes=${STDLIB_INCLUDE_DIR}"
488487
"--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
489488
--log-level=warn
490489
)
@@ -499,7 +498,6 @@ if (MRDOCS_BUILD_TESTS)
499498
"--addons=${CMAKE_SOURCE_DIR}/share/mrdocs/addons"
500499
--generator=${testgenerator}
501500
"--stdlib-includes=${LIBCXX_DIR}"
502-
"--stdlib-includes=${STDLIB_INCLUDE_DIR}"
503501
"--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
504502
--log-level=warn
505503
DEPENDS mrdocs-test
@@ -697,9 +695,6 @@ if (MRDOCS_INSTALL)
697695
install(DIRECTORY ${LIBCXX_DIR}/
698696
DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/libcxx
699697
FILES_MATCHING PATTERN "*")
700-
install(DIRECTORY ${STDLIB_INCLUDE_DIR}/
701-
DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/clang
702-
FILES_MATCHING PATTERN "*")
703698
install(DIRECTORY ${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs/
704699
DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/libc-stubs
705700
FILES_MATCHING PATTERN "*")

docs/modules/ROOT/pages/install.adoc

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,12 @@ manual intervention and potential errors.
4545
This approach is recommended for developers, advanced users, or those integrating Mr.Docs
4646
into larger projects.
4747
48+
[NOTE]
49+
====
50+
The bootstrap script automatically installs all dependencies (LLVM, Clang, etc.) to the same prefix as Mr.Docs.
51+
This ensures that the Clang resource directory can be found at runtime without additional configuration.
52+
====
53+
4854
[#mrdocs-source]
4955
== Manually Install from Source
5056
@@ -315,12 +321,19 @@ Then build and install MrDocs with:
315321
----
316322
cd build
317323
cmake --build .
318-
cmake --install .
324+
cmake --install . --prefix /path/to/llvm/install/prefix
319325
----
320326
321327
To customize the installation directory, use the `CMAKE_INSTALL_PREFIX` option or use the `--prefix` option for the `cmake --install .` command.
322328
To customize the C and C++ compilers, use the `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` options.
323329
330+
[IMPORTANT]
331+
====
332+
The `--prefix` for MrDocs installation *must* match the installation prefix used for LLVM/Clang.
333+
This is critical for proper runtime resolution of the Clang resource directory.
334+
For example, if LLVM was installed to `/opt/llvm`, then install MrDocs with `cmake --install . --prefix /opt/llvm`.
335+
====
336+
324337
[NOTE]
325338
====
326339
Developers should also enable `-D BUILD_TESTING=ON`.
@@ -337,3 +350,10 @@ The MrDocs installation directory follows the "Filesystem Hierarchy Standard" (F
337350
* `lib`: the MrDocs library
338351
339352
The FHS layout provides a directory structure that also serves as a widely accepted convention for organizing files and directories in Unix-like systems, but that can be used in any operating system.
353+
354+
[IMPORTANT]
355+
====
356+
The MrDocs binary must be installed in the same installation prefix as the Clang library it was built from.
357+
This is required because the Clang resource directory location is resolved relative to the MrDocs executable at runtime.
358+
When installing both LLVM/Clang and MrDocs, ensure they share the same `CMAKE_INSTALL_PREFIX`.
359+
====

docs/modules/ROOT/pages/usage.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ It's also common for libraries to depend on the C++ standard library, the C stan
278278

279279
That means unless `-nostdinc` is defined, all systems include paths are included. This is what allows the user to also use headers like `<Windows.h>` or `<linux/version.h>` without explicitly including anything else, even though they are not part of the C standard library. This is often seen as a convenience but can lead to portability issues.
280280

281-
In this context, MrDocs provides the `use-system-stdlib` and `use-system-libc` options. Both are set as `false` by default, meaning MrDocs will compile the code as if the `-nostdinc&plus;&plus; -nostdlib&plus;&plus;` and `-nostdinc` flags were passed to Clang. Additionally:
281+
In this context, MrDocs provides the `use-system-stdlib` and `use-system-libc` options. Both are set as `true` by default; setting both to `false` results in MrDocs compiling the code as if the `-nostdinc&plus;&plus; -nostdlib&plus;&plus;` and `-nostdinc` flags were passed to Clang. Additionally:
282282

283283
- When `use-system-stdlib` is `false`, MrDocs will use the bundled libc&plus;&plus; headers available in `<mrdocs-root>/share/mrdocs/headers/libcxx` and `<mrdocs-root>/share/mrdocs/headers/clang`. These paths can be adjusted with the `stdlib-includes` option.
284284
- When `use-system-libc` is `false`, MrDocs will use the bundled libc stubs available in `<mrdocs-root>/share/mrdocs/headers/libc-stubs`. This path can be adjusted with the `libc-includes` option.

docs/mrdocs.schema.json

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -570,8 +570,7 @@
570570
},
571571
"stdlib-includes": {
572572
"default": [
573-
"<mrdocs-root>/share/mrdocs/headers/libcxx",
574-
"<mrdocs-root>/share/mrdocs/headers/clang"
573+
"<mrdocs-root>/share/mrdocs/headers/libcxx"
575574
],
576575
"description": "When `use-system-stdlib` is disabled, the C++ standard library headers are available in these paths.",
577576
"items": {
@@ -611,7 +610,7 @@
611610
"type": "string"
612611
},
613612
"use-system-libc": {
614-
"default": false,
613+
"default": true,
615614
"description": "To achieve reproducible results, MrDocs bundles the LibC headers with its definitions. To use the C standard library available in the system instead, set this option to true.",
616615
"enum": [
617616
true,
@@ -621,7 +620,7 @@
621620
"type": "boolean"
622621
},
623622
"use-system-stdlib": {
624-
"default": false,
623+
"default": true,
625624
"description": "To achieve reproducible results, MrDocs bundles the LibC++ headers. To use the C++ standard library available in the system instead, set this option to true.",
626625
"enum": [
627626
true,

docs/website/snippets/sqrt.cpp

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
#include <type_traits>
2-
#include <stdexcept>
32

43
/** Computes the square root of an integral value.
54

include/mrdocs/Support/Concepts.hpp

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -137,8 +137,12 @@ concept range_of_tuple_like =
137137
std::ranges::range<Range> && tuple_like<std::ranges::range_value_t<Range>>;
138138

139139
#ifdef __cpp_lib_reference_from_temporary
140-
using std::reference_constructs_from_temporary_v;
141-
using std::reference_converts_from_temporary_v;
140+
/** True when binding `To` from `From` would require a temporary conversion.
141+
*/
142+
using std::reference_constructs_from_temporary_v;
143+
/** Like `reference_converts_from_temporary_v`, but for construction.
144+
*/
145+
using std::reference_converts_from_temporary_v;
142146
#else
143147
/** True when binding `To` from `From` would require a temporary conversion.
144148
*/

src/lib/AST/ASTVisitor.cpp

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2372,7 +2372,8 @@ extractSFINAEInfo(clang::QualType const T)
23722372
Result.Type = resultType->getAsType();
23732373
for (std::size_t I = 0; I < Args.size(); ++I)
23742374
{
2375-
if (SFINAEControl->ControllingParams[I])
2375+
if (I < SFINAEControl->ControllingParams.size()
2376+
&& SFINAEControl->ControllingParams[I])
23762377
{
23772378
MRDOCS_SYMBOL_TRACE(Args[I], context_);
23782379
clang::TemplateArgument ArgsI = Args[I];

src/lib/AST/ExtractDocComment.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -627,7 +627,7 @@ class DocCommentVisitor
627627
auto compsExp = parseHTMLStartSpan(C, cur);
628628
if (!compsExp)
629629
{
630-
report::error(
630+
report::warn(
631631
"{} at {} ({})",
632632
compsExp.error().message(),
633633
filename,

0 commit comments

Comments
 (0)