Supplemental information for JOSM -- the Java OpenStreetMap Editor ============================================================================= I. Install & Launch ============================================================================= Installation notes ------------------ To run JOSM, you need: * The JOSM .jar file, e.g., josm-tested.jar or josm-latest.jar * Java Runtime Environment (JRE) 8, or later. How to get Java Runtime Environment ----------------------------------- You need JRE Version 8, or later. Microsoft Windows and Apple Mac OS X users should visit https://www.java.com and download the latest Java executable for their system. Linux users should visit http://www.oracle.com/technetwork/java/index.html There is a Linux binary installer, which you must execute from a console, or use the mechanism of your distribution's packaging system. How to launch ------------- Microsoft Windows users launch by double-clicking on the .jar file. If this does not work, open a command shell and type "java -jar josm-latest.jar" in the directory that holds the file. (Please replace josm-latest.jar with the name of your .jar file, if you aren't using the latest version.) Under Linux, open a shell, go to the file directory and type "java -jar josm-latest.jar" to launch. If this does not work, try to set your JAVA_HOME variable to the java executable location (the root location, not the bin). macOS users just click on the .jar file icon. ============================================================================= II. Development ============================================================================= How to get the source code -------------------------- Download it directly from the subversion at https://josm.openstreetmap.de/svn/trunk. To use the command line subversion client, type svn co https://josm.openstreetmap.de/svn/trunk josm Files & directories ------------------- This is an overview of the files and directories in the JOSM code repository: - build.xml ant build file (standard way to create a JOSM binary) - CONTRIBUTION list of major code contributors - gpl-2.0.txt, gpl-3.0.txt full text of the GNU General Public License - ide IDE-specific files - eclipse/ preconfigured Eclipse configuration files - netbeans/ preconfigured Netbeans project - josm.jnlp Java Web Start launcher file (used on the website for the tested version) - josm-latest.jnlp Java Web Start launcher file (used on the website for the latest version) - LICENSE the JOSM license terms - native/ OS-specific files - linux/ files useful for Linux distributions, including Appdata files, .desktop files, Debian/Ubuntu scripts, man pages, icons, etc. - macosx/ files needed to create the MacOS package - windows/ files needed to create the Windows installer - nodist/ files not included in JOSM binary - data/ data files that are useful for development, but not distributed - exif-direction-example.jpg sample image, that contains direction information in the EXIF header (keys: Exif.GPSInfo.GPSImgDirectionRef, Exif.GPSInfo.GPSImgDirection) - filterTests.osm used for unit testing of the filter feature (see test/unit/org/openstreetmap/josm/data/osm/FilterTest.java) - Join_Areas_Tests.osm some examples to test the 'join areas' feature - *.* various other data files used for unit testing and as reference file - projection/ projection files - *.gsb NTv2 grid files for projection support, downloaded by the client on demand (see CONTRIBUTION) - CHENyx06-Distribution.pdf archive of terms of use for the CHENyx06.gsb file - epsg EPSG data file, taken from the proj.4 project (see https://github.com/OSGeo/proj.4/blob/master/nad/epsg) - esri ESRI data file, taken from the proj.4 project (see https://github.com/OSGeo/proj.4/blob/master/nad/esri) - josm-epsg customizations to the epsg file, used together with the epsg file to generate data/projection/custom-epsg - projection-reference-data.csv reference data for projection tests (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRefTest.java) - projection-regression-test-data.csv regression data for projection tests (see test/unit/org/openstreetmap/josm/data/projection/ProjectionRegressionTest.java) - trans/*.lang translation data for files that are not distributed, but used by the server for localization of the services; currently contains plugin descriptions in order to include translations in the downloaded plugin list - images/ images, which are not for distribution, but may be useful later (e.g. high resolution and vector versions) - styles/ files needed for map style maintenance - potlatch2/README infos on how to update the Potlatch 2 style from upstream sources - README this file - resources/ resource files that will be included in the JOSM jar file - data/ data files that will be included in the JOSM jar file - fonts/ font files used for map rendering - gpx/ different color gradients for gpx drawing - projection/ projection files - custom-epsg list of projection definitions, auto-generated file created by ant task 'epsg' - security/*.pem certificates that we like to accept for TLS connections, but are missing in the default Java certificate store - validator/ data files used by the JOSM validator - *.cfg files designed for the old tagchecker, still in use - *.mapcss default validation rules for the MapCSS-based tagchecker - boundaries.osm OSM file containing boundary data for the states of the earth, including data for right and left-hand traffic - defaultpresets.xml data file for the core tagging presets - help-browser.css CSS file for the help sites (HTML content is downloaded from the website on demand, but displayed inside the programm in a Java web browser component.) - *.lang translation data - *.xsd xml schema files for validation of configuration files - images/ images distributed with the JOSM binary - icons images for the Potlatch 2 style - presets images for the main mappaint style and the internal presets - styles/ map styles included in JOSM - scripts/ various scripts used by JOSM developers - BuildProjectionDefinitions.java called from the ant build file to combine the files epsg and josm-epsg to create the custom-epsg file for distribution - geticons.pl tool to find all used icons and allows deleting unused icons searches also for images with incompatible svg code - optimize-images short script to decrease size of PNG images - since_xxx.py developer tool to replace "@since xxx" in Javadoc by the upcoming revision number - SyncEditorLayerIndex.java script to compare and analyse the differences of the editor layer index and the JOSM imagery list (see https://josm.openstreetmap.de/wiki/ImageryCompare) - TagInfoExtract.java extracts tag information for the taginfo project - src/ the source code of the application - start.html HTML page to run the applet version of JOSM - test/ automated software tests - data/ resources used for some tests - functional/ functional tests (source code) - lib/ libraries needed for (some of) the tests, including JUnit - performance/ performance tests (source code) - unit/ unit tests (source code) - tools/ libraries and tools that help in the development process - animal-sniffer-ant-tasks.jar used to build and check code signatures to ensure plugins binary compatibility - checkstyle/ libs and config files for checkstyle (automatically detects code style problems in source code); can be launched as an ant target in build.xml - ivy/ Apache Ivy binary, configuration file, and downloaded dependencies - jacocoant.jar used to include coverage data into JUnit test reports - japicc/ used to generate a compatibility report between optimized jar and normal one - spotbugs/ libs and config files for spotbugs (automatically detects common bugs and potential problems in source code); can be launched as an ant target in build.xml Third party libraries --------------------- There are some third party libraries which are directly included in the source code tree, in particular: * jmapviewer: Java component to browse a TMS map src/org/openstreetmap/gui (svn external) -> https://josm.openstreetmap.de/osmsvn/applications/viewer/jmapviewer/ * Apache commons compress: Support for bzip2 compression when opening files -> https://github.com/apache/commons-compress * Apache commons validator: Improved validator routines src/org/openstreetmap/josm/data/validation/routines -> http://commons.apache.org/proper/commons-validator * SVG Salamander: Support for SVG image format src/com/kitfox/svg -> https://github.com/blackears/svgSalamander * Metadata Extractor: Read EXIF Metadata of photos -> https://github.com/drewnoakes/metadata-extractor * Signpost: OAuth library -> https://github.com/mttkay/signpost * MultiSplitPane: Small lib for GUI layout management src/org/openstreetmap/josm/gui/MultiSplitLayout.java, MultiSplitPane.java -> https://github.com/floscher/multi-split -> https://community.oracle.com/docs/DOC-983539 * swinghelper: Class CheckThreadViolationRepaintManager to find EDT violations src/org/openstreetmap/josm/gui/util/CheckThreadViolationRepaintManager.java -> https://github.com/floscher/swinghelper * xz extractor -> https://tukaani.org/xz/java.html * OpeningHoursParser (MIT license) -> https://github.com/simonpoole/OpeningHoursParser