archive-gh-me/maplibre-rs
1
0
Fork 0
mirror of https://github.com/maplibre/maplibre-rs.git synced 2025-12-08 19:05:57 +00:00
Code Issues Projects Releases Wiki Activity

Create the how-to-run.md documentation (#102)

Browse Source
This commit is contained in:
Drabble 2022-05-23 11:04:54 +02:00 committed by GitHub
parent 01c45fd13f
commit c563d640b0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 118 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
docs/src/development-guide/building.md
View File

@ -1,87 +0,0 @@
# Building for various Platforms
## Desktop
The build for desktop is very simple. You just have to run the following:
```bash
cargo build -p maplibre-demo
```
You can use the `--release` parameter if you want to be in release mode instead of debug.
If you want to run the application:
```bash
cargo run -p maplibre-demo
```
> __Note__: Make sure you have selected the right toolchain target within rustup. You can use `rustup show` to see your
> active toolchain. If you want to change the target of the build manually, use the cargo `--target` parameter.
## Android
You should make sure that a recent Android NDK is installed. You will need to set the `ANDROID_NDK_ROOT` variable
to something like this:
```bash
export ANDROID_NDK_ROOT=$HOME/android-sdk/ndk/23.1.7779620/
```
After that you can run the build the library:
``bash
just build-android
``
## iOS
In order to run this app on iOS you have to open the Xcode project at `./apple/xcode`.
You can then run the app on an iOS Simulator or a real device. During the Xcode build process cargo is used to build
a static library for the required architecture.
## MacOS
You can build Unix Executables for MacOS, as explained in the first section, with one of the following toolchain targets:
* **x86_64-apple-darwin** for Intel's x86-64 processors
* **aarch64-apple-darwin** for ARM64 processors
Use one of the following commands to build for your desired target architecture:
```bash
cargo build -p maplibre-demo --target x86_64-apple-darwin
cargo build -p maplibre-demo --target aarch64-apple-darwin
```
If you want to build a proper MacOS application (in OSX terminology), you will need to use the XCode project
in the folder `./apple/xcode/`.
Install [XCode](https://apps.apple.com/us/app/xcode/id497799835?ls=1&mt=12) and [rustup](https://rustup.rs/).
Then open the project from the folder `./apple/xcode` with XCode. Select the scheme called *example(macOS)* and
click on *Product -> Build for -> Running*. This will build the MacOS application for the version of OSX defined
in the Build Settings. The XCode project is configured to automatically compile the Rust library with the correct target
in the *Cargo Build* build phases configuration.
If you want to run the project from XCode, you need to make sure that you have selected the version of OSX which
corresponds to your system. Otherwise, XCode will tell you that the app is incompatible with the current version of macOS.
In order to change that, go into *Build settings -> Deployment -> MacOS deployment target* and select your OSX version.
Finally, you can click on the run button to start the application.
## Web (WebGL, WebGPU)
If you have a browser which already supports a recent version of the WebGPU specification then you can start a
development server using the following commands.
```bash
cd web
npm run start
```
If you want to run maplibre-rs with WebGL which is supported on every major browser, then you have to use the following
command.
```bash
npm run webgl-start
```

118
docs/src/development-guide/how-to-run.md Normal file
View File

@ -0,0 +1,118 @@
# Running maplibre-rs demos on various platforms
During development, you will want to run the maplibre demos on your local machine to test out your changes.
There are multiple demos of maplibre-rs for different targets. Some targets have prerequisites
depending on your operating system.
* **maplibre-demo** - targets Windows, MacOS and Linux, it is built directly with cargo.
* **apple** - targets iOS and MacOS and relies on the xcode IDE.
* **android** - targets Android devices and builds in Android Studio.
* **web** - targets the web using a WASM binary.
* **maplibre-headless** - *TBD*
All the targets below require you to install [rustup](https://rustup.rs/) to manage your Rust toolchain.
> __Note__: Make sure you have selected the right toolchain target within rustup. You can use `rustup show` to see your
> active toolchain. If you want to change the target of the build manually, use the cargo `--target` parameter.
## Maplibre-demo
### Linux/MacOS
The build for desktop is very simple, you just have to run the following command from the root of the
maplibre-rs project:
```bash
cargo run -p maplibre-demo
```
### Windows
Windows has two additional prerequisites to be able to run. You will need CMake, Visual Studio C++ build tools and the
sqlite3 library.
Install [CMake](https://cmake.org/download/) and add it to your path environment variables.
For the C++ build tools, download the [Visual Studio 2022 Build tools](https://visualstudio.microsoft.com/downloads/)
from the Microsoft website. After the download, while installing the Build tools, make sure that you select the
*C++ build tools*.
To install sqlite3 you need to build the sqlite3.lib manually with the following
[steps](https://gist.github.com/zeljic/d8b542788b225b1bcb5fce169ee28c55). This will generate a .lib file that
you will have to add to the SQLITE3_LIB_DIR environment variable.
Restart your shell to make sure you are using up-to-date environment variables.
Finally, the command below should execute successfully:
```bash
cargo run -p maplibre-demo
```
## Android
Start by installing the
[Android Studio IDE](https://developer.android.com/studio?gclid=CjwKCAjwj42UBhAAEiwACIhADmF7uHXnEHGnmOgFnjp0Z6n-TnBvutC5faGA89lwouMIXiR6OXK4hBoCq78QAvD_BwE&gclsrc=aw.ds).
Make sure the NDK version 23.1.7779620 is installed. The Native Development Kit (NDK) is a set of tools that allows
you to use C and C++ code with Android.
```
ANDROID STUDIO -> tools -> SDK manager -> SDK tools -> tick show package details -> ndk (side by side) version 23.1.7779620
```
Open the project within `./android/gradle` and create a new virtual device with the device manager. Minimum SDK version
should be 21. This was tested on a x86_64 emulator. Finally, run the demo configuration. It should open your virtual device and
run the maplibre-rs Android demo on it. Alternatively you can also run it on your own Android device.
> Note: If you are building for a x86 Android device, you probably need to install the following target using
> rustup with the following command `rustup target add i686-linux-android`.
> Note: Android is configured to support OpenGL ES 3.1 (This API specification is supported by Android 5.0 (API level 21) and higher).
> Your Android device is required to support OpenGL ES 3.1 at least. There are some issues
> [here](https://stackoverflow.com/questions/40797975/android-emulator-and-opengl-es3-egl-bad-config) and
> [here](https://www.reddit.com/r/Arcore/comments/8squbo/opengl_es_31_is_required_for_android_emulator_to/) that
> discuss configuration of Android Studio for OpenGL ES 3.1 support in emulators.
## Apple
Apple builds rely on the [XCode IDE](https://apps.apple.com/us/app/xcode/id497799835?ls=1&mt=12).
Start by installing XCode and open the project within `./apple/xcode`.
> Cargo is used in to build the maplibre library in the build phases of the XCode project configuration.
### iOS
You can use XCode to run on a iOS Simulator or a real device. Install a simulator in XCode.
Version 9 is the minimum version supported theoretically.
Select the scheme called *example (iOS)* and click on run. This will start the iOS application.
### MacOS
As you might have seen in the maplibre-demo section, you can build Unix executables directly with Cargo.
In order to build a proper MacOS application (in OSX terminology) you have to use the `./apple/xcode` project.
Open the project from the folder `./apple/xcode` with XCode. Select the scheme called *example (macOS)* and
click on run. This will start the MacOS application.
> The minimum target OSX version for the MacOS build is defined inside *Build settings -> Deployment -> MacOS deployment target*.
> If you are using a lower version of OSX, you will not be able to run the application on your computer.
## Web (WebGL, WebGPU)
If you have a browser which already supports a recent version of the WebGPU specification then you can start a
development server using the following commands.
```bash
cd web
npm run start
```
If you want to run maplibre-rs with WebGL which is supported on every major browser, then you have to use the following
command.
```bash
just web-lib esbuild
just web-demo start
```