Describe the issue linked to the documentation
The current documentation in doc/developers/advanced_installation.rst under the "macOS compilers from Homebrew" section provides environment variable examples using the path /usr/local/opt/libomp/. While this is correct for Intel-based Macs, Homebrew on Apple Silicon (arm64) Macs installs packages, including libomp, to /opt/homebrew/opt/libomp/.
This can lead to confusion and build issues for users on Apple Silicon hardware who follow the documentation to install from source.
The documentation will improve from mentioning that libomp is often installed as "keg-only" by Homebrew, which is why explicitly setting these paths is necessary. Homebrew's own output (brew info libomp) often provides guidance on the necessary CPPFLAGS and LDFLAGS.
Suggest a potential alternative/fix
The documentation could be updated to:
- Mention the different Homebrew base paths for Intel (
/usr/local) and Apple Silicon (/opt/homebrew).
- Update the example environment variable settings to reflect the
/opt/homebrew/opt/libomp path as a common case for Apple Silicon, or provide instructions for users to identify and use the correct path for their system.
- Optionally, We could briefly explain the "keg-only" nature of
libomp from Homebrew and how it relates to needing these environment variables.
Describe the issue linked to the documentation
The current documentation in
doc/developers/advanced_installation.rstunder the "macOS compilers from Homebrew" section provides environment variable examples using the path/usr/local/opt/libomp/. While this is correct for Intel-based Macs, Homebrew on Apple Silicon (arm64) Macs installs packages, includinglibomp, to/opt/homebrew/opt/libomp/.This can lead to confusion and build issues for users on Apple Silicon hardware who follow the documentation to install from source.
The documentation will improve from mentioning that
libompis often installed as "keg-only" by Homebrew, which is why explicitly setting these paths is necessary. Homebrew's own output (brew info libomp) often provides guidance on the necessaryCPPFLAGSandLDFLAGS.Suggest a potential alternative/fix
The documentation could be updated to:
/usr/local) and Apple Silicon (/opt/homebrew)./opt/homebrew/opt/libomppath as a common case for Apple Silicon, or provide instructions for users to identify and use the correct path for their system.libompfrom Homebrew and how it relates to needing these environment variables.