mobac-unlocked/README-DEV.html

207 lines
9.3 KiB
HTML
Raw Normal View History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Mobile Atlas Creator - Readme for Developers</title>
<style type="text/css">
body {
margin-left: 10px;
font-family: Helvetica, Arial, sans-serif;
}
h1,h2,h3,h4 {
color: #0000CC;
font-style: italic;
}
h1 {
border-bottom: solid thin black;
}
h2 {
margin-left: 20px;
}
h3 {
margin-left: 50px;
}
h4 {
margin-left: 80px;
}
pre {
margin-left: 140px;
}
p,ul,ol {
font-size: 110%;
margin-left: 100px;
}
</style>
</head>
<body>
<h1>Mobile Atlas Creator - Readme for Developers</h1>
<p>Welcome to the developer documentation of Mobile Atlas Creator
(MOBAC). First please read the <a href="README.html">standard readme</a>
for all users.</p>
<h2>Table of contents</h2>
<ul style="margin-left: 50px;">
<li><a href="#CodeAccess">Code access</a></li>
<li><a href="#BuildingMOBAC">Building Mobile Atlas Creator</a></li>
<li><a href="#Intellij">MOBAC in IntelliJ</a></li>
<li><a href="#GuidelinesCustomReleases">Guidelines for
publishing custom builds/releases</a></li>
<li><a href="#MapPacks">Map sources and map packs</a></li>
<li><a href="#CustomMapPack">Developing a custom map pack</a>
<ul style="margin-left: 10px;">
<li><a href="#MapPackBuilding">Building the map pack</a></li>
</ul>
</li>
<li><a href="#ImportantPackages">Source code overview - important packages</a></li>
<li><a href="#Participation">Participation</a></li>
</ul>
<h2><a name="CodeAccess">Code access</a></h2>
<p>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:</p>
<p><a
href="https://svn.code.sf.net/p/mobac/code/trunk/MOBAC/"><tt>https://svn.code.sf.net/p/mobac/code/trunk/MOBAC/</tt></a>
</p>
<p>There you will find the latest sources of Mobile Atlas Creator in form of an Gradle project which can be imported for
example into IntelliJ.
All sources, tools and build files are included in this repository.
Java libraries are automatically retrieved from Maven central repository.
</p>
<h2><a name="BuildingMOBAC">Building Mobile Atlas Creator</a></h2>
<p>
If you want to compile MOBAC, an installation of Java Development Tools (JDK) is required.
Using OpenJDK version 8 or 11 is recommended.
For building MOBAC use the provided gradlew command-line script:
</p>
<pre>
# Linux/MacOS:
chmod u+x gradlew
./gradlew dist
# Windows
gradlew dist
</pre>
<h2><a name="Intellij">MOBAC in IntelliJ</a></h2>
<p>The main class for starting MOBAC in IntelliJ is in module <tt>mobac-run</tt> class <tt>mobac.StartMOBACdev</tt></p>
<h2><a name="GuidelinesCustomReleases">Guidelines for
publishing custom builds/releases</a></h2>
<p>If you modify Mobile Atlas Creator and you want to publish it
yourself please consider the following guidelines:</p>
<ol>
<li>Chose a version/release name that makes it clear that it is
not an official release: Change the version string to reflect that.<br>
Example: <tt>2.2 beta 3 XYZ edition</tt><br>
The version string is located in the file <tt>/build.gradle</tt>.
Change the entry <b>version ...</b> to your custom release name.
</li>
<li>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.
</li>
<li>If your modification is useful you may consider to present it
to the Mobile Atlas Creator development team. <a
href="https://sourceforge.net/p/mobac/patches/">Patches</a>
are always welcome. Useful modifications have a great chance to be
integrated into the main branch.
</li>
</ol>
<h2><a name="MapPacks">Map sources and map packs</a></h2>
<p>Since version v1.9 map sources are no longer part of <tt>Mobile_Atlas_Creator.jar</tt>.
All map sources implementation are located in jar files in the <tt>mapsources</tt>
sub-directory. Those map sources implementation packages are called
"map-packs". Map packs files always starts with the term <tt>mp-</tt>
and they end with the term <tt>.jar</tt>.</p>
<p>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
<tt>devmode</tt> in <tt>settings.xml</tt> to <tt>true</tt>. Afterwards
map sources will be loaded directly from the <tt>bin</tt> directory of
Eclipse (if available).</p>
<h2><a name="CustomMapPack">Developing a custom map pack</a></h2>
<p>For creating your own custom map pack you have to create a new module (Java)
inside <tt>/mappacks</tt>. for example <tt>/mappacks/mymappack</tt></p>
<p>Place the map source code in directory <tt>/mappacks/mymappack/src/main/java/mobac/mapsources/mappacks/mymappack</tt>
</p>
<p>Additionally you have to create a text file named <tt>mobac.program.interfaces.MapSource</tt>
inside the directory <tt>src/main/resources/META-INF/services/</tt>. 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.</p>
<p>Background: During the build process this file will be included
into the map-pack jar as <tt>META-INF/services/mobac.program.interfaces.MapSource</tt>
so that it can be found by the <a
href="http://download.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html">ServiceLoader</a>.
</p>
<h3><a name="MapPackBuilding">Building the map pack</a></h3>
<p>Map packs can be built separately using <a
href="http://ant.apache.org/">Apache Ant</a> and the build target <b>build_mapsources</b>:</p>
<pre>ant build_mapsources</pre>
<p>Apache Ant is already included in Eclipse, so that you only have
to select the file <tt>build.xml</tt>, press the right mouse button and
select <b>Run As</b> - <b>Ant Build...</b>. In the dialogs that opens
deselect the build target <b>all</b> and select instead <b>build_mapsources</b>.</p>
<p>Each sub-package of <tt>mobac.mapsources.mappacks</tt> will be
compiled and packed to an map package. The created map packages are
saved into the <tt>mapsources</tt> directory. Therefore our example map
pack will be packed into the file <tt>mapsources/mp-mymappack.jar</tt></p>
<h2><a name="ImportantPackages">Source code overview - important packages</a></h2>
<h3><a href="src/main/java/mobac/gui">mobac.gui</a></h3>
<p>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. <tt><a
href="src/main/java/mobac/gui/mapview/PreviewMap.java">mobac.gui.mapview.PreviewMap</a></tt>
- the component that draws the movable map background used by Mobile
Atlas Creator.</p>
<h3><a href="src/main/java/mobac/mapsources">mobac.mapsources</a></h3>
<p>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 <a
href="src/main/java/mobac/mapsources/AbstractHttpMapSource.java"><tt>mobac.mapsources.AbstractHttpMapSource</tt></a>.
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 <a href="#CustomMapPack">Developing
a custom map pack</a>.</p>
<h3><a href="src/main/java/mobac/program/atlascreators">mobac.program.atlascreators</a></h3>
<p>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 <a
href="src/main/java/mobac/program/atlascreators/AtlasCreator.java">AtlasCreator</a>
which is the super class every atlas creator is derived of. The list of
available formats is maintained in the enumeration <a
href="src/main/java/mobac/program/model/AtlasOutputFormat.java"><tt>mobac.program.model.AtlasOutputFormat</tt></a>.
</p>
<h3><a href="src/main/java/mobac/tools">mobac.tools</a></h3>
<p>This package contains additional stand-alone tools that are not
shipped with the Mobile Atlas Creator binary release. For example the <a
href="src/main/java/mobac/tools/MapSourcesTester.java"><tt>mobac.tools.MapSourcesTester</tt></a>
downloads one tile from each map source for verifying that the map
source is functional.</p>
<h2><a name="Participation">Participation</a></h2>
<p>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
<a href="https://sourceforge.net/projects/mobac/">Mobile Atlas Creator</a>.</p>
</body>
</html>