Homebrew's `cmake` doesn't know out of the box how to find Homebrew's `libomp`, but users will expect it to

[adamnovak]

brew gist-logs <formula> link OR brew config AND brew doctor output

[anovak@swords test]% brew gist-logs cmake
Error: No logs.
[anovak@swords test]% brew gist-logs libomp
Error: No logs.
[anovak@swords test]% brew config
HOMEBREW_VERSION: 4.6.7
ORIGIN: https://github.com/Homebrew/brew
HEAD: 02947ea4edbdef5fcce9ee57fa289547f4d096c9
Last commit: 5 days ago
Branch: stable
Core tap JSON: 29 Aug 17:03 UTC
Core cask tap JSON: 29 Aug 17:08 UTC
HOMEBREW_PREFIX: /opt/homebrew
HOMEBREW_CASK_OPTS: []
HOMEBREW_DISPLAY: /private/tmp/com.apple.launchd.YJyOLyJ9gH/org.xquartz:0
HOMEBREW_FORBID_PACKAGES_FROM_PATHS: set
HOMEBREW_MAKE_JOBS: 8
Homebrew Ruby: 3.4.5 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.4.5/bin/ruby
CPU: octa-core 64-bit arm_firestorm_icestorm
Clang: 17.0.0 build 1700
Git: 2.39.5 => /Library/Developer/CommandLineTools/usr/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 15.6.1-arm64
CLT: 16.4.0.0.1.1747106510
Xcode: N/A
Rosetta 2: false
[anovak@swords test]% brew doctor
Your system is ready to brew.

Verification

• My brew doctor output says Your system is ready to brew. and am still able to reproduce my issue.
• I ran brew update and am still able to reproduce my issue.
• I have resolved all warnings from brew doctor and that did not fix my problem.
• I searched for recent similar issues at https://github.com/Homebrew/homebrew-core/issues?q=is%3Aissue and found no duplicates.
• My issue is not about a failure to build a formula from source.

What were you trying to do (and why)?

I'm trying to build a project from source that uses CMake as its build system and has the OpenMP library as a dependency. I have both cmake and libomp installed through Homebrew.

The CMakeLists.txt of the project I am trying to build has a find_package(OpenMP REQUIRED) line, which instructs CMake to go find OpenMP and stop the build if it can't. This is the "correct" way to depend on OpenMP in CMake as far as I know, and works great on e.g. Linux distributions like Ubuntu when the distribution's CMake and OpenMP packages are both installed.

What happened (include all command output)?

CMake as installed from Homebrew can't find OpenMP as installed from Homebrew, because Homebrew doesn't do anything itself to tell the CMake it ships about the keg-only paths where it installs libomp, and upstream CMake doesn't know to search them.

When installing CMake and OpenMP, I get this log that warns me that OpenMP is keg-only:

==> Downloading https://formulae.brew.sh/api/formula.jws.json
==> Downloading https://formulae.brew.sh/api/cask.jws.json
==> Fetching downloads for: cmake and libomp
==> Downloading https://ghcr.io/v2/homebrew/core/cmake/manifests/4.1.1
Already downloaded: /Users/anovak/Library/Caches/Homebrew/downloads/24af49775f385da509b31f6d086bd8d16010984c687b5b0c3935a8fee72a1ad8--cmake-4.1.1.bottle_manifest.json
==> Downloading https://ghcr.io/v2/homebrew/core/libomp/manifests/21.1.0
Already downloaded: /Users/anovak/Library/Caches/Homebrew/downloads/3acc30bed0aae3c6339b5f7aab8756262a65c507c01924e19bb0bf6aac74b9d2--libomp-21.1.0.bottle_manifest.json
==> Fetching cmake
==> Downloading https://ghcr.io/v2/homebrew/core/cmake/blobs/sha256:15af42c171e6914039f7188154145d20484a565bb43b308be9efbdcc893884af
Already downloaded: /Users/anovak/Library/Caches/Homebrew/downloads/73012cfaa683b9a32d96c98fde8bdd74691e0870c4dba87db58912709f3db05d--cmake--4.1.1.arm64_sequoia.bottle.tar.gz
==> Fetching libomp
==> Downloading https://ghcr.io/v2/homebrew/core/libomp/blobs/sha256:0ceba5785dc521e24a27be3a17f82d8712fc0bbf31350b89f20df1cccfc7a37f
Already downloaded: /Users/anovak/Library/Caches/Homebrew/downloads/9127ada69c658dfc30c695b41ea02f046642a4a3b7698e8bf061df5ff74f3936--libomp--21.1.0.arm64_sequoia.bottle.tar.gz
==> Pouring cmake--4.1.1.arm64_sequoia.bottle.tar.gz
==> Caveats
To install the CMake documentation, run:
  brew install cmake-docs
==> Summary
🍺  /opt/homebrew/Cellar/cmake/4.1.1: 3,913 files, 58.6MB
==> Running `brew cleanup cmake`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
==> Pouring libomp--21.1.0.arm64_sequoia.bottle.tar.gz
==> Caveats
libomp is keg-only, which means it was not symlinked into /opt/homebrew,
because it can override GCC headers and result in broken builds.

For compilers to find libomp you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"
==> Summary
🍺  /opt/homebrew/Cellar/libomp/21.1.0: 9 files, 1.7MB
==> Running `brew cleanup libomp`...
==> No outdated dependents to upgrade!
==> Caveats
Emacs Lisp files have been installed to:
  /opt/homebrew/share/emacs/site-lisp/cmake
==> cmake
To install the CMake documentation, run:
  brew install cmake-docs
==> libomp
libomp is keg-only, which means it was not symlinked into /opt/homebrew,
because it can override GCC headers and result in broken builds.

For compilers to find libomp you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/libomp/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/libomp/include"

Here's an example output for a failed CMake project configuration that encounters this problem:

-- The C compiler identification is AppleClang 17.0.0.17000013
-- The CXX compiler identification is AppleClang 17.0.0.17000013
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
CMake Error at /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:227 (message):
  Could NOT find OpenMP_C (missing: OpenMP_C_FLAGS OpenMP_C_LIB_NAMES)
Call Stack (most recent call first):
  /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:591 (_FPHSA_FAILURE_MESSAGE)
  /opt/homebrew/share/cmake/Modules/FindOpenMP.cmake:652 (find_package_handle_standard_args)
  CMakeLists.txt:3 (find_package)


-- Configuring incomplete, errors occurred!

Even setting the environment variables recommended by Homebrew does not enable Homebrew's CMake to find and use Homebrew's OpenMP:

[anovak@swords test]% LDFLAGS="-L/opt/homebrew/opt/libomp/lib" CPPFLAGS="-I/opt/homebrew/opt/libomp/include" cmake .
CMake Error at /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:227 (message):
  Could NOT find OpenMP_C (missing: OpenMP_C_FLAGS OpenMP_C_LIB_NAMES)
Call Stack (most recent call first):
  /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:591 (_FPHSA_FAILURE_MESSAGE)
  /opt/homebrew/share/cmake/Modules/FindOpenMP.cmake:652 (find_package_handle_standard_args)
  CMakeLists.txt:3 (find_package)


-- Configuring incomplete, errors occurred!

What did you expect to happen?

I expect CMake as installed from Homebrew to be able to find and use OpenMP installed from Homebrew in the default out-of-the-box configuration.

I expect this to work *without( the user needing to determine extra -D arguments they need to pass to CMake to tell it where to find OpenMP, and without the CMake-based project needing special logic in its CMakeLists.txt to ask about or guess Homebrew's OpenMP installation path.

Step-by-step reproduction instructions (by running brew commands)

To reproduce this, first have the Command Line Tools installed, so you actually have a compiler. Then you can set up a trivial CMake project and install the two packages:

brew install cmake libomp
mkdir test
cd test
cat >CMakeLists.txt <<'EOF'
cmake_minimum_required(VERSION 4.1)
project(ProjectName)
find_package(OpenMP REQUIRED)
EOF


Then if you:

cmake .


You will get a project configuration failure because OpenMP is not found.

[carlocab]

I expect CMake as installed from Homebrew to be able to find and use OpenMP installed from Homebrew in the default out-of-the-box configuration.

I don't think this is possible without breaking things, unfortunately. This almost amounts to making libomp not-keg-only, but, as the formula explains: that breaks builds.

[adamnovak]

I'm imagining that the right behavior would be that, when Homebrew's libomp is the "right answer" for a CMake find_package(OpenMP) call, it gets found, whereas when it isn't (like if the build is being done on a compiler which isn't compatible with Homebrew's libomp), then it isn't selected.

I'm envisioning a solution (which might really belong upstream in CMake itself?) where CMake gets taught about the keg-only install locations that Homebrew uses, and adds them to its package search path. I think this makes sense because "search common plausible installation locations to try and find this library" is more or less what find_package() is meant to do.

(In particular: projects that don't use CMake, and projects that use CMake but don't currently ask for and fail to receive a result for find_package(OpenMP) or find_package(OpenMP REQUIRED), would see the current behavior.)

I'm not sure how CMake manages cases where some installed libraries are compatible with only some installed compilers; I could see it being hard to get out of a situation where an optional dependency appears to be available (because CMake knows about the place it is installed) but in practice should not be used because it isn't compatible with the project's chosen compiler. So those builds might break if they relied on the OpenMP appearing to be unavailable during CMake configuration, and if there's no way to maintain that situation when CMake is going to use GCC.

If we can't figure out how to make it work out of the box without breaking some configurations, what is the recommended approach for building CMake projects that use OpenMP on top of a Homebrew environment, when the user knows they're going to be using a compiler that's compatible? Because the suggested configuration that the libomp package describes isn't enough to make it work. Maybe the message libomp prints needs to be extended with more suggestions?

[ZhongRuoyu]

Normally, you can have your desired out-of-the-box OpenMP detection if the compiler toolchain does include libomp's directory in its standard link locations where it looks for libraries. This is the case for Debian GCC, Debian Clang, Homebrew Clang ¹, but not the case for Apple Clang because it doesn't come with OpenMP (see #112107 (comment)). Making CMake aware of this seems to be out of Homebrew's scope because there doesn't seem to be anything actionable on our side.

If we can't figure out how to make it work out of the box without breaking some configurations, what is the recommended approach for building CMake projects that use OpenMP on top of a Homebrew environment, when the user knows they're going to be using a compiler that's compatible?

Set -DOPENMP_ROOT="$(brew --prefix libomp)".

Maybe the message libomp prints needs to be extended with more suggestions?

Speaking of caveats, it seems CMake does not respect CPPFLAGS which is supposed to be passed to the C preprocessor. It does work if you, instead of setting CPPFLAGS=-I/opt/homebrew/opt/libomp/include, set CFLAGS="-I/opt/homebrew/opt/libomp/include" CXXFLAGS="-I/opt/homebrew/opt/libomp/include".

Footnotes

1. Special mention: you don't need extra args if you set -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" because Homebrew's LLVM does come with OpenMP. ↩

[carlocab]

I'm imagining that the right behavior would be that, when Homebrew's libomp is the "right answer" for a CMake find_package(OpenMP) call, it gets found, whereas when it isn't (like if the build is being done on a compiler which isn't compatible with Homebrew's libomp), then it isn't selected.

I'm envisioning a solution (which might really belong upstream in CMake itself?) where CMake gets taught about the keg-only install locations that Homebrew uses, and adds them to its package search path. I think this makes sense because "search common plausible installation locations to try and find this library" is more or less what find_package() is meant to do.

I'm afraid that this is categorically not the right behaviour.

The point of keg-only formulae is that they should not be found unless explicitly opted into, so any mechanism that enables them to be automatically found would break the very concept of keg-only formulae.

If we can't figure out how to make it work out of the box without breaking some configurations, what is the recommended approach for building CMake projects that use OpenMP on top of a Homebrew environment, when the user knows they're going to be using a compiler that's compatible? Because the suggested configuration that the libomp package describes isn't enough to make it work. Maybe the message libomp prints needs to be extended with more suggestions?

Try setting -DCMAKE_PREFIX_PATH=$(brew --prefix libomp) or export CMAKE_PREFIX_PATH=$(brew --prefix libomp).

Or see one of @ZhongRuoyu's suggestions above.

[adamnovak]

Those are some useful and short ways of hooking up particular Homebrew-provided libraries to Homebrew's CMake for particular builds.

As a developer of software that builds with CMake and depends on OpenMP, I could write my software's installation instructions like:

1. Install dependencies. On Mac, do xcode-select --install and brew install libomp. On Ubuntu, do XXXXX
2. Build the project. On Mac, do mkdir build && cd build && cmake .. -DOPENMP_ROOT="$(brew --prefix libomp)" && make. On Linux, do mkdir build && cd build && cmake .. && make.

This works OK, but my build command ends up differing by platform and mentioning every keg-only library I or my transitive dependencies need, which might be a lot. (This project over here seems to use six.)

So then I as the project developer, to make it Just Work and simplify what I am asking of my users, am motivated to write some code in my CMakeLists.txt to automatically check what I know is likely to be the most common install location on MacOS for my project's dependencies: the Homebrew keg-only installation locations.

Is that the wrong approach for me to be taking as a downstream project developer? Or when I'm wearing that hat, am I meant to be the person "explicitly opting in" to use the keg-only formulae on the end-user's behalf?

[ZhongRuoyu]

As @carlocab mentioned, the whole point of having keg-only formulae is that they are not expected to be automatically discovered. My suggestion is that you add something like this your 2nd step:

If you are using Apple Clang, you need to install libomp separately. If you install libomp with Homebrew, you also need to pass -DOPENMP_ROOT="$(brew --prefix libomp)" to your cmake invocation.

I phrased it that way because you don't know what the user's configuration is. For example, they may be building with Homebrew Clang, in which case they don't need a separate libomp at all. But ultimately, it's really up to you as a downstream developer to decide what works best for your users.

You may be inspired by how some other projects do this.