Getting Started Guides iOS and Android

[louwers]

Right now we don't have any Getting Started guides for Android or iOS. These are in my opinion pretty essential to be able to pick up MapLibre.

MapTiler already put out such guides for MapLibre (see below). One option may be to simply link to these guides, but since MapLibre is an independent project that may create the wrong impression. It may be possible to get permission from MapTiler to re-use their guides and example code. We would remove the MapTiler specific information, but still mention MapTiler and other compatible providers.

Another question is where this type of documentation is best placed. I think the Markdown book that Oliver set up is best kept for overarching documentation mainly of interest to contributors. I think ideally we would place it alongside the API documentation of each respective platform. Since we will are investigating alternatives to our current API documentation generators (#672, #676) the best option may be to include it in Markdown files in this repository for now.

MapTiler Guides

iOS

• https://docs.maptiler.com/maplibre-gl-native-ios/
• https://github.com/maptiler/maplibre-gl-native-ios-samples

Android

• https://docs.maptiler.com/maplibre-gl-native-android/
• https://github.com/maptiler/maplibre-gl-native-android-samples

[birkskyum]

ping @wipfli, @klokan

[wipfli]

I think there are a few map service providers which have documentation about how to use MapLibre SDK. To mind come MapTiler, Esri, Amazon Location Services.

[wipfli]

https://developers.arcgis.com/maplibre-gl-js/get-started/

[wipfli]

https://docs.aws.amazon.com/location/latest/developerguide/tutorial-maplibre-gl-js.html

[wipfli]

https://docs.aws.amazon.com/location/latest/developerguide/tutorial-maplibre-ios.html

[wipfli]

Keeping up-to-date documentation is a cost factor which our sponsors might want to share. I would like to bring this topic up in the next MapLibre Advisory Council beginning of March 2023 and ask if anybody would be interested in upstreaming tutorials. I guess it is only AWS at the moment who has tutorials and is part of the MapLibre Sponsorship Program, but let's still ask them in the Adivsory Council...

[birkskyum]

We should at least make sure maplibre is the go to resource for up-to-date api-docs, and then maybe have an overview of these different providers' guides for now.

[hallahan]

I think for starters, we should have some very simple instructions on the commands to run to build the project. For example, I don't see anywhere obvious to run the cmake commands.

The main readme has extraneous details about pending work on render modulation and Metal implementation. That seems like it should not be the first thing to present to a new developer.

When navigating into the platforms, like iOS, for example, I still do not see instructions on how to build the library.

Finally, when navigating into "Integrating custom builds of the Mapbox Maps SDK for iOS into your application", we get some commands, but the make instructions are confusing. It should say:

git submodule update --init
cd platform/ios
make iproj

I think that's probably the. most common thing a developer would do to get up and running with maplibre-gl-native, not `make iframework BUILDTYPE=Release.

Lastly, this pattern seems odd. Usually when I build a CMake project, I run the cmake command first, then the make command, and it is done from the root of the project.

[louwers]

The main readme has extraneous details about pending work on render modulation and Metal implementation. That seems like it should not be the first thing to present to a new developer.

MapLibre GL Native is a monorepo right now, and we decided to keep platform-specific information out of the README.

When navigating into the platforms, like iOS, for example, I still do not see instructions on how to build the library.

The whole build and documentation situation is quite hairy right now. A lot of stuff has not been updated yet after the fork. But your feedback is very helpful, so thank you for sharing it!

It takes two clicks to find the make iproj command. iOS > CONTRIBUTING.md. How can we make it better? Show it right away when navigating to the iOS platform?

I think for starters, we should have some very simple instructions on the commands to run to build the project. For example, I don't see anywhere obvious to run the cmake commands.

On the iOS side, CMake is used in part, but the Xcode is also configured with a custom xcconfig... The CMake is burried deep into that Makefile. I agree this is far from ideal.

I created an issue to track this: #737. Please feel free to join the #maplibre-ios channel on Slack to join other iOS developers working with MapLibre.

[hallahan]

Fair enough. I see things are getting better 👍🏻