| 1 | Supplemental information for JOSM -- the Java OpenStreetMap Editor
|
|---|
| 2 |
|
|---|
| 3 | =============================================================================
|
|---|
| 4 | I. Install & Launch
|
|---|
| 5 | =============================================================================
|
|---|
| 6 |
|
|---|
| 7 | Installation notes
|
|---|
| 8 | ------------------
|
|---|
| 9 | To run JOSM, you need:
|
|---|
| 10 |
|
|---|
| 11 | * The JOSM .jar file, e.g., josm-tested.jar or josm-latest.jar
|
|---|
| 12 | * Java Runtime Environment (JRE) 8, or later.
|
|---|
| 13 |
|
|---|
| 14 |
|
|---|
| 15 | How to get Java Runtime Environment
|
|---|
| 16 | -----------------------------------
|
|---|
| 17 | You need JRE Version 8, or later.
|
|---|
| 18 |
|
|---|
| 19 | Microsoft Windows and Apple Mac OS X users should visit https://www.java.com
|
|---|
| 20 | and download the latest Java executable for their system.
|
|---|
| 21 |
|
|---|
| 22 | Linux users should visit http://www.oracle.com/technetwork/java/index.html
|
|---|
| 23 | There is a Linux binary installer, which you must execute from a console, or
|
|---|
| 24 | use the mechanism of your distribution's packaging system.
|
|---|
| 25 |
|
|---|
| 26 |
|
|---|
| 27 | How to launch
|
|---|
| 28 | -------------
|
|---|
| 29 | Microsoft Windows users launch by double-clicking on the .jar file.
|
|---|
| 30 | If this does not work, open a command shell and type
|
|---|
| 31 | "java -jar josm-latest.jar" in the directory that holds the file. (Please
|
|---|
| 32 | replace josm-latest.jar with the name of your .jar file, if you aren't using
|
|---|
| 33 | the latest version.)
|
|---|
| 34 |
|
|---|
| 35 | Under Linux, open a shell, go to the file directory and type
|
|---|
| 36 | "java -jar josm-latest.jar" to launch. If this does not work, try to set
|
|---|
| 37 | your JAVA_HOME variable to the java executable location (the root location,
|
|---|
| 38 | not the bin).
|
|---|
| 39 |
|
|---|
| 40 | MacOS X users just click on the .jar file icon.
|
|---|
| 41 |
|
|---|
| 42 | =============================================================================
|
|---|
| 43 | II. Development
|
|---|
| 44 | =============================================================================
|
|---|
| 45 |
|
|---|
| 46 | How to get the source code
|
|---|
| 47 | --------------------------
|
|---|
| 48 | Download it directly from the subversion at
|
|---|
| 49 | https://josm.openstreetmap.de/svn/trunk. To use the command line subversion
|
|---|
| 50 | client, type
|
|---|
| 51 |
|
|---|
| 52 | svn co https://josm.openstreetmap.de/svn/trunk josm
|
|---|
| 53 |
|
|---|
| 54 |
|
|---|
| 55 | Files & directories
|
|---|
| 56 | -------------------
|
|---|
| 57 | This is an overview of the files and directories in the JOSM code repository:
|
|---|
| 58 | - build.xml ant build file (standard way to create a JOSM binary)
|
|---|
| 59 | - CONTRIBUTION list of major code contributors
|
|---|
| 60 | - data/ data files that will be included in the JOSM jar file
|
|---|
| 61 | - fonts/ font files used for map rendering
|
|---|
| 62 | - projection/ projection files
|
|---|
| 63 | - *.gsb NTv2 grid files for projection support
|
|---|
| 64 | - epsg list of projection definitions
|
|---|
| 65 | - *.lang translation data
|
|---|
| 66 | - *.xsd xml schema files for validation of configuration files
|
|---|
| 67 | - help-browser.css CSS file for the help sites (HTML content is downloaded from the website
|
|---|
| 68 | on demand, but displayed inside the programm in a Java web browser component.)
|
|---|
| 69 | - validator/ data files used by the JOSM validator feature
|
|---|
| 70 | - *.cfg files designed for the old tagchecker, still used
|
|---|
| 71 | - *.mapcss default validation rules for the new mapcss-based tagchecker
|
|---|
| 72 | - data_nodist/ data files that are useful for development, but not distributed
|
|---|
| 73 | - exif-direction-example.jpg
|
|---|
| 74 | sample image, that contains direction information in the EXIF header
|
|---|
| 75 | (keys: Exif.GPSInfo.GPSImgDirectionRef, Exif.GPSInfo.GPSImgDirection)
|
|---|
| 76 | - filterTests.osm used for unit testing of the filter feature
|
|---|
| 77 | (see test/unit/org/openstreetmap/josm/data/osm/FilterTest.java)
|
|---|
| 78 | - Join_Areas_Tests.osm some examples to test the 'join areas' feature
|
|---|
| 79 | - mapcss/ sample map styles and corresponding data files for regression testing
|
|---|
| 80 | - projection-reference-data.csv
|
|---|
| 81 | reference data for projection tests
|
|---|
| 82 | (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRefTest.java)
|
|---|
| 83 | - projection-regression-test-data.csv
|
|---|
| 84 | regression data for projection tests
|
|---|
| 85 | (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRegressionTest.java)
|
|---|
| 86 | - geticons.pl tool to find all used icons and allows deleting unused icons
|
|---|
| 87 | searches also for images with incompatible svg code
|
|---|
| 88 | - gpl-2.0.txt, gpl-3.0.txt full text of the GNU General Public License
|
|---|
| 89 | - images/ images distributed with the JOSM binary
|
|---|
| 90 | - icons images for the Potlatch 2 style
|
|---|
| 91 | - presets images for the main mappaint style and the internal presets
|
|---|
| 92 | - images_nodist/ images, which are not for distribution, but may be useful later (e.g. high
|
|---|
| 93 | resolution and vector versions)
|
|---|
| 94 | - josm.jnlp Java Web Start launcher file (used on the website for the tested version)
|
|---|
| 95 | - josm-latest.jnlp Java Web Start launcher file (used on the website for the latest version)
|
|---|
| 96 | - LICENSE the JOSM license terms
|
|---|
| 97 | - linux/ files useful for Linux distributions, including Appdata files, .desktop
|
|---|
| 98 | files, Debian/Ubuntu scripts, man pages, icons, etc.
|
|---|
| 99 | - macosx/ files needed to create the MacOS X package
|
|---|
| 100 | - netbeans/ preconfigured Netbeans project
|
|---|
| 101 | - optimize-images short script to decrease size of PNG images
|
|---|
| 102 | - patches/ patches for external libraries used in JOSM (see below)
|
|---|
| 103 | - README this file
|
|---|
| 104 | - resources/ resource files that will be included in the JOSM jar file
|
|---|
| 105 | - scripts/ various scripts used by JOSM developers
|
|---|
| 106 | - src/ the source code of the program
|
|---|
| 107 | - start.html HTML page to run the applet version of JOSM
|
|---|
| 108 | - styles/ map styles included in JOSM
|
|---|
| 109 | - sytles_nodist/ files needed for map style maintenance
|
|---|
| 110 | - potlatch2/README infos on how to update the Potlatch 2 style from upstream sources
|
|---|
| 111 | - test/ automated software tests
|
|---|
| 112 | - data/ resources used for some tests
|
|---|
| 113 | - functional/ functional tests (source code)
|
|---|
| 114 | - lib/ libraries needed for (some of) the tests, including JUnit
|
|---|
| 115 | - performance/ performance tests (source code)
|
|---|
| 116 | - unit/ unit tests (source code)
|
|---|
| 117 | - tools/ libraries and tools that help in the development process
|
|---|
| 118 | - animal-sniffer-ant-tasks-1.15.jar
|
|---|
| 119 | used to build and check code signatures to ensure plugins binary compatibility
|
|---|
| 120 | - appbundler-1.0ea.jar used to build Mac OS X package
|
|---|
| 121 | - checkstyle/ libs and config files for checkstyle (automatically detects code style
|
|---|
| 122 | problems in source code); can be launched as an ant target in build.xml
|
|---|
| 123 | - commons-cli-1.3.1.jar dependency of Groovy Ant task
|
|---|
| 124 | - error_prone_ant-2.0.15.jar
|
|---|
| 125 | used to detect code errors during compilation
|
|---|
| 126 | - findbugs/ libs and config files for findbugs (automatically detects common bugs and potential
|
|---|
| 127 | problems in source code); can be launched as an ant target in build.xml
|
|---|
| 128 | - groovy-all-2.4.8.jar used for some unit tests and various scripts
|
|---|
| 129 | - jacocoant.jar used to include coverage data into JUnit test reports
|
|---|
| 130 | - japicc/ used to generate a compatibility report between optimized jar and normal one
|
|---|
| 131 | - javacc.jar used in the build process to generate some .java files from a javacc source file
|
|---|
| 132 | (src/org/openstreetmap/josm/gui/mappaint/mapcss/MapCSSParser.jj)
|
|---|
| 133 | - proguard.jar optimize final binary jar - see build.xml (not used in production so far)
|
|---|
| 134 | - xmltask.jar used to edit XML files from Ant for the OSX package
|
|---|
| 135 | - windows/ files needed to create the Windows installer
|
|---|
| 136 |
|
|---|
| 137 | The 'patches' directory
|
|---|
| 138 | -----------------------
|
|---|
| 139 | Some libraries that JOSM depends on, are patched for various reasons. The
|
|---|
| 140 | files in the patches directory can be used to roll back these customizations.
|
|---|
| 141 | This is useful in order to
|
|---|
| 142 | * inspect the changes
|
|---|
| 143 | * update to a newer version of the library but keep the modifications
|
|---|
| 144 |
|
|---|
| 145 | You can use 'quilt' to manage the patches. E.g. the following command applies all of them:
|
|---|
| 146 |
|
|---|
| 147 | $ quilt push -a
|
|---|
| 148 |
|
|---|
| 149 | Of course, it is also possible to apply the patch files manually one by one.
|
|---|
| 150 |
|
|---|
| 151 | Third party libraries
|
|---|
| 152 | ---------------------
|
|---|
| 153 | There are some third party libraries which are directly included in the source code tree, in particular:
|
|---|
| 154 |
|
|---|
| 155 | * jmapviewer: Java component to browse a TMS map
|
|---|
| 156 | src/org/openstreetmap/gui (svn external)
|
|---|
| 157 | -> http://svn.openstreetmap.org/applications/viewer/jmapviewer/
|
|---|
| 158 | * Apache commons compress: Support for bzip2 compression when opening files
|
|---|
| 159 | src/org/apache/commons/compress/compressors (svn external)
|
|---|
| 160 | -> https://github.com/apache/commons-compress
|
|---|
| 161 | * Apache commons validator: Improved validator routines
|
|---|
| 162 | src/org/openstreetmap/josm/data/validation/routines
|
|---|
| 163 | -> http://commons.apache.org/proper/commons-validator
|
|---|
| 164 | * SVG Salamander: Support for SVG image format
|
|---|
| 165 | src/com/kitfox/svg
|
|---|
| 166 | -> https://github.com/blackears/svgSalamander
|
|---|
| 167 | * Metadata Extractor: Read EXIF Metadata of photos
|
|---|
| 168 | src/com/drew
|
|---|
| 169 | -> https://github.com/drewnoakes/metadata-extractor
|
|---|
| 170 | * Signpost: OAuth library
|
|---|
| 171 | src/oauth, src/com/google
|
|---|
| 172 | -> https://github.com/mttkay/signpost
|
|---|
| 173 | * GNU getopt Java port: Command line argument processing library
|
|---|
| 174 | src/gnu/getopt
|
|---|
| 175 | -> https://github.com/arenn/java-getopt
|
|---|
| 176 | * MultiSplitPane: Small lib for GUI layout management
|
|---|
| 177 | src/org/openstreetmap/josm/gui/MultiSplitLayout.java, MultiSplitPane.java
|
|---|
| 178 | -> http://today.java.net/pub/a/today/2006/03/23/multi-split-pane.html
|
|---|
| 179 | -> https://community.oracle.com/docs/DOC-983539
|
|---|
| 180 | * swinghelper: Class CheckThreadViolationRepaintManager to find classpath violations
|
|---|
| 181 | src/org/jdesktop/swinghelper/debug/CheckThreadViolationRepaintManager.java
|
|---|
| 182 | -> https://java.net/projects/swinghelper
|
|---|
