Add documentation about macOS to Developer Docs (#3415)

docs/mdbook/src/SUMMARY.md

@@ -2,24 +2,23 @@
 
 [Introduction](./introduction.md)
 
-- [Platforms](./platforms.md)
+- [Platforms](./platforms/README.md)
+  - [Android](./platforms/android/README.md)
+    - [Tests](./platforms/android/android-tests.md)
+    - [Documentation](./platforms/android/android-documentation.md)
+    - [Benchmark](./platforms/android/benchmark.md)
+    - [Release](./platforms/android/release.md)
+  - [iOS](./platforms/ios/README.md)
+    - [Tests](./platforms/ios/ios-tests.md)
+    - [Documentation](./platforms/ios/ios-documentation.md)
+    - [Release](./platforms/ios/release.md)
+    - [Development Apps](./platforms/ios/dev-apps.md)
+  - [macOS](./platforms/macos/README.md)
 
 - [Release Policy](./release-policy.md)
 
 - [Render Tests](./render-tests.md)
 
-- [Android](./android/README.md)
-  - [Tests](./android/android-tests.md)
-  - [Documentation](./android/android-documentation.md)
-  - [Benchmark](./android/benchmark.md)
-  - [Release](android/release.md)
-
-- [iOS](./ios/README.md)
-  - [Tests](ios/ios-tests.md)
-  - [Documentation](ios/ios-documentation.md)
-  - [Release](ios/release.md)
-  - [Development Apps](ios/dev-apps.md)
-
 - [Design](./design/README.md)
   - [Ten Thousand Foot View](design/ten-thousand-foot-view.md)
   - [Coordinate System](design/coordinate-system.md)

docs/mdbook/src/platforms/macos/README.md

@@ -0,0 +1,98 @@
+# macOS
+
+MapLibre Native can be built for macOS. This is mostly used for development.
+
+> [!NOTE]
+> There are some [AppKit](https://developer.apple.com/documentation/appkit) APIs for macOS the source tree. However those are not actively maintained. There is an [discussion](https://github.com/maplibre/maplibre-native/discussions/3414) on whether we should remove this code.
+
+## File Structure
+
+| Path                        | Description                                                              |
+|-----------------------------|--------------------------------------------------------------------------|
+| `platform/darwin`          | Shared code between macOS and iOS                                        |
+| `platform/darwin/core`     | iOS/macOS specific implementations for interfaces part of the MapLibre Native C++ Core |
+| `platform/macos`           | macOS specific code                                                      |
+| `platform/macos/app`       | AppKit based example app                                                 |
+
+## Getting Started
+
+Clone the repo:
+
+```sh
+git clone --recurse-submodules git@github.com:maplibre/maplibre-native.git
+```
+
+Make sure the following Homebrew packages are installed:
+
+```sh
+brew install bazelisk webp libuv webp icu4c jpeg-turbo glfw
+brew link icu4c --force
+```
+
+You can get started building the project for macOS using either Bazel or CMake.
+
+## Bazel
+
+Configure Bazel (optional):
+
+```sh
+cp platform/darwin/bazel/example_config.bzl platform/darwin/bazel/config.bzl
+```
+
+Run the GLFW app with a style of your choice:
+
+```sh
+bazel run --//:renderer=metal //platform/glfw:glfw_app -- --style https://sgx.geodatenzentrum.de/gdz_basemapworld_vektor/styles/bm_web_wld_col.json
+```
+
+Create and open Xcode project:
+
+```sh
+bazel run //platform/macos:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal"
+xed platform/macos/MapLibre.xcodeproj
+```
+
+## CMake
+
+Configure CMake:
+
+```sh
+cmake --preset macos
+```
+
+Build and run the render tests:
+
+```sh
+cmake --build build-macos --target mbgl-render-test-runner
+build-macos/mbgl-render-test-runner --manifestPath=metrics/macos-xcode11-release-style.json
+```
+
+Build and run the C++ Tests:
+
+```sh
+cmake --build build-macos --target mbgl-test-runner
+npm install && node test/storage/server.js  # required test server
+# in another terminal
+build-macos/mbgl-test-runner
+```
+
+Create and open an Xcode project with CMake:
+
+```sh
+cmake --preset macos-xcode
+xed build-macos-xcode/MapLibre\ Native.xcodeproj
+```
+
+Configure project for Vulkan (make sure [MoltenVK](https://github.com/KhronosGroup/MoltenVK) is installed):
+
+```sh
+cmake --preset macos-vulkan
+```
+
+Build and run `mbgl-render` (simple command line utility for rendering maps):
+
+```sh
+cmake --build build-macos-vulkan --target mbgl-render
+build-macos-vulkan/bin/mbgl-render -z 7 -x -74 -y 41 --style https://americanamap.org/style.json
+open out.png
+```