From 22eb0d4a0b3a247ba3b865d8dc5d2b1025e701e8 Mon Sep 17 00:00:00 2001 From: Emux Date: Sat, 6 Feb 2016 17:45:33 +0200 Subject: [PATCH] Library integration documentation #781 --- README.md | 2 +- docs/Changelog.md | 3 +- docs/Getting-Started-Developers.md | 20 +----- docs/Getting-Started-Map-Writer.md | 4 +- docs/Integration.md | 90 +++++++++++++++++++++++++++ docs/Specification-Binary-Map-File.md | 2 - 6 files changed, 95 insertions(+), 26 deletions(-) create mode 100644 docs/Integration.md diff --git a/README.md b/README.md index b3c426b55..0dda65e57 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The mapsforge project provides free and open software for the rendering of maps based on OpenStreetMap data. Currently, we offer a library for ad-hoc map rendering on Android devices and in Java stand-alone applications. -**The current stable release is 0.6.0. See the [changelog](docs/Changelog.md) for details, [download official 0.6.0 binaries](docs/Downloads.md).** +**The current stable release is 0.6.0. See the [integration guide](docs/Integration.md) and [changelog](docs/Changelog.md), download official [0.6.0 binaries](docs/Downloads.md).** - The mapsforge project uses a [compact file format](docs/Specification-Binary-Map-File.md) for fast ad-hoc rendering of OpenStreetMap data. - We provide tools to [compile your own maps](docs/Getting-Started-Map-Writer.md) with detailed [instructions](docs/MapCreation.md) and also [precompiled maps](http://download.mapsforge.org). diff --git a/docs/Changelog.md b/docs/Changelog.md index f5a5455a7..0045ffc29 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -1,7 +1,5 @@ # Changelog - - ## New since 0.6.0 - POI Search [#728](https://github.com/mapsforge/mapsforge/issues/728) @@ -9,6 +7,7 @@ - LabelLayer improved implementation [#763](https://github.com/mapsforge/mapsforge/issues/763) - Color filters in map rendering [#778](https://github.com/mapsforge/mapsforge/issues/778) - Night mode example [#777](https://github.com/mapsforge/mapsforge/issues/777) +- Library integration [documentation](Integration.md) [#781](https://github.com/mapsforge/mapsforge/issues/781) - Jar with dependencies building [#767](https://github.com/mapsforge/mapsforge/issues/767) - Improve code formatting [#782](https://github.com/mapsforge/mapsforge/issues/782) - Many other minor improvements and bug fixes diff --git a/docs/Getting-Started-Developers.md b/docs/Getting-Started-Developers.md index dddcd6473..252442498 100644 --- a/docs/Getting-Started-Developers.md +++ b/docs/Getting-Started-Developers.md @@ -45,7 +45,7 @@ Extra Java components: The jars build from the above components are required elements for a mapsforge application on Android or Java. -External dependencies jars can be found at their respective sites or simply searching them in [Maven central repository](http://search.maven.org/). +External dependencies jars can be found at their respective sites or in Maven central repository. ### Branches @@ -54,7 +54,7 @@ The mapsforge code has now been consolidated into two main branches as well as r - **dev**: unstable development, features in progress. Use this if you want the latest development features and you can live with some instability. - **release**: use this if you want to build applications built on top of well-tested and stable code. -Code before the 0.6.0 release is not supported anymore (we do not have the resources to do this) and if you are starting development with mapsforge, its use is strongly discouraged. +Code before latest release is not supported anymore (we do not have the resources to do this) and if you are starting development with mapsforge, its use is strongly discouraged. ## Development Applications @@ -141,22 +141,6 @@ To build the Android sample application, you need to make a few adjustments: Without these steps, you may have issues with the app crashing with a `java.lang.NoClassDefFoundError` exception. If that happens, carry out the above steps and build again. -### JitPack - -We support also [JitPack](https://jitpack.io/#mapsforge/mapsforge) for publishing Mapsforge. This can be used for our releases but it's also useful for using SNAPSHOT builds in your application (which are not in Maven central). - -For example in order to include the `mapsforge-core` module `master-SNAPSHOT` with Gradle. - -Add as repository: - -`maven { url "https://jitpack.io" }` - -And declare as dependency: - -`compile 'com.github.mapsforge.mapsforge:mapsforge-core:master-SNAPSHOT'` - -The same syntax applies for all Mapsforge modules. And with similar way you can declare the dependencies in Maven too. - ## How to contribute As an open source project, we welcome new contributors and appreciate your help. diff --git a/docs/Getting-Started-Map-Writer.md b/docs/Getting-Started-Map-Writer.md index 19a1e61c7..d28134953 100644 --- a/docs/Getting-Started-Map-Writer.md +++ b/docs/Getting-Started-Map-Writer.md @@ -1,9 +1,7 @@ # Mapsforge Map-Writer - - -The Mapsforge Map-Writer is a plug-in for the OpenStreetMap Osmosis Tool to convert OSM data files into maps that can be displayed with mapsforge. +The Mapsforge Map-Writer is a plug-in for the OpenStreetMap Osmosis Tool to convert OSM data files into maps that can be displayed with mapsforge. This documentation is intended for those who want to create map files for use with mapsforge. diff --git a/docs/Integration.md b/docs/Integration.md new file mode 100644 index 000000000..2d3b624c3 --- /dev/null +++ b/docs/Integration.md @@ -0,0 +1,90 @@ +# Integration guide + +This article describes how to integrate mapsforge library in your project (use the proper versions). + +## Gradle + +### 1. Map + +#### 1.1 Core +```groovy +compile 'org.mapsforge:mapsforge-core:0.6.0' +compile 'org.mapsforge:mapsforge-map:0.6.0' +compile 'org.mapsforge:mapsforge-map-reader:0.6.0' +compile 'net.sf.kxml:kxml2:2.3.0' +``` + +#### 1.2 Android +```groovy +compile 'org.mapsforge:mapsforge-map-android:0.6.0' +compile 'com.caverock:androidsvg:1.2.2-beta-1' +``` + +Optionally: +```groovy +compile 'org.mapsforge:mapsforge-map-android-extras:0.6.0@aar' +``` + +#### 1.3 Java +```groovy +compile 'org.mapsforge:mapsforge-map-awt:0.6.0' +compile 'com.kitfox.svg:svg-salamander:1.0' +``` + +### 2. POI + +#### 2.1 Core +```groovy +compile 'org.mapsforge:mapsforge-core:0.6.0' +compile 'org.mapsforge:mapsforge-poi:0.6.0' +``` + +#### 2.2 Android +```groovy +compile 'org.mapsforge:mapsforge-poi-android:0.6.0' +compile 'org.mapsforge:sqlite3-android:0.6.0' +``` + +You'll need also the SQLite wrapper native library [files](../sqlite3-android/libs). + +#### 2.3 Java +```groovy +compile 'org.mapsforge:mapsforge-poi-awt:0.6.0' +compile 'org.xerial:sqlite-jdbc:3.8.11.2' +``` + +## Maven + +The dependencies for Maven are declared in a similar way. For example: + +```xml + + org.mapsforge + mapsforge-core + 0.6.0 + +``` + +## JitPack + +We support also [JitPack](https://jitpack.io/#mapsforge/mapsforge) for publishing Mapsforge. This can be used for the releases, but it's also useful for integrating SNAPSHOT builds in your application (not available in Maven central). + +For example in order to include the `mapsforge-core` module `master-SNAPSHOT` with Gradle. + +Add as repository: +```groovy +maven { url "https://jitpack.io" } +``` + +And declare as dependency: +```groovy +compile 'com.github.mapsforge.mapsforge:mapsforge-core:master-SNAPSHOT' +``` + +The same syntax applies for all Mapsforge modules. And with similar way you can declare the dependencies in Maven too. + +## Jars + +You can find Mapsforge (regular and with dependencies) jars in the [downloads](Downloads.md) section. + +External dependencies jars can be found at their respective sites or in Maven central repository. diff --git a/docs/Specification-Binary-Map-File.md b/docs/Specification-Binary-Map-File.md index 8606274c0..d35a54508 100644 --- a/docs/Specification-Binary-Map-File.md +++ b/docs/Specification-Binary-Map-File.md @@ -1,8 +1,6 @@ # Specification: Mapsforge Binary Map File Format - - ## Conceptual design The *mapsforge binary map file format* is designed for map rendering on devices with limited resources like mobile phones.