From 7fd736e23c671f4d4e6e61dcd299e8aefaa833b2 Mon Sep 17 00:00:00 2001
From: Bosco <gowxxink@gmail.com>
Date: Sat, 18 May 2024 02:10:57 +0800
Subject: [PATCH] docs: Update macOS development docs with dispatch.h error
 solution (#11986)

### Title
Update macOS Development Documentation with Dispatch.h Error Solution

### Description
This PR updates the macOS development documentation to include a
solution for the `dispatch/dispatch.h` file not found error. This error
is encountered during local development when using the `cargo run`
command. The documentation now includes steps to ensure the Xcode
command line tools are properly installed and set, and instructions to
set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable.

### Changes
- Added troubleshooting section for `dispatch/dispatch.h` error in
`development/macos.md`.

### Related Issues
- Closes [#11963](https://github.com/zed-industries/zed/issues/11963)

### Testing Instructions
1. Follow the steps in the updated `development/macos.md` to configure
your environment.
2. Run `cargo clean` and `cargo run` to ensure the build completes
successfully.

Release Notes:

- N/A
---
 docs/src/development/macos.md | 39 +++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/src/development/macos.md b/docs/src/development/macos.md
index 3120607f28..6168cb7a3d 100644
--- a/docs/src/development/macos.md
+++ b/docs/src/development/macos.md
@@ -83,3 +83,42 @@ Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
 ### Cargo errors claiming that a dependency is using unstable features
 
 Try `cargo clean` and `cargo build`.
+
+### Error: 'dispatch/dispatch.h' file not found
+
+If you encounter an error similar to:
+
+```bash
+src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
+
+Caused by:
+  process didn't exit successfully
+
+  --- stdout
+  cargo:rustc-link-lib=framework=System
+  cargo:rerun-if-changed=src/platform/mac/dispatch.h
+  cargo:rerun-if-env-changed=TARGET
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
+```
+
+This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
+
+```bash
+xcode-select --install
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
+
+```bash
+export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
+```
+
+Then clean and rebuild the project:
+
+```bash
+cargo clean
+cargo run
+```