Docs: detect version of clang++

[sdarwin]

@alandefreitas wrote: "@sdarwin The Antora workflow that generates the preview will probably break again." Yes the same issue occurred on http_proto. This fix allows build_antora.sh to be run locally, or from another location, not depending on inputs from CI.

[cppalliance-bot]

An automated preview of the documentation is available at https://848.url.prtest2.cppalliance.org/libs/url/doc/html/index.html

[cppalliance-bot]

GCOVR code coverage report https://848.url.prtest2.cppalliance.org/gcovr/index.html
LCOV code coverage report https://848.url.prtest2.cppalliance.org/genhtml/index.html
Coverage Diff https://848.url.prtest2.cppalliance.org/gcovr/coverage_diff.txt

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.21%. Comparing base (951477d) to head (2736b6f).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #848   +/-   ##
========================================
  Coverage    99.21%   99.21%           
========================================
  Files          157      157           
  Lines         8422     8422           
========================================
  Hits          8356     8356           
  Misses          66       66           

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 951477d...2736b6f. Read the comment docs.

[alandefreitas]

The biggest issue with my initial comment is whether clang++-18 is actually available on the machine that builds the preview. Is it?

[alandefreitas]

The workflow already sets CXX and CC. Is this change to ensure it works in the container that builds the preview?

[alandefreitas]

Maybe I wasn't explicit enough in my initial comment but #847 already addressed the environment variables among other things in 95e50b8

[sdarwin]

Yes, in the container that builds the previews.
A script that performs some function, let's say "builds the docs with antora", should ideally work "in the wild", whether that is Jenkins previews, or if a developer is running it locally on their laptop to build docs. In those cases, the operating system might have both gcc and clang installed. build_antora.sh needs to prefer clang. This code causes clang to be chosen. But allows overrides as well. CXX may be specified beforehand.

Another topic.. this section:

      - name: Build Antora Docs
        run: |
          cd doc
          bash ./build_antora.sh
          
          # Antora returns zero even if it fails, so we check if the site directory exists
          if [ ! -d "build/site" ]; then
              echo "Antora build failed"
              exit 1
          fi

Can be simplified to :

       - name: Build Antora Docs
        run: |
          set -e
          cd doc
          bash ./build_antora.sh

If build_antora.sh also uses set -e. Generally a nice idea to add in any multi-line bash scripts to discover hidden errors.

[alandefreitas]

Yes, in the container that builds the previews.

Nice :)

A script that performs some function, let's say "builds the docs with antora", should ideally work "in the wild", whether that is Jenkins previews, or if a developer is running it locally on their laptop to build docs.

Yes. I opened an issue in MrDocs to address that: cppalliance/mrdocs#644

When this changes, any compiler can run cmake to generate the compile_commands.json, but the standard library headers will ultimately come from MrDocs so there will never be any conflict between the mrdocs compiler and the standard library headers.

In those cases, the operating system might have both gcc and clang installed. build_antora.sh needs to prefer clang.

Yes. This logic is already in the javascript script that generates the reference pages. It prefers clang, then GCC, than MSVC.
It only falls back to process.env.CXX_COMPILER or process.env.CXX when the compiler is not found.

url/doc/generate-files.mjs

Line 98 in 95e50b8

let cxxCompiler = findExecutable(['clang++', 'g++', 'cl']) || process.env.CXX_COMPILER || process.env.CXX

The problem we have is it fails to find clang++ because installing in ubuntu clang++-18 only gives us the clang++-18 executable. Not clang++. I will address that.

This code causes clang to be chosen. But allows overrides as well. CXX may be specified beforehand.

Yes. That's also the case because the script that generates the reference pages also checks these environment variables. The problem for now is more about clang++-18 not being available or when it can't be found because CXX is not set. But it already identifies CXX.

We should be good as long as clang++-18 is available. I'll include some logic to look for clang++-\d+ and gcc-\d+ in the extension.

[sdarwin]

It sounds like you will solve the problem in various other (better) ways within Mr. Docs itself, and so on. OK.

We should be good as long as clang++-18 is available.

The previews container has clang++-18.

But was getting error: definition of builtin function '_mm_setcsr'.

The logic in this pull request searches for the newest clang, rather than specifically 18. Soon it will happen that clang-20 is available while clang-18 is missing. That case would already be handled. But if you will solve the problem more correctly elsewhere, that is great.

[alandefreitas]

It sounds like you will solve the problem in various other (better) ways within Mr. Docs itself and so on. OK.

Yes. There are many levels to it.

We had this problem finding the compiler, which I was already fixing in the Antora extension, so it finds these latest versioned executables by itself.

MrDocs currently needs the compiler to run cmake, but there's potential for improvement. In the future, MrDocs might be able to use itself as the compiler.

However, the other issue is with the standard library, for which we also have an issue in the MrDocs repo.

The previews container has clang++-18.
But was getting error: definition of builtin function '_mm_setcsr'.

Nice. That's the only thing I needed clarification on. As long as the compiler is available, #843 should solve the issue.

The PR is already receiving previews again: https://843.urlantora.prtest2.cppalliance.org/site/index.html

The logic in this pull request searches for the newest clang, rather than specifically 18. Soon it will happen that clang-20 is available while clang-18 is missing. That case would already be handled. But if you will solve the problem more correctly elsewhere, that is great.

Yes. The solution implemented in the extension is a little more elegant because it's at a lower level and because in bash we would "need" to look for clang-40, clang-39, ...

[alandefreitas]

Obsoleted by #843