Segfault on most of Boost.GIL's headers

[sdebionne]

While converting Boost.GIL documentation to AsciiDoc + Antora + MrDocs toolchain (in boostorg/gil#797), I hit a serious blocker while validating the MrDocs piece.

Summary

Running MrDocs 0.8.0 (Linux release binary, MrDocs-0.8.0-Linux.tar.xz) against boostorg/gil's headers segfaults on 38 of the 49 headers pulled in by the library's umbrella header (boost/gil.hpp), each reproducing in complete isolation (a single #include in an otherwise empty translation unit). The headers that crash are exactly the ones built around GIL's CRTP proxy-reference pattern: pixel.hpp, image.hpp, image_view.hpp, locator.hpp, algorithm.hpp, pixel_iterator*.hpp, rgb.hpp, step_iterator.hpp, and everything under image_processing/. Headers without that pattern (channel.hpp, point.hpp, color_base.hpp, concepts.hpp, utilities.hpp, gray.hpp, dynamic_step.hpp, promote_integral.hpp, rasterization/*.hpp) extract cleanly.

This effectively blocks generating a MrDocs/Antora reference for GIL today, since the crashing headers are exactly the ones declaring GIL's most-used public types.

Environment

• MrDocs 0.8.0 (MrDocs version 0.8.0, Built with LLVM 22.0.0git,
  Build SHA 33d985ccf31e2e3208f317bb5e6e9b91be4400f5, x86_64-unknown-linux-gnu)
• Ubuntu (linux-64), boostorg/gil develop branch as of 2026-09-01
  (commit 9bb53c581)

Reproduction

git clone https://github.com/boostorg/gil.git
git clone --depth 1 https://github.com/boostorg/stl_interfaces.git   # gil's iterator base
git clone --depth 1 https://github.com/boostorg/boost.git boost-root # for cross-lib headers, OR use a full boost checkout with headers staged under `boost/`

mkdir -p smoketest/src
cat > smoketest/src/all.cpp <<'EOF'
#include <boost/gil/pixel.hpp>
EOF

cat > smoketest/compile_commands.json <<EOF
[
  {
    "directory": "$(pwd)/smoketest/src",
    "command": "c++ -std=c++17 -I$(pwd)/gil/include -I<boost-root> -I$(pwd)/stl_interfaces/include -c all.cpp",
    "file": "all.cpp"
  }
]
EOF

cat > smoketest/mrdocs.yml <<'EOF'
source-root: gil
input:
  - gil/include/boost/gil
file-patterns:
  - '*.hpp'
include-symbols:
  - 'boost::gil::**'
generator: adoc
multipage: true
EOF

mrdocs --config=smoketest/mrdocs.yml \
       --compilation-database=smoketest/compile_commands.json \
       --output=smoketest/out

Result: segmentation fault, exit code 139. Stack dump has no symbols (no llvm-symbolizer on PATH in this environment), but is a deep, repeating frame pattern (255+ frames before truncation) consistent with unbounded recursion during AST visitation, not a simple null-pointer crash. Immediately before the crash, MrDocs prints:

Extracting declarations
<eof> parser at end of file

which looks like it's coming from the comment-doc lexer/parser hitting EOF unexpectedly, though I haven't traced further without symbols.

Per-header result (isolated, #include <boost/gil/X.hpp> alone)

Header	Result
channel.hpp	OK (225 pages)
color_base.hpp	OK
color_base_algorithm.hpp	OK
concepts.hpp	OK
dynamic_step.hpp	OK
gray.hpp	OK
point.hpp	OK
promote_integral.hpp	OK
utilities.hpp	OK
extension/rasterization/{circle,ellipse,line}.hpp	OK
algorithm.hpp	segfault
bit_aligned_pixel_iterator.hpp	segfault
bit_aligned_pixel_reference.hpp	segfault
channel_algorithm.hpp	segfault
cmyk.hpp	segfault
color_convert.hpp	segfault
device_n.hpp	segfault
histogram.hpp	segfault
image.hpp	segfault
image_view.hpp	segfault
image_view_factory.hpp	segfault
iterator_from_2d.hpp	segfault
locator.hpp	segfault
metafunctions.hpp	segfault
packed_pixel.hpp	segfault
pixel.hpp	segfault
pixel_iterator.hpp	segfault
pixel_iterator_adaptor.hpp	segfault
planar_pixel_iterator.hpp	segfault
planar_pixel_reference.hpp	segfault
position_iterator.hpp	segfault
premultiply.hpp	segfault
rgb.hpp	segfault
rgba.hpp	segfault
step_iterator.hpp	segfault
typedefs.hpp	segfault
virtual_locator.hpp	segfault
image_processing/*.hpp (all 8 files)	segfault

Expected behavior

MrDocs should either successfully extract declarations from these headers, or fail gracefully with a diagnostic pointing at the offending construct (as it already does for e.g. --ignore-failures-recoverable warnings), rather than segfaulting.

Possibly related

• Segfault with template-template in function #795 "Segfault with template-template in function"
• Segfault when parsing template specializations involving nested type access #748 "Segfault when parsing template specializations involving nested type access"
• Segfault when a public function uses a private type alias #794 "Segfault when a public function uses a private type alias"

GIL's pixel/iterator/locator classes are heavy users of exactly these patterns (CRTP proxy references, nested const_t/value_type type aliases, iterator adaptors built via template-template parameters), so this may be a recurrence or an unfixed corner of one of those.

Notes

• algorithm.hpp and pixel.hpp alone (no other GIL headers) are probably the smallest starting points to bisect from, since they crash in total isolation.

[alandefreitas]

Have you happened to try it with the develop release? There's a good chance this has already been fixed.

[sdebionne]

I would like to test that, but, AFAIU, it might a bit involved to build from source. Is there a nightly build that I could try?

[sdebionne]

I guess I can get an artifact from the CI pipelines (https://github.com/cppalliance/mrdocs/actions/runs/33587765201/artifacts/9830961242)

[sdebionne]

No change — this develop build (0.8.0+c43bf98dea11, LLVM 23) crashes on the exact same 38 of 49 headers as the released v0.8.0, and succeeds on the exact same 11. Same behavior on the full boost/gil.hpp umbrella include too. So whatever's fixed on develop since the 0.8.0 release doesn't touch this bug — it's still fully blocking.

Shall I try another build?

[alandefreitas]

It should be working now after #1273: gil.zip

[sdebionne]

Awesome! I always feel uneasy when I copy and paste things from my AI agents, but real humans really appreciate it. You might have seen that question coming: when do you think we could have a new release of MrDocs?

[alandefreitas]

A more complete version with documentation (I left the source at https://github.com/alandefreitas/gil-mrdocs-fork in case you want to cherry pick some of it) would look like this: gil.zip

[alandefreitas]

Awesome! I always feel uneasy when I copy and paste things from my AI agents, but real humans really appreciate it.

Yes. AI is good at including details we need to replicate the issue. I still like at least a human section explaining how it affects them.

You might have seen that question coming: when do you think we could have a new release of MrDocs?

Probably today, actually. :)

[sdebionne]

Thank you @alandefreitas !

I have started writing a conda recipe for MrDocs so that it can land in the Conda Forge ecosystem (and Pixi). AFAIU, MrDocs is using a specific build/commit of LLVM so I cannot reuse the LLVM build 23.1.0 that is already available, is that correct?

I am also adding jerryscript to Conda Forge, all the rest is already readily available.

[sdebionne]

The Boost.GIL doc based on your tool chain is already live https://boostorg.github.io/gil/develop/doc/gil/index.html

[alandefreitas]

AFAIU, MrDocs is using a specific build/commit of LLVM so I cannot reuse the LLVM build 23.1.0 that is already available, is that correct?

Exactly. We use specific commits rather than canonical versions so we can use the clang's unstable API, customize the build with things we need, and make sure we have access to all clang features we want to document. This is typically not a problem because MrDocs is a tool so people just download the binaries.

The Boost.GIL doc based on your tool chain is already live https://boostorg.github.io/gil/develop/doc/gil/index.html

That's a much nicer table of contents :)

If you know the logic you want for the table, you can also have an extension and have mrdocs generate it.

https://mrdocs.com/docs/mrdocs/develop/extensions/script-generators.html#_navigation_lists

This section title should be called "table of contents".