Changes between Version 24 and Version 25 of Help/CommandLineOptions

2018-02-11T19:40:23+01:00 (6 months ago)

Complete review after ticket:15894, Smaller list of arguments and examples to fit in 90 chars width


  • Help/CommandLineOptions

    v24 v25  
    22= Command Line Options =
    4 unfinished hb-
     4No table of content.
    6 Starting JOSM is affected by three groups of command line options.
    7 Most important are the ''Programm arguments'' and also the ''Java options''. The ''run-options'' are involved in Web Start only. 
     6JOSM is affected by three groups of command line options.
     7The [#Programarguments Program arguments] are most important and than the [#Javaoptions Java options]. Only involved in Web Start are the [#run-options run-options]. See [#Examples Examples]
    1111# Running a jar
    12 java [Java options] -jar josm-tested.jar [Programm arguments]
     12java [Java options] -jar josm-tested.jar [Program arguments]
    14 # Web Start
    15 javaws [run-options] josm.jnlp
     14# Launch a Web Start
     15javaws [run-options] -J[Java option] josm.jnlp
     18=== Program arguments ===#Programarguments
    19 Java Virtual Machine options::
    20  Control the handler of virtual machine, for example `--Xmx2048m`. The `--jar jarfile` part is a java option, too.
    21  Control the environment inside the virtual machine for JOSM, for example `-Djosm.home=/home/user/.josm_dev`
    22 WebStart run-options::
    23  Control the startup of the handler, for example `-J--Xmx2048m` to hand over the string 'Xmx2048m' to the JVM
    24 `--offline`
     20Also called ''Post jar arguments'' here or ''args'' by Oracle.
     22The first argument is seen as ''command'' by JOSM. The possible commands are `runjosm` for normal launch (default), `render` for generating an image file and `project` converting coordinates. If JOSM can't recognize a command the default is assumed.
     24The following arguments are ''options'' for JOSM. They are separated by spaces. They can be URLs, filenames, coordinates, simple options and option=argument pairs. The complete list of commands and options is shown below:
     28  java <java options> -jar josm.jar [<command>] <options>
     31  runjosm     launch JOSM (default, performed when no command is specified)
     32  render      render data and save the result to an image file
     33  project     convert coordinates from one coordinate reference system to another
     35For details on the render and project commands, run them with the --help option.
     36The remainder of this help page documents the runjosm command.
     39  --help|-h                                 Show this help
     40  --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
     41  [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
     42  [--download=]<URL>                        Download the location URL which has
     43                                            coordinates like lat=x&lon=y&zoom=z
     44  [--download=]<filename>                   Open a file (same as Menu/File/Open)
     45  --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
     46  --downloadgps=<URL>                       Download the location as raw GPS
     47  --selection=<searchstring>                Select with the given search
     48  --[no-]maximize                           Launch in maximized mode
     49  --reset-preferences                       Reset the preferences to default
     50  --load-preferences=<url-to-xml>           Import preferences from XML file
     51  --set=<key>=<value>                       Set preference key to value
     52  --language=<language>                     Set the language
     53  --version                                 Displays the JOSM version and exits
     54  --debug                                   Print debugging messages to console
     55  --skip-plugins                            Skip loading plugins
     56  --offline=[osm_api,][josm_website,][all]  Disable access to the listed resources
     59The `--download=` part of the download option is optional.
     60The arguments `--download`, `--downloadgps` and `--selection` are processed in this order.
     61The value `<url-to-xml>` can point to a local file with `file:relative/path/name.xml`.
     62The items in the `--offline` value are separated by comma.
    27 === Programm arguments ===#Postjararguments
     65=== Java options ===#Javaoptions
    29 Also called ''Post jar arguments'' here or ''args'' by Java.
    30 The order of these arguments behind the jarfile in the command line is important for some of them.
    32 The first argument is the ''commmand'' for JOSM. The three possible commmands are `one` for normal work, `one` for image and `one` for something other. If JOSM can't recognize a command the default is assumed and the usual GUI is started.
    34 The following arguments can be URLs, coordinates, options with own arguments and filenames. See the output of the --help option below.
     67The Java options are also called ''JOSM JVM options'' here or ''VM arguments'' in the [wiki:/Help/Action/ShowStatusReport Status Report]. In that report you can see them and also the Program Arguments. They control the Java virtual machine [ (JVM)] and can set [ properties] inside it. JOSM reads some of them, for example `josm.home` and `user.language`.
    37 --help|-h                                 Show this help
    38 --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
    39 [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
    40 [--download=]<URL>                        Download the location at the URL (with lat=x&lon=y&zoom=z)
    41 [--download=]<filename>                   Open a file (any file type that can be opened with File/Open)
    42 --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
    43 --downloadgps=<URL>                       Download the location at the URL (with lat=x&lon=y&zoom=z) as raw GPS
    44 --selection=<searchstring>                Select with the given search
    46 --[no-]maximize                           Launch in maximized mode
    47 --reset-preferences                       Reset the preferences to default
    48 --load-preferences=<url-to-xml>           Changes preferences according to the XML file
    49 --set=<key>=<value>                       Set preference key to value
    50 --language=<language>                     Set the language
    51 --version                                 Displays the JOSM version and exits
    52 --debug                                   Print debugging messages to console
    53 --skip-plugins                            Skip loading plugins
    54 --offline=<osm_api|josm_website|all>      Disable access to the given resource(s), separated by comma
     69java options:
     70                      Change the JOSM directory name
     71  -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
     72                                            Default: C:\Users\name\AppData\Roaming\JOSM
     73  -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
     74                                            Default: /home/name/.local/share/JOSM
     75  -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
     76                                            Default: <...>
     77  -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Set the common directory for preferences,
     78                                            user data and ./cache/. Lower precedence.
     79                                            Will get overridden from specific setting.
     80  -Xmx...m                                  Set maximum Java heap size in megabytes.
     81                                            May avoid Out-of-Memory errors.
    57 Make sure you load some data if you use `--selection`.
    58 The --offline list may have commata between its items osm_api,josm_website.
     84The `-Xmx...m` option may be useful when [wiki:/Download#Outofmemory Out of Memory] errors arise.
     85If you set a common directory with `Djosm.home` then JOSM will create the subdirectories ''./autosave'', ''./cache'' and ''./validator''.
     86If a value has spaces, then enclose it in quotation marks like `"josm dev"`.
    60 === Java options ===#JOSMJVMoptions
    62 These options are sometimes called ''JOSM JV options'' in this help or ''VM arguments'' in the JOSM status report.
    64 provided as Java system properties
     88=== run-options ===
     89The run-options follow the `javaws` command. They control the Web Start mechanism and the environment for the JVM.
    66 -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
    67 -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
    68 -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
    69 -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Relocate all 3 directories to homedir.
    70 }}}
    71 `-Djosm.home` has lower precedence, i.e. the specific setting overrides this general one.
    73 For some tasks, JOSM has a large appetite for memory. On the one hand, it may be necessary to configure an  -Xmx memory size that supports more JOSM plugins and other JOSM editing features. On the other hand, slow systems or those systems with few memory resources, can be stabilized by restricting JOSM memory use.  These example Java memory settings provide examples that start with systems that have few memory resources to systems with vast amounts of memory.
    74 {{{
    75 -Xmx...m                                  Set maximum Java heap size in megabytes
    76 -Xmx256m
    77 -Xmx1024m
    78 -Xmx2048m
     91  -offline                  Allows to Web Start JOSM without internet access
     92  -J<java option>           Supplies the <java option> to the JVM
     93  -J-Xmx1024m               Here: Set maximum Java heap size to 1024 megabyte
    81 examples
     96The `-J` run-option takes its part behind the J letter and supplies that as Java option.
     97The [wiki:/Help/jnlpOptions jnlp-File] used by [ Web Start] offers a second way to [  set options] for JRE and for the JOSM program directly.
     100=== Examples ===
    84 java -jar josm.jar track1.gpx track2.gpx london.osm
    85 java -jar josm.jar
    86 java -jar josm.jar london.osm --selection=
    87 java -jar josm.jar 43.2,11.1,43.4,11.4
    88 java -jar josm.jar --set=expert=true
    89 java -Djosm.pref=$XDG_CONFIG_HOME -Djosm.userdata=$XDG_DATA_HOME -Djosm.cache=$XDG_CACHE_HOME -jar josm.jar
    90 java -Djosm.home=/home/user/.josm_dev -jar josm.jar
    91 java -Xmx1024m -jar josm.jar
     103# Load three files
     104  java -jar josm.jar track1.gpx BigBen.jpg "london data.osm"
     105# Download from OSM according to an URL with zoom and coordinates
     106  java -jar josm.jar
     107# Download a bounding box and select every element matching a string
     108  java -jar josm.jar 51.505,-0.14,51.515,-0.13 --selection="Piccadilly Circus"
     110# Set directory for JOSM according to a property from the operating system
     111  java -Djosm.pref=$XDG_CONFIG_HOME jar josm.jar
     112# Quotations for a value with space
     113  java"josm dev" -jar josm.jar
     114# Set the common directory in a sub-subdirectroy below the active command prompt
     115  java -Djosm.home=biketour2017/london -jar josm.jar
     116# More memory in a French spoken environment
     117  java -Xmx1024m -Duser.language=fr -jar josm.jar
     119# Log everything in English
     120  java -verbose  -jar josm-latest.jar --language=en --debug >WhatsUp.txt
    94 Parameters `--download`, `--downloadgps` and `--selection` are processed in this order.
    97 The option group names used here follow the documentation on [ Runtime Engine] and on [ Web Start].
    100123=== See also ===
     124* [wiki:Download#Troubleshooting Troubleshooting Java]
     125* [wiki:InstallNotes Installation notes]
    101126* [wiki:Help/Preferences Preferences] - overview page about all "preferences"
    102 * [[jnlpOptions]]