# Mobile Atlas Creator - Readme for Developers

Welcome to the developer documentation of Mobile Atlas Creator (MOBAC). First please read the standard readme for all users.

## Table of contents

- Code access
- Compiling MOBAC within Eclipse
- Building Mobile Atlas Creator
- Guidelines for publishing custom builds/releases
- Map sources and map packs
- Developing a custom map pack
  - Building the map pack
- Source code overview - important packages
- Participation

## Code access

If you want do get your hands on the latest source code of Mobile Atlas Creator you can check out the code from the Subversion repository at SourceForge:

`https://svn.code.sf.net/p/mobac/code/trunk/MOBAC/trunk/MOBAC`

There you will find the latest sources of Mobile Atlas Creator in form of an Eclipse (v4.11) project. All tools, libraries, sources and build files are included in this repository.

## Compiling MOBAC within Eclipse

If you want to run MOBAC from within Eclipse you only need Eclipse with Java Development Tools installed (included in all Eclipse Java editions).
The root class for starting MOBAC in Eclipse `mobac.StartMOBAC`

Compile/building Mobile Atlas Creator without Eclipse requires Apache Ant) which is used for building the jar version of Mobile Atlas Creator and of course the Java Development Kit (JDK) installed.

## Building Mobile Atlas Creator

For building Mobile Atlas Creator please run Apache Ant on the provided file `build.xml`

The default build target performs all necessary tasks for compiling the sources, packaging the classes to the main jar and the map packs and then minimizing the size of the jar using ProGuard (`lib/proguard.jar`).
Additionally the build steps include a call to `lib/svnversion.jar` which is a Java only version of the command svnversion (bases on SVNKit). This command updates the SVN revision information in file `src/main/java/mobac/mobac-rev.properties` which is included in the final jar of Mobile Atlas Creator.

## Guidelines for publishing custom builds/releases

If you modify Mobile Atlas Creator and you want to publish it yourself please consider the following guidelines:

1. Chose a version/release name that makes it clear that it is not an official release: Change the version string to reflect that.
   Example: `1.9 beta 3 XYZ edition`
   The version string is located in the properties file `src/main/java/mobac/mobac.properties`. Change the entry mobac.version to your custom release name.
2. Do not forget that Mobile Atlas Creator is a GPL project - therefore publishing the source code together with the binary release should went without saying.
3. If your modification is useful you may consider to present it to the Mobile Atlas Creator development team. Patches are always welcome. Useful modifications have a great chance to be integrated into the main branch.

## Map sources and map packs

Since version v1.9 map sources are no longer part of `Mobile_Atlas_Creator.jar`. All map sources implementation are located in jar files in the `mapsources` sub-directory. Those map sources implementation packages are called "map-packs". Map packs files always starts with the term `mp-` and they end with the term `.jar`.

For implementing new map sources in a development environment like Eclipse it is sometimes faster to load the map sources directly from class-path rather from the map-packs. You can enable it by setting `devmode` in `settings.xml` to `true`. Afterwards map sources will be loaded directly from the `bin` directory of Eclipse (if available).

## Developing a custom map pack

For creating your own custom map pack you have to create a new Java package below `mobac.mapsources.mappacks`. For example lets assume that the name of the new map pack should be mymappack. Therefore you have to create the package `mobac.mapsources.mappacks.mymappack`. Place all Java source files within this package (sub-packages are also possible).

Additionally you have to create a text file named `mapsources.list` inside the package `mobac.mapsources.mappacks.mymappack`. This file contains a list of class names (full class name including the package name, one per line) that should be loaded by MOBAC as map source.

Background: During the build process this file will be included into the map-pack jar as `META-INF/services/mobac.program.interfaces.MapSource` so that it can be found by the ServiceLoader.

### Building the map pack

Map packs can be built separately using Apache Ant and the build target build_mapsources:

    ant build_mapsources

Apache Ant is already included in Eclipse, so that you only have to select the file `build.xml`, press the right mouse button and select Run As - Ant Build.... In the dialogs that opens deselect the build target all and select instead build_mapsources.

Each sub-package of `mobac.mapsources.mappacks` will be compiled and packed to an map package. The created map packages are saved into the `mapsources` directory. Therefore our example map pack will be packed into the file `mapsources/mp-mymappack.jar`

## Source code overview - important packages

### mobac.gui

This package contains the implementation of all dialogs/windows. In the sub-packages you can find the related implementations of used graphical components - e.g. `mobac.gui.mapview.PreviewMap` - the component that draws the movable map background used by Mobile Atlas Creator.

### mobac.mapsources

Holds the infrastructure and the implementation of all map sources available within Mobile Atlas Creator. For implementing own map sources that uses an online map you should derive your map source from the abstract base class `mobac.mapsources.AbstractHttpMapSource`. Map sources should be compiled and packed to a map pack so that they can be automatically detected and loaded while MOBAC is starting-up. For details on that topic please read section Developing a custom map pack.

### mobac.program.atlascreators

Holds the implementations of all atlas creators (atlas output formats) provided by Mobile Atlas Creator. Each class in the package implements exactly one atlas output format. Of special interest is the abstract class AtlasCreator which is the super class every atlas creator is derived of. The list of available formats is maintained in the enumeration `mobac.program.model.AtlasOutputFormat`.

### mobac.tools

This package contains additional stand-alone tools that are not shipped with the Mobile Atlas Creator binary release. For example the `mobac.tools.MapSourcesTester` downloads one tile from each map source for verifying that the map source is functional.

## Participation

If you are familiar with the programming language Java and you want to contribute or participate in the development process of Mobile Atlas Creator feel free to contact one of the other developers of Mobile Atlas Creator.