Xcode + Homebrew GCC fix after macOS upgrade

Readme.md

Sometimes upon updating macOS, the Xcode SDK becomes incompatible with Homebrew GCC. Sometimes the problem is that the "Command Line Tools" are too new for the Homebrew GCC. Sometimes the problem is the the Xcode SDK hasn't installed the latest "command line tools".

Note, the examples below use "g++-15" -- substitute the appropriate GCC version on your macOS.

Ensure Command Line Tools matches macOS, Xcode and Homebrew Config

Determine the Xcode version used by Homebrew (and hence GCC) by looking for the line starting with "Xcode: " in the output of Homebrew config utility:

brew config | grep Xcode

Print the default Xcode version:

pkgutil --pkg-info com.apple.pkg.Xcode

Print the Xcode Command Line Tools version:

pkgutil --pkg-info com.apple.pkg.CLTools_Executables

Note that the Xcode version in general is different from the macOS version. The SDK version is the same as the macOS version. Determine the macOS version by

sw_vers -productVersion

Determine the default Command Line Tools version, and other versions available by

ls -l /Library/Developer/CommandLineTools/SDKs

Check that Xcode has completed the upgrade by:

xcodebuild -checkFirstLaunchStatus

xcodebuild -runFirstLaunch

Check that the Command Line Tools of the Xcode version are installed by

softwareupdate --list

If needed, update the Command Line Tools from the softwareupdate --list command like (substitute the appropriate version number):

softwareupdate -i "Command Line Tools for Xcode-26.4"

where "26.4" is the same version as the brew config | grep Xcode

Open the Xcode App itself (just to the first splash welcome screen) to accept the license and complete the installation.

If this still doesn't work to get the Command Line Tools to match the Xcode version, then download the Command Line Tools for the Xcode version and install them manually.

If these fail, try the Workaround below to specify the SDKROOT. If these all fail, then consider reinstalling Homebrew--this is uncommonly necessary after a macOS update.

Test compatibility

Homebrew GCC / Gfortran and Xcode SDK incompatibilites may be revealed in this simple project. If the

CXX=g++-15 cmake -Bbuild --fresh

cmake --build build

Workaround with SDKROOT set to older Xcode SDK

The workaround is to specify SDKROOT so that CMake uses the compatible SDK with GCC, until Homebrew updates its platform environment. Create a file ~/gcc.sh and source ~/gcc.sh to use GCC:

export CC=gcc-15 CXX=g++-15 FC=gfortran-15

export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk/

In general in my projects I have CMake print CMAKE_OSX_SYSROOT so when users run into an issue I can help them more quickly.

Configure output with SDKROOT Workaround

CXX=g++-15 SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk/ cmake -Bbuild --fresh

-- The CXX compiler identification is GNU 15.2.0
...
-- CMAKE_OSX_SYSROOT /Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk
-- OS_NAME: macOS
-- OS_VERSION: 25E246
-- OS_RELEASE: 26.4
-- OS_PLATFORM: arm64

GCC + Xcode build errors

Build errors if using CMake with Xcode incompatible with Homebrew GCC:

/opt/homebrew/opt/gcc/bin/g++-15   -O2 -g -DNDEBUG -arch arm64 -fdiagnostics-color=always -MD -MT CMakeFiles/main.dir/main.cpp.o -MF CMakeFiles/main.dir/main.cpp.o.d -o CMakeFiles/main.dir/main.cpp.o -c main.cpp
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk/usr/include/mach/message.h:78,
                 from /Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk/usr/include/mach/arm/thread_status.h:40,
                 from /Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk/usr/include/mach/machine/thread_status.h:35,
                 from /Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk/usr/include/mach-o/loader.h:52,
                 from main.cpp:4:
/Library/Developer/CommandLineTools/SDKs/MacOSX26.sdk/usr/include/mach/message.h:299:1: error: expected constructor, destructor, or type conversion before '(' token
  299 | xnu_static_assert_struct_size(mach_msg_type_descriptor_t, 12);
      | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~

or

/opt/homebrew/bin/g++-14   -O3 -DNDEBUG -arch arm64 -MD -MT CMakeFiles/main.dir/main.cpp.o -MF CMakeFiles/main.dir/main.cpp.o.d -o CMakeFiles/main.dir/main.cpp.o

/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk/usr/include/mach/arm/_structs.h:627:35: error: expected primary-expression before 'unsigned'
  627 | } __attribute__((aligned(_Alignof(unsigned int))));
      |

or

/opt/homebrew/bin/g++-14   -O3 -DNDEBUG -arch arm64 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.0.sdk -MD -MT CMakeFiles/main.dir/main.cpp.o -MF CMakeFiles/main.dir/main.cpp.o.d -o CMakeFiles/main.dir/main.cpp.o

/opt/homebrew/Cellar/gcc/14.2.0/lib/gcc/current/gcc/aarch64-apple-darwin23/14/include-fixed/stdio.h:83:8: error: 'FILE' does not name a type
   83 | extern FILE *__stdinp;
      |        ^~~~
/opt/homebrew/Cellar/gcc/14.2.0/lib/gcc/current/gcc/aarch64-apple-darwin23/14/include-fixed/stdio.h:81:1: note: 'FILE' is defined in header '<cstdio>'; this is probably fixable by adding '#include <cstdio>'
   80 | #include <sys/_types/_seek_set.h>
  +++ |+#include <cstdio>
   81 |

Regular command line is OK

g++-14 main.cpp -v

works, output ends with

 /opt/homebrew/Cellar/gcc/14.2.0/bin/../libexec/gcc/aarch64-apple-darwin23/14/collect2 -demangle -syslibroot /Library/Developer/CommandLineTools/SDKs/MacOSX14.sdk/ -dynamic -arch arm64 -platform_version macos 15.0.0 0.0 -o a.out -L/opt/homebrew/Cellar/gcc/14.2.0/bin/../lib/gcc/current/gcc/aarch64-apple-darwin23/14 -L/opt/homebrew/Cellar/gcc/14.2.0/bin/../lib/gcc/current/gcc -L/opt/homebrew/Cellar/gcc/14.2.0/bin/../lib/gcc/current/gcc/aarch64-apple-darwin23/14/../../.. -lemutls_w -lheapt_w /var/folders/dh/k7c2gppn12v3w0plnf_xz94c0000gn/T//ccarxhZd.o -lstdc++ -lgcc -lSystem -no_compact_unwind -rpath @loader_path -rpath /opt/homebrew/Cellar/gcc/14.2.0/lib/gcc/current/gcc/aarch64-apple-darwin23/14 -rpath /opt/homebrew/Cellar/gcc/14.2.0/lib/gcc/current/gcc -rpath /opt/homebrew/Cellar/gcc/14.2.0/lib/gcc/current

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)

project(min LANGUAGES CXX Fortran)

set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
# set OFF if not using C++ modules, or it can trip similar compiler errors due to "-fmodules-ts" flags auto-added when ON.

message(STATUS "CMAKE_OSX_SYSROOT ${CMAKE_OSX_SYSROOT}")

foreach(i IN ITEMS OS_NAME OS_VERSION OS_RELEASE OS_PLATFORM)
  cmake_host_system_information(RESULT ${i} QUERY ${i})
  message(STATUS "${i}: ${${i}}")
endforeach()

add_executable(main main.cpp)

file(GENERATE OUTPUT .gitignore CONTENT "*")

main.cpp

#include <iostream>

// sometimes this header causes issues, that's a bug with Homebrew vs. Xcode version
#include <mach-o/loader.h>

int main(){ return 0; }

It broke in the same way for me on gcc@12. This helped me out. Thanks!

Is there an original issue from Homebrew/GCC somewhere? If so, it would be helpful to link it - I landed here by searching for a general issue, not specifically connected with the scivision project

@PKua007 Most likely this is the current issue on iains gcc-14 branch.
iains/gcc-14-branch#11

Not sure however who will take care to bring this to Homebrew as soon as fixed.

Was stuck on this for hours - the export commands you mentioned resolved it! A million thanks

Thank you for pointing this out and for the guidance.

I encountered the same issue while trying to download and build the gtest dependency using Conan on macOS 26 with Xcode Command Line Tools 26.4 installed. Unfortunately, AI tools kept misguiding me, and after a long search online, this page was the only place where I could finally find a relevant discussion. It seems there is still some time before AI can fully replace software developers 😄

When I tried to build the dependencies using the following command:

conan install . --build=missing -pr:h=hb_gcc15 -pr:b=default

I was getting an error for xnu_static_assert_struct_size, xnu_static_assert_struct_size_kernel_user and xnu_static_assert_struct_size_kernel_user64_user32 functions:

gtest/1.17.0: Running CMake.build()  
gtest/1.17.0: RUN: cmake --build ".../build/Release" -- -j10  
[ 12%] Building CXX object googletest/CMakeFiles/gtest.dir/src/gtest-all.cc.o  
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/mach/message.h:78,  
...  
/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/mach/message.h:299:1:  
error: expected constructor, destructor, or type conversion before '(' token  
xnu_static_assert_struct_size(mach_msg_type_descriptor_t, 12);
...

I was able to resolve this issue by adding the following lines to the Conan profile I was using:

[conf]  
tools.apple:sdk_path=/Library/Developer/CommandLineTools/SDKs/MacOSX15.sdk