From c563d640b0cf62947f2b31c979b6a4dd02e4d22b Mon Sep 17 00:00:00 2001 From: Drabble Date: Mon, 23 May 2022 11:04:54 +0200 Subject: [PATCH] Create the how-to-run.md documentation (#102) --- docs/src/development-guide/building.md | 87 ----------------- docs/src/development-guide/how-to-run.md | 118 +++++++++++++++++++++++ 2 files changed, 118 insertions(+), 87 deletions(-) delete mode 100644 docs/src/development-guide/building.md create mode 100644 docs/src/development-guide/how-to-run.md diff --git a/docs/src/development-guide/building.md b/docs/src/development-guide/building.md deleted file mode 100644 index 663da68d..00000000 --- a/docs/src/development-guide/building.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/docs/src/development-guide/how-to-run.md b/docs/src/development-guide/how-to-run.md new file mode 100644 index 00000000..8bbe0722 --- /dev/null +++ b/docs/src/development-guide/how-to-run.md @@ -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 +``` \ No newline at end of file