diff --git a/README.md b/README.md index 2d50240..763c3b9 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,17 @@ This library fully supports Qt 6.5 and newer. Qt 5.15 is fully supported only on desktop platforms, previous Qt 5 versions down to 5.6 only support widgets but not Qt Location. -## Documentation +## Get and build -- [How to build](docs/Building.md) +The project uses submodules, so you need to clone it with the following commands: + +```shell +git clone https://github.com/maplibre/maplibre-native-qt.git +cd maplibre-native-qt +git submodule update --init --recursive +``` + +For more details on building the project, see [How to build](docs/Building.md). ## How to use? @@ -26,6 +34,13 @@ Two example projects based on Qt 6 are available in the To build an example, run the following commands: +```shell +export QMapLibre_DIR="" +cmake --workflow --preset default +``` + +or alternatively + ```shell mkdir build-example && cd build-example qt-cmake ../maplibre-native-qt/examples/ -GNinja \ @@ -35,7 +50,7 @@ qt-cmake ../maplibre-native-qt/examples/ -GNinja \ ninja ``` -For macOS a deployment target `deploy` is provided for convenience. +For more details on using the library, see [Usage](docs/Usage.md). ## Copyright diff --git a/docs/Documentation.md b/docs/Documentation.md index eadb2ce..54d7cf5 100644 --- a/docs/Documentation.md +++ b/docs/Documentation.md @@ -5,7 +5,13 @@ You would normally use this API in a Qt-based application. If you are interested in the internals of MapLibre Native you can also look at [Core C++ API](https://maplibre.org/maplibre-native/cpp/api/). -The source code can be found [on GitHub](https://github.com/maplibre/maplibre-native-qt). +The source code can be found [on GitHub](https://github.com/maplibre/maplibre-native-qt): + +```shell +git clone https://github.com/maplibre/maplibre-native-qt.git +cd maplibre-native-qt +git submodule update --init --recursive +```
diff --git a/docs/Usage.md b/docs/Usage.md index 75f7810..ee69b36 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,6 +1,123 @@ # Usage -Coming soon! +[TOC] + +MapLibre Native can be used with Qt either with C++ or with QML. +The following sections will guide you through the process of setting up +a project and using MapLibre Native with it. + +## Examples + +Two example apps are provided for Qt 6 in the `examples` directory +of the repository: + +- `quick` is a QML app that uses the `MapView` QML type. +- `widgets` is a C++ app that uses the `QMapLibre::GLWidget` widget. + +```shell +export QMapLibre_DIR="" +cmake --workflow --preset default +``` + +or alternatively + +```shell +mkdir build-example && cd build-example +qt-cmake ../maplibre-native-qt/examples/ -GNinja \ + -DCMAKE_C_COMPILER_LAUNCHER="ccache" \ + -DCMAKE_CXX_COMPILER_LAUNCHER="ccache" \ + -DCMAKE_PREFIX_PATH="" +ninja +``` + +## Basic CMake setup + +To use MapLibre Native in a Qt project built with CMake you can +use the `find_package` command to locate the package `QMapLibre` and then link +the target to the `QMapLibre::Core`, `QMapLibre::Location` +or `QMapLibre::Widgets` targets. Only specific components can be looked for +by using the `COMPONENTS` option. For example, to use the `Widgets` component +you need to add the following lines to your `CMakeLists.txt`: + +```cmake +find_package(QMapLibre COMPONENTS Widgets REQUIRED) + +target_link_libraries( + MyApplication + PRIVATE + QMapLibre::Widgets +) +``` + +There are multiple options to make CMake find the package: + +- set the `QMapLibre_DIR` variable to the directory where the package + is installed ending with `/lib/cmake/QMapLibre` +- set the `CMAKE_PREFIX_PATH` variable to the directory where the package + is installed + +## Widgets setup + +No special additional setup is needed. `QMapLibre` and `QMapLibreWidgets` +libraries need to be provided with your application. + +## QML setup + +To use MapLibre Native in a QML project you need to ensure that the plugins +are installed with your application: + +- `plugins/geoservices` for the mapping engine itself +- `qml/MapLibre` for the QML types + +Of course also `QMapLibre` and `QMapLibreLocation` +libraries need to be provided with your application. + +This can be ensured automatically using the helper function +`qmaplibre_location_setup_plugins()` which is available once +MapLibre Native is found by CMake. + +@warning Only OpenGL backend is supported for now! + +For example, to use MapLibre in a CMake-based QML project you need to add + +```cmake +find_package(QMapLibre COMPONENTS Location REQUIRED) + +target_link_libraries( + MyApplication + PRIVATE + QMapLibre::Location +) + +qmaplibre_location_setup_plugins(MyApplication) +``` + +## Development specifics + +Once your application is deployed there should be no special environment +or other overrides needed to run the application. +However, during development you may need to set some environment variables: + +- `QSG_RHI_BACKEND=opengl` to force the OpenGL backend +- `DYLD_LIBRARY_PATH` to find libraries on macOS +- `LD_LIBRARY_PATH` to find libraries on Linux +- `QML_IMPORT_PATH=/qml` to find the QML types + (`QML2_IMPORT_PATH` for Qt 5) +- `QT_PLUGIN_PATH=plugins` to find the plugins + +## Platform specifics + +### Android + +For Android multi-ABI builds you need to ensure that the correct build +is picked-up. In CMake this can be done like + +```cmake +if(ANDROID AND DEFINED ENV{QMapLibre_Android_DIR}) + message(STATUS "Setting QMapLibre_DIR to $ENV{QMapLibre_Android_DIR}/${ANDROID_ABI}/lib/cmake/QMapLibre") + set(QMapLibre_DIR "$ENV{QMapLibre_Android_DIR}/${ANDROID_ABI}/lib/cmake/QMapLibre") +endif() +```
diff --git a/examples/quick/minimal.pro b/examples/quick/minimal.pro deleted file mode 100644 index 30b2ab4..0000000 --- a/examples/quick/minimal.pro +++ /dev/null @@ -1,9 +0,0 @@ -TARGET = minimal - -# not sure why this is needed -CONFIG += install_ok - -QT += location - -SOURCES += main.cpp -RESOURCES += qml.qrc