Add documentation about macOS to Developer Docs (#3415)

CMakePresets.json

@@ -28,20 +28,35 @@
         "CMAKE_SYSTEM_NAME": "Darwin",
         "CMAKE_CXX_COMPILER_LAUNCHER": "ccache",
         "MLN_WITH_METAL": "ON",
+        "MLN_WITH_OPENGL": "OFF",
+        "CMAKE_BUILD_TYPE": "Debug"
+      }
+    },
+    {
+      "name": "macos-xcode",
+      "displayName": "macOS (Xcode)",
+      "generator": "Xcode",
+      "binaryDir": "${sourceDir}/build-macos-xcode",
+      "inherits": "macos"
+    },
+    {
+      "name": "macos-vulkan",
+      "displayName": "macOS Vulkan",
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/build-macos-vulkan",
+      "inherits": "macos",
+      "cacheVariables": {
+        "MLN_WITH_VULKAN": "ON",
+        "MLN_WITH_METAL": "OFF",
         "MLN_WITH_OPENGL": "OFF"
       }
     },
     {
-      "name": "macos-vulkan",
+      "name": "macos-vulkan-xcode",
-      "displayName": "macOS",
+      "displayName": "macOS Vulkan (Xcode)",
-      "generator": "Ninja",
+      "generator": "Xcode",
-      "binaryDir": "${sourceDir}/build-macos-vulkan",
+      "binaryDir": "${sourceDir}/build-macos-vulkan-xcode",
-      "cacheVariables": {
+      "inherits": "macos-vulkan"
-        "CMAKE_SYSTEM_NAME": "Darwin",
-        "CMAKE_CXX_COMPILER_LAUNCHER": "ccache",
-        "MLN_WITH_VULKAN": "ON",
-        "MLN_WITH_OPENGL": "OFF"
-      }
     },
     {
       "name": "macos-node",

README.md

@@ -203,7 +203,7 @@ The go-to reference is the [MapLibre Native Developer Documentation](https://map
 
 Open `platform/android` with Android Studio.
 
-More information: [MapLibre Android Developer Guide](https://maplibre.org/maplibre-native/docs/book/android/index.html).
+More information: [MapLibre Android Developer Guide](https://maplibre.org/maplibre-native/docs/book/platforms/android/index.html).
 
 ### iOS
 
@@ -216,7 +216,7 @@ xed platform/ios/MapLibre.xcodeproj
 
 To generate and open the Xcode project.
 
-More information: [MapLibre iOS Developer Guide](https://maplibre.org/maplibre-native/docs/book/ios/index.html).
+More information: [MapLibre iOS Developer Guide](https://maplibre.org/maplibre-native/docs/book/platforms/ios/index.html).
 
 ## Other Platforms
 

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
+```

platform/android/README.md

@@ -18,4 +18,4 @@ Visit [MapLibre Android Dokka Docs](https://maplibre.org/maplibre-native/android
 
 ## Contributing
 
-See the [MapLibre Android Developer Guide](https://maplibre.org/maplibre-native/docs/book/android) for instructions on how to build the project or how to work on the documentation.
+See the [MapLibre Android Developer Guide](https://maplibre.org/maplibre-native/docs/book/platforms/android) for instructions on how to build the project or how to work on the documentation.

platform/ios/README.md

@@ -11,4 +11,4 @@ Embed interactive maps with scalable, customizable vector maps into iOS Applicat
 
 # Contributing
 
-See the [MapLibre iOS Developer Guide](https://maplibre.org/maplibre-native/docs/book/ios) for instructions on how to build the project or how to work on the documentation.
+See the [MapLibre iOS Developer Guide](https://maplibre.org/maplibre-native/docs/book/platforms/ios) for instructions on how to build the project or how to work on the documentation.

platform/macos/README.md

@@ -1,34 +1,5 @@
-# MapLibre Native for macOS
+# MapLibre Native on macOS
 
 [![GitHub Action build status](https://github.com/maplibre/maplibre-native/workflows/macos-ci/badge.svg)](https://github.com/maplibre/maplibre-native/actions/workflows/macos-ci.yml)
 
-Clone the repo:
+Refer to the [MapLibre Native Developer Guide](https://maplibre.org/maplibre-native/docs/book/platforms/macos/index.html) to learn how to build the project for macOS.
-
-```sh
-git clone --recurse-submodules git@github.com:maplibre/maplibre-native.git
-```
-
-Install needed tooling and dependencies with Homebrew. See [macos-ci.yml](https://github.com/maplibre/maplibre-native/blob/main/.github/workflows/macos-ci.yml) for the most up-to-date dependencies.
-
-Optionally configure Bazel:
-
-```sh
-cp platform/darwin/bazel/example_config.bzl platform/darwin/bazel/config.bzl
-```
-
-Create and open Xcode project:
-
-```sh
-bazel run //platform/macos:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal
-xed platform/macos/MapLibre.xcodeproj
-```
-
-Build and run AppKit sample app directly from the command line:
-
-```sh
-bazel run //platform/macos/app:macos_app --//:renderer=metal
-```
-
----
-
-The MapLibre Organization does not officially support the macOS to the same extent as iOS (see [project tiers](https://github.com/maplibre/maplibre/blob/main/PROJECT_TIERS.md)). However, bug reports and pull requests are certainly welcome.