Support Homebrew-installed LLVM 20 on macOS

[rouson]

On macOS 15.4.1 with a Homebrew-installed LLVM 20.1.4, flang-new --version yields

Homebrew flang version 20.1.4
Target: arm64-apple-darwin24.4.0
Thread model: posix
InstalledDir: /opt/homebrew/Cellar/flang/20.1.4/libexec
Configuration file: /opt/homebrew/Cellar/flang/20.1.4/libexec/flang.cfg
Configuration file: /opt/homebrew/etc/clang/arm64-apple-darwin24.cfg

which isn't recognized by Caffeine's install.sh script. I just created PR #226 to address this. After fixing that issue, the next error that I encounter is

 exec /Users/rouson/.local/bin/fpm build --profile debug --flag '-g -O3 -DASSERT_MULTI_IMAGE -DASSERT_PARALLEL_CALLBACKS -DASSERTIONS  -O3 -g' --compiler /opt/homebrew/Cellar/flang/20.1.4/libexec/flang-new --c-compiler /opt/homebrew/Cellar/llvm/20.1.4/bin/clang --c-flag '-O3 -Wno-unused -Wunused-result -Wno-unused-parameter -Wno-address  -D_GNU_SOURCE=1 -DGASNET_SEQ -I/Users/rouson/.local/include -I/Users/rouson/.local/include/smp-conduit' --link-flag '-O3 -Wno-unused -Wunused-result -Wno-unused-parameter -Wno-address  -L/Users/rouson/.local/lib'
[  0%]                     caffeine.c
[  2%]                     caffeine.c  done.

././src/caffeine/caffeine.c:15:10: fatal error: 'ISO_Fortran_binding.h' file not found
   15 | #include <ISO_Fortran_binding.h>
      |          ^~~~~~~~~~~~~~~~~~~~~~~
1 error generated.
<ERROR> Compilation failed for object " src_caffeine_caffeine.c.o "
<ERROR> stopping due to failed compilation
STOP 1

From what I can tell, I have two copies of ISO_Fortran_binding.h installed with LLVM 20:

/opt/homebrew/Cellar/flang/20.1.4/include/flang/ISO_Fortran_binding.h
/opt/homebrew/Cellar/flang/20.1.4/lib/clang/20/include/ISO_Fortran_binding.h

@ktras @bonachea any thoughts on why it's not being found?

[bonachea]

@rouson Why was this closed as completed?

My understanding is this defect remains unresolved and possibly not yet fully diagnosed.

If you discovered a workaround, please post it here.
Otherwise we should leave this issue open to document the problem, until we have a resolution.

[rouson]

@bonachea I was multitasking and mis-clicked. I meant to click "Close as not planned." I don't think it's worth it to invest much time because Caffeine's target user is a compiler developer, which almost certainly means the user is building the compilers from source rather than using Homebrew. Nonetheless, I'll add two checkboxes and suggest we close this after these have been accomplished:

• @ktras to reproduce on a second macOS machine
• @rouson to report this issue to the maintainer of the Homebrew flang formula

[bonachea]

@rouson said:

I don't think it's worth it to invest much time because Caffeine's target user is a compiler developer, which almost certainly means the user is building the compilers from source rather than using Homebrew

I agree Homebrew is not an important use case for our real target users, but disagree that makes it not worth solving.

The main reason I'd like to see this solved is because I think it blocks issue #230, namely getting macOS+flang into Caffeine CI. We currently have no CI coverage for macOS+flang (or flang+ARM64), both of which are important to our project, and solving this problem could be a path to establishing both.

Of course we could also pursue other alternatives like finding or creating an appropriate LLVM container for macOS..

[bonachea]

Recommended workaround for users who encounter this problem:

export CFLAGS="-I$(dirname $(find $(brew --prefix)/Cellar/flang -name ISO_Fortran_binding.h | head -1))" 

Ensure Brew clang is first in your PATH:

export PATH="$(brew --prefix)/opt/llvm/bin:${PATH}"

Then install Caffeine as normal:

env FC=flang-new CC=clang CXX=clang++ ./install.sh

[bonachea]

As of PR #232 we now have macOS Homebrew flang in CI, using the workaround described above.

[bonachea]

As of today, the flang 21 homebrew package still exhibits the defect that causes this problem (demonstration in CI).

The workaround provided above remains effective.