From 3eba74d1ac7efbbbe8cc8882db64cd6c0a1b0a37 Mon Sep 17 00:00:00 2001 From: Bart Louwers Date: Mon, 21 Apr 2025 18:47:21 +0200 Subject: [PATCH] Add documentation about macOS to Developer Docs (#3415) --- CMakePresets.json | 35 +++++-- README.md | 4 +- docs/mdbook/src/SUMMARY.md | 25 +++-- .../src/{platforms.md => platforms/README.md} | 0 .../src/{ => platforms}/android/README.md | 0 .../android/android-documentation.md | 0 .../{ => platforms}/android/android-tests.md | 0 .../src/{ => platforms}/android/benchmark.md | 0 .../src/{ => platforms}/android/release.md | 0 docs/mdbook/src/{ => platforms}/ios/README.md | 0 .../src/{ => platforms}/ios/dev-apps.md | 0 .../{ => platforms}/ios/ios-documentation.md | 0 .../src/{ => platforms}/ios/ios-tests.md | 0 .../mdbook/src/{ => platforms}/ios/release.md | 0 docs/mdbook/src/platforms/macos/README.md | 98 +++++++++++++++++++ platform/android/README.md | 2 +- platform/ios/README.md | 2 +- platform/macos/README.md | 33 +------ 18 files changed, 141 insertions(+), 58 deletions(-) rename docs/mdbook/src/{platforms.md => platforms/README.md} (100%) rename docs/mdbook/src/{ => platforms}/android/README.md (100%) rename docs/mdbook/src/{ => platforms}/android/android-documentation.md (100%) rename docs/mdbook/src/{ => platforms}/android/android-tests.md (100%) rename docs/mdbook/src/{ => platforms}/android/benchmark.md (100%) rename docs/mdbook/src/{ => platforms}/android/release.md (100%) rename docs/mdbook/src/{ => platforms}/ios/README.md (100%) rename docs/mdbook/src/{ => platforms}/ios/dev-apps.md (100%) rename docs/mdbook/src/{ => platforms}/ios/ios-documentation.md (100%) rename docs/mdbook/src/{ => platforms}/ios/ios-tests.md (100%) rename docs/mdbook/src/{ => platforms}/ios/release.md (100%) create mode 100644 docs/mdbook/src/platforms/macos/README.md diff --git a/CMakePresets.json b/CMakePresets.json index 18103ffa0..2f40204ad 100644 --- a/CMakePresets.json +++ b/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", - "displayName": "macOS", - "generator": "Ninja", - "binaryDir": "${sourceDir}/build-macos-vulkan", - "cacheVariables": { - "CMAKE_SYSTEM_NAME": "Darwin", - "CMAKE_CXX_COMPILER_LAUNCHER": "ccache", - "MLN_WITH_VULKAN": "ON", - "MLN_WITH_OPENGL": "OFF" - } + "name": "macos-vulkan-xcode", + "displayName": "macOS Vulkan (Xcode)", + "generator": "Xcode", + "binaryDir": "${sourceDir}/build-macos-vulkan-xcode", + "inherits": "macos-vulkan" }, { "name": "macos-node", diff --git a/README.md b/README.md index 113f6b97c..76b121e48 100644 --- a/README.md +++ b/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 diff --git a/docs/mdbook/src/SUMMARY.md b/docs/mdbook/src/SUMMARY.md index d1426f081..1817ed77b 100644 --- a/docs/mdbook/src/SUMMARY.md +++ b/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) diff --git a/docs/mdbook/src/platforms.md b/docs/mdbook/src/platforms/README.md similarity index 100% rename from docs/mdbook/src/platforms.md rename to docs/mdbook/src/platforms/README.md diff --git a/docs/mdbook/src/android/README.md b/docs/mdbook/src/platforms/android/README.md similarity index 100% rename from docs/mdbook/src/android/README.md rename to docs/mdbook/src/platforms/android/README.md diff --git a/docs/mdbook/src/android/android-documentation.md b/docs/mdbook/src/platforms/android/android-documentation.md similarity index 100% rename from docs/mdbook/src/android/android-documentation.md rename to docs/mdbook/src/platforms/android/android-documentation.md diff --git a/docs/mdbook/src/android/android-tests.md b/docs/mdbook/src/platforms/android/android-tests.md similarity index 100% rename from docs/mdbook/src/android/android-tests.md rename to docs/mdbook/src/platforms/android/android-tests.md diff --git a/docs/mdbook/src/android/benchmark.md b/docs/mdbook/src/platforms/android/benchmark.md similarity index 100% rename from docs/mdbook/src/android/benchmark.md rename to docs/mdbook/src/platforms/android/benchmark.md diff --git a/docs/mdbook/src/android/release.md b/docs/mdbook/src/platforms/android/release.md similarity index 100% rename from docs/mdbook/src/android/release.md rename to docs/mdbook/src/platforms/android/release.md diff --git a/docs/mdbook/src/ios/README.md b/docs/mdbook/src/platforms/ios/README.md similarity index 100% rename from docs/mdbook/src/ios/README.md rename to docs/mdbook/src/platforms/ios/README.md diff --git a/docs/mdbook/src/ios/dev-apps.md b/docs/mdbook/src/platforms/ios/dev-apps.md similarity index 100% rename from docs/mdbook/src/ios/dev-apps.md rename to docs/mdbook/src/platforms/ios/dev-apps.md diff --git a/docs/mdbook/src/ios/ios-documentation.md b/docs/mdbook/src/platforms/ios/ios-documentation.md similarity index 100% rename from docs/mdbook/src/ios/ios-documentation.md rename to docs/mdbook/src/platforms/ios/ios-documentation.md diff --git a/docs/mdbook/src/ios/ios-tests.md b/docs/mdbook/src/platforms/ios/ios-tests.md similarity index 100% rename from docs/mdbook/src/ios/ios-tests.md rename to docs/mdbook/src/platforms/ios/ios-tests.md diff --git a/docs/mdbook/src/ios/release.md b/docs/mdbook/src/platforms/ios/release.md similarity index 100% rename from docs/mdbook/src/ios/release.md rename to docs/mdbook/src/platforms/ios/release.md diff --git a/docs/mdbook/src/platforms/macos/README.md b/docs/mdbook/src/platforms/macos/README.md new file mode 100644 index 000000000..251f617fd --- /dev/null +++ b/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 +``` diff --git a/platform/android/README.md b/platform/android/README.md index 029a598ee..1e8854b64 100644 --- a/platform/android/README.md +++ b/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. diff --git a/platform/ios/README.md b/platform/ios/README.md index 51d906cc2..a8d8889cd 100644 --- a/platform/ios/README.md +++ b/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. diff --git a/platform/macos/README.md b/platform/macos/README.md index d4b27fe0e..8cb6f2479 100644 --- a/platform/macos/README.md +++ b/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: - -```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. +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.