From 04be6ecbd2c245b6f56da340acbb73f7195ab65d Mon Sep 17 00:00:00 2001 From: Bart Louwers Date: Wed, 22 May 2024 00:23:42 +0200 Subject: [PATCH] (Re)move oudated information from .md files (#2416) --- CONTRIBUTING.md | 37 ++----- DEVELOPING.md | 189 --------------------------------- platform/android/DEVELOPING.md | 8 ++ platform/ios/CONTRIBUTING.md | 96 ++++++++++++++++- platform/ios/README.md | 156 ++------------------------- platform/linux/README.md | 35 +++++- 6 files changed, 150 insertions(+), 371 deletions(-) delete mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34af96905..ff9ba2ad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,6 @@ ## Documentation - For a high-level overview of MapLibre Native, check out the [MapLibre Native Markdown Book](https://maplibre.org/maplibre-native/docs/book/). -- See [`DEVELOPING.md`](DEVELOPING.md) for getting started with development. ## Source code checkout @@ -11,7 +10,6 @@ git clone --recurse-submodules https://github.com/maplibre/maplibre-native.git ``` - ## Guidelines If you want to contribute code: @@ -22,15 +20,7 @@ If you want to contribute code: 1. Pull requests are gladly accepted. If there are any changes that developers using one of the platforms should be aware of, please update the **main** section of the relevant `CHANGELOG.md`. -Please note the special instructions for contributing new source code files, asset files, or user-facing strings to MapLibre Native for [iOS](platform/ios/CONTRIBUTING.md), [Android](platform/android/DEVELOPING.md) or [macOS](platform/macos/DEVELOPING.md). - -## Pull Requests - -To run the benchmarks (for Android) include the following line on a PR comment: - -``` -!benchmark android -``` +Please note the special instructions for contributing new source code files, asset files, or user-facing strings to MapLibre Native for [iOS](platform/ios/CONTRIBUTING.md), [Android](platform/android/DEVELOPING.md) or [macOS](platform/macos/README.md). ## Design Proposals @@ -47,25 +37,14 @@ The steps for a Design Proposal are the following: 5. Call a vote on the Design Proposal once discussions have settled. People in favor of your Design Proposal shall approve the pull request. People against your Design Proposal shall comment on the pull request with something like "Rejected". 6. Give the community at least 72 hours to vote. If a majority of the people who voted accept your Proposal, it can be merged. -## Semantic Versioning +[Accepted design proposals](https://github.com/maplibre/maplibre-native/tree/main/design-proposals). -MapLibre uses tags for releases based on [SemVer](https://semver.org) versioning. This is useful for checking out a particular released version for feature enhancements or debugging. +## Pre-commit hooks -You can list available tags by issuing the command `git tag`, then use the result +Install [pre-commit](https://pre-commit.com/) and run -```bash -# 1. Obtain a list of tags, which matches to release versions -git tag - -# 2. Set a convenience variable with the desired TAG -# TAG=android-v9.4.2 -# TAG=android-v9.5.2 -TAG=ios-v5.12.0 -# TAG=ios-v5.12.0-pre.1 - -# 3. Check out a particular TAG -git checkout tags/$TAG -b $TAG - -# 4. build, debug or enhance features based on the tag -# clean, if you need to troubleshoot build dependencies by using `make clean` ``` +pre-commit install +``` + +to install the pre-commit hooks configured in `.pre-commit-config.yml`. diff --git a/DEVELOPING.md b/DEVELOPING.md deleted file mode 100644 index cdbc0ec43..000000000 --- a/DEVELOPING.md +++ /dev/null @@ -1,189 +0,0 @@ -# Developing - - -## Pre-commit hooks - -Install [pre-commit](https://pre-commit.com/) and run - -``` -pre-commit install -``` - -to install the pre-commit hooks configured in `.pre-commit-config.yml`. - -## Render Tests - -To check that the output of the rendering is correct, we compare actual rendered PNGs for simple styles with expected PNGs. The content of the tests used to be stored in the MapLibre GL JS repository, which means that GL JS and Native are mostly pixel-identical in their rendering. - -The directory structure of the render tests looks like: - -``` -metrics/ - integration/ - render-tests/ - / - / - expected.png - style.json -``` - -After the render test run, the folder will also contain an `actual.png` file and a `diff.png` which is the difference between the expected and the actual image. There is a pixel difference threshold value which is used to decide if a render test passed or failed. - -### Building the render test runner - -Run the following on linux to build the render test runner: - -``` -git submodule update --init --recursive --depth 1 - -sudo apt update -sudo apt install ccache cmake ninja-build pkg-config xvfb libcurl4-openssl-dev libglfw3-dev libuv1-dev g++-10 libc++-dev libc++abi-dev libpng-dev libgl1-mesa-dev libgl1-mesa-dri libjpeg-turbo8 libicu-dev libjpeg-dev - -cmake . -B build -G Ninja -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 -cmake --build build -j $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null) -``` - -Also, if your system supports OpenGL ES 3+, you can now execute the GLFW demo with: - -``` -MLN_API_KEY=add_maptiler_api_key_here ./build/platform/glfw/mbgl-glfw -``` - - -### Running the render tests - -On linux, run all render tests with: - -``` -./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json -``` - -Or a single test with: - -``` -./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json --filter "render-tests/fill-visibility/visible" -``` - -On macOS, run all render tests with: - -``` -./build/mbgl-render-test-runner --manifestPath metrics/macos-xcode11-release-style.json -``` - -### Inspecting render test results - -The render test results are summarized in a HTML website located next to the manifest file. For example, running `metrics/linux-clang8-release-style.json` produces a summary at `metrics/linux-clang8-release-style.html`. - ---- - -# MapLibre & C++ - -MapLibre makes use of a common set of C++ files for iOS, macOS, Android, Linux & Qt. See [`platform/default/src/mbgl/`](`platform/default/src/mbgl/`), -or any of the platform make files: - -* [`platform/android/android.cmake`](platform/android/android.cmake) -* [`platform/ios/ios.cmake`](platform/ios/ios.cmake) -* [`platform/linux/linux.cmake`](platform/linux/linux.cmake) -* [`platform/macos/macos.cmake`](platform/macos/macos.cmake) -* [`platform/qt/qt.cmake`](platform/qt/qt.cmake) - -## Debugging - -* Android developers can use [Android Studio](https://developer.android.com/studio/debug) or [`ndk-gdb`](https://developer.android.com/ndk/guides/ndk-gdb) -* iOS developers can use [Xcode](https://developer.apple.com/support/debugging/). See also [Advanced Debugging with Xcode and LLDB](https://developer.apple.com/videos/play/wwdc2018/412/). - -## Static Analysis - -We use [`clang-tidy`](https://clang.llvm.org/extra/clang-tidy/) for static analysis and run it on CI for each pull request. If you want to run it locally use `-DMLN_WITH_CLANG_TIDY=ON` CMake option and just run regular build. For the list of enabled checks please see: - [`.clang-tidy`](.clang-tidy) and [`test/.clang-tidy`](test/.clang-tidy)(for tests we are less strict and use different set of checks). - -## Logging in C++ - -* Android developers can review NDK logging at [developer.android.com/ndk/reference/group/logging](https://developer.android.com/ndk/reference/group/logging). -* iOS developers can review Logging at [developer.apple.com/documentation/os/logging](https://developer.apple.com/documentation/os/logging). - -### Example Cross Compile Logging for Android & iOS - -Add this to your header. - -```c++ -#include -#include -#define LOG_TAG "# MapLibre " - -#ifdef __ANDROID__ - #include -#endif -``` - -Then you can use this sample code which compiles for both Android & Xcode. - -```c++ -std::stringstream message; - -// Set your message to log. -message << LOG_TAG << __FUNCTION__ << " req->resource.url = " << req->resource.url << std::endl; - -// Logs to Xcode console. -std::cout << message.str(); - -#ifdef __ANDROID__ -// Logs to Android Logcat. -__android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, "%s", message.str().c_str()); -#endif -``` - -Which will log the following samples. - -#### Android Sample Logging Output - -> com.mapbox.mapboxsdk.testapp D/# MapLibre: online_file_source.cpp: # MapLibre: online_file_source.cpp activateRequest req->resource.url = https://api.maptiler.com/tiles/v3/tiles.json - -#### Xcode Sample Logging Output - -> MapLibre: online_file_source.cpp activateRequest req->resource.url = https://demotiles.maplibre.org/style.json - ---- - -### Autocomplete with `make` - -MapLibre makes use of several command line tools for local and cloud builds. -To see what targets exist you have to review the `Makefile`, which can be tedious. - -There is a better way with the Zsh. While in a folder with a `Makefile`, you can type `make` followed by hitting `` twice. - - -```zsh -cd platform/android -make android # -# Example, Android make targets starting with `ap` -# apackage aproj - -# ---- - -cd platform/ios -make ios # -# Example, iOS make targets starting with `ios` -# ios ios-lint ios-sanitize ios-test - -make macos # -# Example, macOS make targets starting with `macos` -# macos macos-lint macos-test -``` - -To add this feature add the following to your zsh. - -```zsh -# open ~/.zprofile - -# Autocomplete for `make` when in a directory -zstyle ':completion:*:*:make:*' tag-order 'targets' -autoload -Uz compinit && compinit -``` - -### Kotlin and Java compatibility - -We are moving the Android SDK to Kotlin, which is backward compatible with Java, but if you need a Java version of the Android SDK there is a `before-kotlin-port` tag available. - - - diff --git a/platform/android/DEVELOPING.md b/platform/android/DEVELOPING.md index 90b630ae9..371687071 100644 --- a/platform/android/DEVELOPING.md +++ b/platform/android/DEVELOPING.md @@ -76,3 +76,11 @@ To format all Kotlin source files, use: ``` $ ./gradlew formatKotlin ``` + +## Benchmarks in Pull Request + +To run the benchmarks (for Android) include the following line on a PR comment: + +``` +!benchmark android +``` diff --git a/platform/ios/CONTRIBUTING.md b/platform/ios/CONTRIBUTING.md index 1f4d1bafa..51104902c 100644 --- a/platform/ios/CONTRIBUTING.md +++ b/platform/ios/CONTRIBUTING.md @@ -1,4 +1,94 @@ -# Documentation +# Contributing + +## Downloading Source + +Download the source and install all submodules if you have not already, by running the following from the root of the repository. + +``` +git clone --recurse-submodules git@github.com:maplibre/maplibre-native.git +cd maplibre-native +``` + +## Bazel + +[Bazel](https://bazel.build/) is used for building on iOS. + +You can generate an Xcode project thanks to [rules_xcodeproj](https://github.com/MobileNativeFoundation/rules_xcodeproj) intergration. + +You need to install [bazelisk](https://github.com/bazelbuild/bazelisk), which is a wrapper around Bazel which ensures that the version specified in `.bazelversion` is used. + +``` +brew install bazelisk +``` + +### Creating `config.bzl` + +> [!NOTE] +> This is optional. + +You may want to configure Bazel, otherwise the default config gets used. + +``` +cp platform/darwin/bazel/example_config.bzl platform/darwin/bazel/config.bzl +``` + +You need to set your `BUNDLE_ID_PREFIX` to be unique (ideally use a domain that you own in reverse domain name notation). + +You can keep leave the `APPLE_MOBILE_PROVISIONING_PROFILE_NAME` alone. + +Set the Team ID to the Team ID of your Apple Developer Account (paid or unpaid both work). +If you do not know your Team ID, go to your [Apple Developer account](https://developer.apple.com/account), log in, and scroll down to find your Team ID. + +If you don't already have a developer account, continue this guide and let Xcode generate a provisioning profile for you. You will need to update the Team ID later once a certificate is generated. + +If you are encountering build errors due to provisioning profiles, skip down to the troubleshooting section. + +## Create the Xcode Project + +Run the following commands: + +``` +bazel run //platform/ios:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal" +xed platform/ios/MapLibre.xcodeproj +``` + +Then once in Xcode, click on "MapLibre" on the left, then "App" under Targets, then "Signing & Capabilities" in the tabbed menu. +Confirm that no errors are shown: + +image + +Try to run the example App in the simulator and on a device to confirm your setup works. + +### Troubleshooting Provisioning Profiles + +If you get a Python `KeyError` when processing provisioning profiles, you probably have some _really_ old or corrupted profiles. + +Have a look through `~/Library/MobileDevice/Provisioning\ Profiles` and remove any expired profiles. + +## Using Bazel from the Command Line + +It is also possible to build and run the test application in a simulator from the command line without opening Xcode. + +``` +bazel run //platform/ios:App +``` + +If you want to build your own XCFramework, see the 'Build XCFramework' step in the [iOS CI workflow](../../.github/workflows/ios-ci.yml). + +## Render Tests + +To run the render tests, run the `RenderTest` target from iOS. + +When running in a simulator, use + +``` +# check for 'DataContainer' of the app with `*.maplibre.RenderTestApp` id +xcrun simctl listapps booted +``` + +to get the data directory of the render test app. This allows you to inspect test results. When adding new tests, the generated expectations and `actual.png` file can be copied into the source directory from here. + +## Documentation We use [DocC](https://www.swift.org/documentation/docc) for documentation. To build the documentation locally, run the following command from the root directory of the repository: @@ -8,7 +98,7 @@ platform/ios/scripts/docc.sh preview You need to have [aws-cli](https://github.com/aws/aws-cli) installed to download the resources from S3 (see below). -## Resources +### Resources Resources like images should not be checked in but should be uploaded to the [S3 Bucket](https://s3.eu-central-1.amazonaws.com/maplibre-native/index.html#ios-documentation-resources/). You can share a `.zip` with all files that should be added in the PR. @@ -28,7 +118,7 @@ resources=( ) ``` -## Examples +### Examples The code samples in the documentation should ideally be compiled on CI so they do not go out of date. diff --git a/platform/ios/README.md b/platform/ios/README.md index 69e0c052a..ec6d22ae5 100644 --- a/platform/ios/README.md +++ b/platform/ios/README.md @@ -2,155 +2,13 @@ [![GitHub Action build status](https://github.com/maplibre/maplibre-native/actions/workflows/ios-ci.yml/badge.svg)](https://github.com/maplibre/maplibre-native/actions/workflows/ios-ci.yml) [![CocoaPods Package](https://img.shields.io/cocoapods/v/MapLibre.svg)](https://github.com/CocoaPods/Specs/tree/master/Specs/b/0/0/MapLibre) [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmaplibre%2Fmaplibre-gl-native-distribution%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/maplibre/maplibre-gl-native-distribution) -A library based on [MapLibre Native](https://github.com/maplibre/maplibre-native) for embedding interactive map views with scalable, customizable vector maps into iOS Applications. - -## Getting Started - -MapLibre Native for iOS is distributed using the [Swift Package Index](https://swiftpackageindex.com/maplibre/maplibre-gl-native-distribution). To add it to your project, follow the steps below. - -1. To add a package dependency to your Xcode project, select File > Swift Packages > Add Package Dependency and enter its repository URL. You can also navigate to your target’s General pane, and in the “Frameworks, Libraries, and Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency. - -2. Either add MapLibre GitHub distribution URL `https://github.com/maplibre/maplibre-gl-native-distribution` or search for `maplibre-native` package. - -3. Choose "Next". Xcode should clone the distribution repository and download the binaries. - -4. To create a minimal app, update `ContentView.swift` (which should have been automatically created when you initalized the new XCode project) with the following contents: - -```swift -import SwiftUI -import Mapbox - -struct ContentView: View { - var body: some View { - MapView().edgesIgnoringSafeArea(.all) - } -} - -struct ContentView_Previews: PreviewProvider { - static var previews: some View { - ContentView() - } -} - -struct MapView: UIViewRepresentable { - func makeUIView(context: Context) -> MGLMapView { - // Build the style URL - let styleURL = URL(string: "https://demotiles.maplibre.org/style.json") - - // Create the map view - let mapView = MGLMapView(frame: .zero, styleURL: styleURL) - - mapView.logoView.isHidden = true - - mapView.setCenter( - CLLocationCoordinate2D( - latitude: 23.16, longitude: -109.50), animated: false) - - mapView.setZoomLevel(4, animated: false) - return mapView - - } - - func updateUIView(_ mapView: MGLMapView, context: Context) { - // Update the view if needed - } -} -``` - -There is a an open bounty to extend this Getting Started guide ([#809](https://github.com/maplibre/maplibre-native/issues/809)). In the meantime, refer to one of these external guides: - -- [Get Started with MapLibre Native for iOS using SwiftUI](https://docs.maptiler.com/maplibre-gl-native-ios/ios-swiftui-basic-get-started/) -- [Get Started With MapLibre Native for iOS using UIKit](https://docs.maptiler.com/maplibre-gl-native-ios/ios-uikit-basic-get-started/) - -## Developing - -The following are instructions on how to build MapLibre Native for development purposes. - -### Downloading Source - -Download the source and install all submodules if you have not already, by running the following from the root of the repository. - -``` -git clone --recurse-submodules git@github.com:maplibre/maplibre-native.git -cd maplibre-native -``` - -### Bazel - -[Bazel](https://bazel.build/) can be used to build the project. - -You can generate an Xcode project thanks to [rules_xcodeproj](https://github.com/MobileNativeFoundation/rules_xcodeproj) intergration. - -You need to install bazelisk, which is a wrapper around Bazel which ensures that the version specified in `.bazelversion` is used. - -``` -brew install bazelisk -``` - -#### Creating `config.bzl` - -You may want to configure Bazel, otherwise the default config gets used. - -``` -cp platform/darwin/bazel/example_config.bzl platform/darwin/bazel/config.bzl -``` - -You need to set your `BUNDLE_ID_PREFIX` to be unique (ideally use a domain that you own in reverse domain name notation). - -You can keep leave the `APPLE_MOBILE_PROVISIONING_PROFILE_NAME` alone. - -Set the Team ID to the Team ID of your Apple Developer Account (paid or unpaid both work). -If you do not know your Team ID, go to your [Apple Developer account](https://developer.apple.com/account), log in, and scroll down to find your Team ID. - -If you don't already have a developer account, continue this guide and let Xcode generate a provisioning profile for you. You will need to update the Team ID later once a certificate is generated. - -If you are encountering build errors due to provisioning profiles, skip down to the troubleshooting section. - -#### Create the Xcode Project - -_These instructions are for XCode 14.3.1_ - - -``` -bazel run //platform/ios:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal" -xed platform/ios/MapLibre.xcodeproj -``` - -Then once in Xcode, click on "MapLibre" on the left, then "App" under Targets, then "Signing & Capabilities" in the tabbed menu. -Confirm that no errors are shown: - -image - -Try to run the example App in the simulator and on a device to confirm your setup works. - -#### Troubleshooting Provisioning Profiles - -If you get a Python `KeyError` when processing provisioning profiles, you probably have some _really_ old or corrupted profiles. -Have a look through `~/Library/MobileDevice/Provisioning\ Profiles` and remove any expired profiles. - -#### Using Bazel from the Command Line - -It is also possible to build and run the test application in a simulator from the command line without opening Xcode. - -``` -bazel run //platform/ios:App -``` - -If you want to build your own XCFramework, see the 'Build XCFramework' step in the [iOS CI workflow](../../.github/workflows/ios-ci.yml). - -### Render Tests - -To run the render tests, run the `RenderTest` target from iOS. - -When running in a simulator, use - -``` -# check for 'DataContainer' of the app with `*.maplibre.RenderTestApp` id -xcrun simctl listapps booted -``` - -to get the data directory of the render test app. This allows you to inspect test results. When adding new tests, the generated expectations and `actual.png` file can be copied into the source directory from here. +Embed interactive maps with scalable, customizable vector maps into iOS Applications. Uses [Metal](https://developer.apple.com/metal/) for real-time rendering. ## Documentation -- [MapLibre Native for iOS API Reference](https://maplibre.org/maplibre-native/ios/api/) +- See the [Getting Started](https://maplibre.org/maplibre-native/ios/latest/documentation/maplibre-native-for-ios/gettingstarted) Guide in the documentation. +- [MapLibre Native iOS Documentation](https://maplibre.org/maplibre-native/ios/api/) + +# Contributing + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for instructions on how to build the project or how to work on the documentation. \ No newline at end of file diff --git a/platform/linux/README.md b/platform/linux/README.md index 146abd499..520a98e1d 100644 --- a/platform/linux/README.md +++ b/platform/linux/README.md @@ -98,4 +98,37 @@ Next, run the following command. This should produce an `out.png` image in your current directory with a barebones image of the world. -![Sample image of world from mbgl-render command](/misc/sample-barebones-mbgl-render-out.png) \ No newline at end of file +![Sample image of world from mbgl-render command](/misc/sample-barebones-mbgl-render-out.png) + +### Running the render tests + +To check that the output of the rendering is correct, we compare actual rendered PNGs for simple styles with expected PNGs. The content of the tests used to be stored in the MapLibre GL JS repository, which means that GL JS and Native are mostly pixel-identical in their rendering. + +The directory structure of the render tests looks like: + +``` +metrics/ + integration/ + render-tests/ + / + / + expected.png + style.json +``` + +After the render test run, the folder will also contain an `actual.png` file and a `diff.png` which is the difference between the expected and the actual image. There is a pixel difference threshold value which is used to decide if a render test passed or failed. + + +Run all render tests with: + +``` +./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json +``` + +Or a single test with: + +``` +./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json --filter "render-tests/fill-visibility/visible" +``` + +The render test results are summarized in a HTML website located next to the manifest file. For example, running `metrics/linux-clang8-release-style.json` produces a summary at `metrics/linux-clang8-release-style.html`. \ No newline at end of file