From 039f8d7a197e2bb4c41d46cc3ac2edb0fcc66bfb Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Wed, 5 Feb 2025 10:00:25 +0100
Subject: [PATCH] Add a troubleshooting section to Compiling for macOS/iOS

---
 .../compiling/compiling_for_ios.rst           | 26 +++++++++++++++++++
 .../compiling/compiling_for_macos.rst         | 26 +++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/contributing/development/compiling/compiling_for_ios.rst b/contributing/development/compiling/compiling_for_ios.rst
index 7d5fcbe5929..d9512d1cfa7 100644
--- a/contributing/development/compiling/compiling_for_ios.rst
+++ b/contributing/development/compiling/compiling_for_ios.rst
@@ -86,3 +86,29 @@ Run
 
 To run on a device or simulator, follow these instructions:
 :ref:`doc_exporting_for_ios`.
+
+Troubleshooting
+---------------
+
+Fatal error: 'cstdint' file not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you get a compilation error of this form early on, it's likely because
+the Xcode command line tools installation needs to be repaired after
+a macOS or Xcode update:
+
+::
+
+    ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
+    45 | #include <cstdint>
+       |          ^~~~~~~~~
+
+Run these two commands to reinstall Xcode command line tools
+(enter your administrator password as needed):
+
+::
+
+    sudo rm -rf /Library/Developer/CommandLineTools
+    sudo xcode-select --install
+
+If it still does not work, try updating Xcode from the Mac App Store and try again.
diff --git a/contributing/development/compiling/compiling_for_macos.rst b/contributing/development/compiling/compiling_for_macos.rst
index 44e07fd17fe..9f3af62ff72 100644
--- a/contributing/development/compiling/compiling_for_macos.rst
+++ b/contributing/development/compiling/compiling_for_macos.rst
@@ -215,3 +215,29 @@ Now you can compile with SCons like you normally would::
 If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
 
     scons platform=macos osxcross_sdk=darwin15
+
+Troubleshooting
+---------------
+
+Fatal error: 'cstdint' file not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you get a compilation error of this form early on, it's likely because
+the Xcode command line tools installation needs to be repaired after
+a macOS or Xcode update:
+
+::
+
+    ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
+    45 | #include <cstdint>
+       |          ^~~~~~~~~
+
+Run these two commands to reinstall Xcode command line tools
+(enter your administrator password as needed):
+
+::
+
+    sudo rm -rf /Library/Developer/CommandLineTools
+    sudo xcode-select --install
+
+If it still does not work, try updating Xcode from the Mac App Store and try again.