| 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 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 | - gpx/ different color gradients for gpx drawing
|
|---|
| 63 | - projection/ projection files
|
|---|
| 64 | - custom-epsg list of projection definitions, auto-generated file created by ant task 'epsg'
|
|---|
| 65 | - security/*.pem certificates that we like to accept for TLS connections, but are missing in the
|
|---|
| 66 | default Java certificate store
|
|---|
| 67 | - validator/ data files used by the JOSM validator
|
|---|
| 68 | - *.cfg files designed for the old tagchecker, still in use
|
|---|
| 69 | - *.mapcss default validation rules for the MapCSS-based tagchecker
|
|---|
| 70 | - opening_hours.js Javascript code to validate opening hours tag
|
|---|
| 71 | (external library, see https://github.com/opening-hours/opening_hours.js)
|
|---|
| 72 | - boundaries.osm OSM file containing boundary data for the states of the earth, including
|
|---|
| 73 | data for right and left-hand traffic
|
|---|
| 74 | - defaultpresets.xml data file for the core tagging presets
|
|---|
| 75 | - help-browser.css CSS file for the help sites (HTML content is downloaded from the website
|
|---|
| 76 | on demand, but displayed inside the programm in a Java web browser component.)
|
|---|
| 77 | - overpass-wizard.js Javascript code to provide a wizard-GUI for creating Overpass requests
|
|---|
| 78 | (external library, see https://github.com/tyrasd/overpass-wizard)
|
|---|
| 79 | - *.lang translation data
|
|---|
| 80 | - *.xsd xml schema files for validation of configuration files
|
|---|
| 81 | - data_nodist/ data files that are useful for development, but not distributed
|
|---|
| 82 | - exif-direction-example.jpg
|
|---|
| 83 | sample image, that contains direction information in the EXIF header
|
|---|
| 84 | (keys: Exif.GPSInfo.GPSImgDirectionRef, Exif.GPSInfo.GPSImgDirection)
|
|---|
| 85 | - filterTests.osm used for unit testing of the filter feature
|
|---|
| 86 | (see test/unit/org/openstreetmap/josm/data/osm/FilterTest.java)
|
|---|
| 87 | - Join_Areas_Tests.osm some examples to test the 'join areas' feature
|
|---|
| 88 | - *.* various other data files used for unit testing and as reference file
|
|---|
| 89 | - projection/ projection files
|
|---|
| 90 | - *.gsb NTv2 grid files for projection support, downloaded by the
|
|---|
| 91 | client on demand (see CONTRIBUTION)
|
|---|
| 92 | - CHENyx06-Distribution.pdf
|
|---|
| 93 | archive of terms of use for the CHENyx06.gsb file
|
|---|
| 94 | - epsg EPSG data file, taken from the proj.4 project
|
|---|
| 95 | (see https://github.com/OSGeo/proj.4/blob/master/nad/epsg)
|
|---|
| 96 | - esri ESRI data file, taken from the proj.4 project
|
|---|
| 97 | (see https://github.com/OSGeo/proj.4/blob/master/nad/esri)
|
|---|
| 98 | - josm-epsg customizations to the epsg file, used together with the epsg file
|
|---|
| 99 | to generate data/projection/custom-epsg
|
|---|
| 100 |
|
|---|
| 101 | - projection-reference-data.csv
|
|---|
| 102 | reference data for projection tests
|
|---|
| 103 | (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRefTest.java)
|
|---|
| 104 | - projection-regression-test-data.csv
|
|---|
| 105 | regression data for projection tests
|
|---|
| 106 | (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRegressionTest.java)
|
|---|
| 107 | - trans/*.lang translation data for files that are not distributed, but used
|
|---|
| 108 | by the server for localization of the services;
|
|---|
| 109 | currently contains plugin descriptions in order to include translations
|
|---|
| 110 | in the downloaded plugin list
|
|---|
| 111 | - gpl-2.0.txt, gpl-3.0.txt full text of the GNU General Public License
|
|---|
| 112 | - images/ images distributed with the JOSM binary
|
|---|
| 113 | - icons images for the Potlatch 2 style
|
|---|
| 114 | - presets images for the main mappaint style and the internal presets
|
|---|
| 115 | - images_nodist/ images, which are not for distribution, but may be useful later (e.g. high
|
|---|
| 116 | resolution and vector versions)
|
|---|
| 117 | - josm.jnlp Java Web Start launcher file (used on the website for the tested version)
|
|---|
| 118 | - josm-latest.jnlp Java Web Start launcher file (used on the website for the latest version)
|
|---|
| 119 | - LICENSE the JOSM license terms
|
|---|
| 120 | - linux/ files useful for Linux distributions, including Appdata files, .desktop
|
|---|
| 121 | files, Debian/Ubuntu scripts, man pages, icons, etc.
|
|---|
| 122 | - macosx/ files needed to create the MacOS X package
|
|---|
| 123 | - netbeans/ preconfigured Netbeans project
|
|---|
| 124 | - patches/ patches for external libraries used in JOSM (see below)
|
|---|
| 125 | - README this file
|
|---|
| 126 | - resources/ resource files that will be included in the JOSM jar file
|
|---|
| 127 | - scripts/ various scripts used by JOSM developers
|
|---|
| 128 | - BuildProjectionDefinitions.java
|
|---|
| 129 | called from the ant build file to combine the files epsg and josm-epsg
|
|---|
| 130 | to create the custom-epsg file for distribution
|
|---|
| 131 | - geticons.pl tool to find all used icons and allows deleting unused icons
|
|---|
| 132 | searches also for images with incompatible svg code
|
|---|
| 133 | - optimize-images short script to decrease size of PNG images
|
|---|
| 134 | - presets_lang.pl helper script to update language links in presets file
|
|---|
| 135 | - since_xxx.py developer tool to replace "@since xxx" in Javadoc by the upcoming revision number
|
|---|
| 136 | - SyncEditorLayerIndex.groovy
|
|---|
| 137 | script to compare and analyse the differences of the editor layer index and the
|
|---|
| 138 | JOSM imagery list (see https://josm.openstreetmap.de/wiki/ImageryCompare)
|
|---|
| 139 | - TagInfoExtract.groovy extracts tag information for the taginfo project
|
|---|
| 140 | - src/ the source code of the application
|
|---|
| 141 | - start.html HTML page to run the applet version of JOSM
|
|---|
| 142 | - styles/ map styles included in JOSM
|
|---|
| 143 | - sytles_nodist/ files needed for map style maintenance
|
|---|
| 144 | - potlatch2/README infos on how to update the Potlatch 2 style from upstream sources
|
|---|
| 145 | - test/ automated software tests
|
|---|
| 146 | - data/ resources used for some tests
|
|---|
| 147 | - functional/ functional tests (source code)
|
|---|
| 148 | - lib/ libraries needed for (some of) the tests, including JUnit
|
|---|
| 149 | - performance/ performance tests (source code)
|
|---|
| 150 | - unit/ unit tests (source code)
|
|---|
| 151 | - tools/ libraries and tools that help in the development process
|
|---|
| 152 | - animal-sniffer-ant-tasks.jar
|
|---|
| 153 | used to build and check code signatures to ensure plugins binary compatibility
|
|---|
| 154 | - appbundler-1.0ea.jar used to build Mac OS X package
|
|---|
| 155 | - checkstyle/ libs and config files for checkstyle (automatically detects code style
|
|---|
| 156 | problems in source code); can be launched as an ant target in build.xml
|
|---|
| 157 | - commons-cli-1.3.1.jar dependency of Groovy Ant task
|
|---|
| 158 | - error_prone_ant.jar used to detect code errors during compilation
|
|---|
| 159 | - spotbugs/ libs and config files for spotbugs (automatically detects common bugs and potential
|
|---|
| 160 | problems in source code); can be launched as an ant target in build.xml
|
|---|
| 161 | - groovy-all.jar used for some unit tests and various scripts
|
|---|
| 162 | - jacocoant.jar used to include coverage data into JUnit test reports
|
|---|
| 163 | - japicc/ used to generate a compatibility report between optimized jar and normal one
|
|---|
| 164 | - javacc.jar used in the build process to generate some .java files from a javacc source file
|
|---|
| 165 | (src/org/openstreetmap/josm/gui/mappaint/mapcss/MapCSSParser.jj)
|
|---|
| 166 | - proguard.jar optimize final binary jar - see build.xml (not used in production so far)
|
|---|
| 167 | - xmltask.jar used to edit XML files from Ant for the OSX package
|
|---|
| 168 | - windows/ files needed to create the Windows installer
|
|---|
| 169 |
|
|---|
| 170 | The 'patches' directory
|
|---|
| 171 | -----------------------
|
|---|
| 172 | Some libraries that JOSM depends on, are patched for various reasons. The
|
|---|
| 173 | files in the patches directory can be used to roll back these customizations.
|
|---|
| 174 | This is useful in order to
|
|---|
| 175 | * inspect the changes
|
|---|
| 176 | * update to a newer version of the library but keep the modifications
|
|---|
| 177 |
|
|---|
| 178 | You can use 'quilt' to manage the patches. E.g. the following command applies all of them:
|
|---|
| 179 |
|
|---|
| 180 | $ quilt push -a
|
|---|
| 181 |
|
|---|
| 182 | Of course, it is also possible to apply the patch files manually one by one.
|
|---|
| 183 |
|
|---|
| 184 | Third party libraries
|
|---|
| 185 | ---------------------
|
|---|
| 186 | There are some third party libraries which are directly included in the source code tree, in particular:
|
|---|
| 187 |
|
|---|
| 188 | * jmapviewer: Java component to browse a TMS map
|
|---|
| 189 | src/org/openstreetmap/gui (svn external)
|
|---|
| 190 | -> http://svn.openstreetmap.org/applications/viewer/jmapviewer/
|
|---|
| 191 | * Apache commons compress: Support for bzip2 compression when opening files
|
|---|
| 192 | src/org/apache/commons/compress/compressors (svn external)
|
|---|
| 193 | -> https://github.com/apache/commons-compress
|
|---|
| 194 | * Apache commons validator: Improved validator routines
|
|---|
| 195 | src/org/openstreetmap/josm/data/validation/routines
|
|---|
| 196 | -> http://commons.apache.org/proper/commons-validator
|
|---|
| 197 | * SVG Salamander: Support for SVG image format
|
|---|
| 198 | src/com/kitfox/svg
|
|---|
| 199 | -> https://github.com/blackears/svgSalamander
|
|---|
| 200 | * Metadata Extractor: Read EXIF Metadata of photos
|
|---|
| 201 | src/com/drew
|
|---|
| 202 | -> https://github.com/drewnoakes/metadata-extractor
|
|---|
| 203 | * Signpost: OAuth library
|
|---|
| 204 | src/oauth, src/com/google
|
|---|
| 205 | -> https://github.com/mttkay/signpost
|
|---|
| 206 | * GNU getopt Java port: Command line argument processing library
|
|---|
| 207 | src/gnu/getopt
|
|---|
| 208 | -> https://github.com/arenn/java-getopt
|
|---|
| 209 | * MultiSplitPane: Small lib for GUI layout management
|
|---|
| 210 | src/org/openstreetmap/josm/gui/MultiSplitLayout.java, MultiSplitPane.java
|
|---|
| 211 | -> https://github.com/floscher/multi-split
|
|---|
| 212 | -> https://community.oracle.com/docs/DOC-983539
|
|---|
| 213 | * swinghelper: Class CheckThreadViolationRepaintManager to find classpath violations
|
|---|
| 214 | src/org/jdesktop/swinghelper/debug/CheckThreadViolationRepaintManager.java
|
|---|
| 215 | -> https://github.com/floscher/swinghelper
|
|---|
| 216 | * xz extractor
|
|---|
| 217 | src/org/tukaani
|
|---|
| 218 | -> https://tukaani.org/xz/java.html
|
|---|
