A quick description for developers of how to get started with mapsforge.
This article describes how to build the mapsforge project and libraries from scratch and how developers should start working.
There are problems checking out the code from this repository with git > 1.7.2, the reason is unknown but it might be a corruption of the Google repository. You can clone the repository with git version 1.7.2 or via one of the clones, eg. at https://github.com/applantation/mapsforge
Mapsforge consists of the following components:
The jars build from the above components are required elements for a mapsforge application on Android.
The mapsforge code has now been consolidated into two main branches as well as releases
Code before the 0.4.0 release is not supported anymore and if you are starting development with mapsforge, its use is strongly discouraged.
For a while, what has become the 0.4.0 release was known as the 'rescue' branch, while what is known as dev now was the 'rescue-exp' branch. Rescue has been merged into master, and rescue-exp has become dev. The use of the cloned repositories holding these branches is discouraged, they will only exist for a transition period before being removed.
The Samples app, in Applications/Android/Samples, is a sample app for Android demonstrating mapsforge capabilities and a good starting point if you want to develop your own mapsforge-based app.
The SwingMapViewer is a simple Java only app useful for testing maps.
Gradle is the new build system favoured by Google for Android builds. Android Studio, the new IDE provided by Google for building Android apps, integrates nicely with Gradle.
The current version for building mapsforge is Gradle 1.11.
After checking out the code, a build from the command line should be as easy as
gradle clean build
After the build completes successfully you will find the Samples app in the directory Applications/Android/Samples/build/apk. Currently the build results in unsigned apks.
Android Studio integrates tightly with gradle. The easiest way to create a new application is to follow the example of the Samples app.
A second way to build mapsforge is using maven. This was the original way of building mapsforge.
The mapsforge project uses the free Apache maven tool to automatize the build process. Both version 2 and version 3 can be used. If you want to learn more about maven, please refer to the official documentation.
To start a complete build of all modules, open a command prompt, change to the directory which contains the copy of the mapsforge repository and execute the following command:
mvn clean install
This will tell maven to delete any pre-existing generated files and directories during the build. Although the cleanup step is not always needed, we recommend to do so every time in order to avoid problems and have repeatable results.
In the beginning, maven automatically downloads all missing plug-ins and files. Depending on the speed of your Internet connection, this may take some time. All downloaded files are stored locally in a special maven directory to avoid downloading them again at each build.
During the build process, maven compiles, tests and packages all modules in the correct order. A new directory target is created for each module which contains – among test reports and other generated files – the new artifacts. Eventually these artifacts are installed in your local repository so that you can use them in other maven projects.
If you want to contribute to the mapsforge project, we recommend to use the latest stable version of the Eclipse IDE.
As Eclipse needs to know the path to your local maven repository, you have to add a new classpath variable named M2_REPO. This can either be done manually via Window > Preferences > Java > Build Path > Classpath Variables > New or automatically via the Maven Eclipse Plugin. Depending on the currently running operating system, execute one of the following commands:
mvn eclipse:configure-workspace "-Declipse.workspace=path/to/your/eclipse/workspace/"
mvn eclipse:configure-workspace "-Declipse.workspace=x:\path\to\your\eclipse\workspace\"
After you have configured your Eclipse workspace, checked out the code and built the complete project (see the instructions above), execute the following command:
This will tell maven to generate all missing Eclipse project files which are not checked in into our repository. It also ensures that all mapsforge projects use the same code formatter profile, compiler settings, file encoding, new line delimiters and so on.
You should install the Checkstyle, FindBugs and PMD Eclipse plug-ins to regularly analyze the quality of the source code. The same set of rules is shared across all mapsforge modules. Running the above maven command will also copy the necessary configuration files into each project directory.
Each of the mapsforge modules is now configured as an Eclipse project and can be added to your current workspace via File > Import > General > Existing Projects into Workspace.
As an open source project, we welcome new contributors and appreciate your help.
Before you start working on an unresolved issue or try to implement a new feature, please contact us via our public mapsforge-dev mailing list. You may also create a new issue or comment on an existing one to describe your ideas. We will then discuss the best way to realize your proposal and figure out how we can help you to get started quickly.
If you are only requesting a small change in the code, you may attach a patch file to the corresponding issue. Make sure that your patch is derived from the latest version in our repository, otherwise we might be unable to apply it. Please follow our code and style conventions. Detailed information about them can be found in the Project conventions article.
Besides writing code, improving our written documentation and keeping our issue tracker up-to-date is equally important. Participating in this way, you are required to have a Google account. We will grant potentially required permissions on individual basis and request.
Please note that the mapsforge project is licenced under the GNU LGPL3 licence. Thus, all your contributions are going to be published under this license.