Index: doc/options.txt =================================================================== --- doc/options.txt (revision 4270) +++ doc/options.txt (working copy) @@ -1,8 +1,105 @@ -Note that option order is significant: An option only -applies to subsequent input files. So if you are using splitter, you probably -want to put most of your options before '-c template.args'. - - +=== Background === + +The mkgmap program is distributed in Java archive format compiled for +use under the Java Runtime Environment 8. You will need the Java SE +Runtime Environment 8 installed on your system in order to run mkgmap. + +Garmin maps consist of a series of .img files, with each file +containing the data for one tile of the map. Unless you intend to +build a very small map, you will need to use the accompanying splitter +program to split your map into smaller tiles. The individual tiles +can be joined together to produce a single gmapsupp.img file which +contains the whole map and can be copied into the /Garmin folder of +an SD card for use by a GPS device. If you want to create more than +one map for use on your GPS, the gmapsupp.img files can be renamed +to be unique, for example gmapsupp1.img, gmapsupp2.img. + +=== Command line === + +The command line is of the format: + +java.exe [java-options] –jar mkgmap.jar [mkgmap-options] + +A typical simple example using both splitter and mkgmap: + +java.exe -Xmx2g -jar splitter.jar england-latest.o5m +java.exe -jar mkgmap.jar --gmapsupp -c template.args + +The first command splits the Open Street Map data into smaller files +with each file containing the data for one tile of the map. It also +produces a file named template.args that contains the names of all +the generated files. + +The second command takes as input all the individual files listed +in the template.args file generated by splitter, produces a .img +file for each tile, then merges all the tiles together into a +single gmapsupp.img file. + +=== Java options === + +Details of the Java options are available at docs.oracle.com. +The most likely options you may need to use are: + +;-Xmx[g|G|m|M|k|K] +: Use this option to set the maximum Java heap size in GB, MB, KB or bytes. +Mkgmap allows the use of multiple CPU cores and the amount of heap memory +required increases proportionally with the number of CPU cores being used. +The default value may not be sufficient to allow mkgmap to use all the +available CPU cores, which will cause the run time to be longer than +necessary. To allow mkgmap to run optimally, you may need to use this +option to allow more memory to be allocated to the Java heap. Typically, +mkgmap requires about 500MB per core, so an 8-core processor might need +to specify –Xmx4g – note there is no space or equals sign in the option. + +;-enableassertions +: Causes an error to be thrown if an assertion written in the mkgmap code +is evaluated as not true. This is useful in detecting bugs in the mkgmap +code. + +;-Dlog.config=filename +: Specifies a logging configuration file that allows you to enable and +disable specific logging messages. This is useful if you want to see +certain types of message that are not logged by default or choose where +the messages should be written. The configuration file contains details +of the handler(s) used to write the messages, parameters used to format +the messages and the severity of messages that should be logged at Java +package or class level, plus a default value. An example file is: + +# The default level FINE, WARNING, INFO, SEVERE +.level=SEVERE +#handlers: java.util.logging.ConsoleHandler +handlers: java.util.logging.FileHandler java.util.logging.ConsoleHandler +# package or class name with .level appended and then the level +uk.me.parabola.imgfmt.level=INFO +uk.me.parabola.mkgmap.build.level=INFO +uk.me.parabola.mkgmap.main.Main.level=INFO +uk.me.parabola.mkgmap.main.MapMaker.level=INFO +uk.me.parabola.mkgmap.general.RoadNetwork.level=INFO +uk.me.parabola.mkgmap.general.MapLine.level=INFO +uk.me.parabola.mkgmap.osmstyle.level=INFO +uk.me.parabola.mkgmap.reader.osm.level=INFO +uk.me.parabola.mkgmap.reader.osm.xml.level=INFO +uk.me.parabola.mkgmap.reader.osm.RestrictionRelation.level=FINE +uk.me.parabola.mkgmap.reader.osm.Restriction.level=FINE +# For ConsoleHandler +java.util.logging.ConsoleHandler.level=WARNING +java.util.logging.ConsoleHandler.formatter=uk.me.parabola.log.UsefulFormatter +# For FileHandler +java.util.logging.FileHandler.level=FINE +java.util.logging.FileHandler.encoding=UTF-8 +java.util.logging.FileHandler.formatter=uk.me.parabola.log.UsefulFormatter +java.util.logging.FileHandler.limit=20000000 +java.util.logging.FileHandler.count=4 +java.util.logging.FileHandler.pattern=mkgmap.log +java.util.logging.FileHandler.append=false + +=== Mkgmap options === + +The order of the options is significant in that options only apply +to subsequent input files. If you are using splitter, you probably +will need to put most of your options before '-c template.args' +(this file is generated by splitter). + === General options === ;--help=topic @@ -15,8 +112,8 @@ === File options === ;--input-file=filename -: Read input data from the give file. This option (or just a -filename) may be given more than once. Make sure to set all +: Read input data from the given file. This option (or just a +filename) may be specified more than once. Make sure you set all wanted options before using this. ;--gmapsupp Index: resources/help/en/options =================================================================== --- resources/help/en/options (revision 4270) +++ resources/help/en/options (working copy) @@ -1,7 +1,105 @@ -Note that option order is significant: An option only applies to -subsequent input files. (So if you are using splitter, you probably -want to put most of your options before '-c template.args'.) +Background +The mkgmap program is distributed in Java archive format compiled for +use under the Java Runtime Environment 8. You will need the Java SE +Runtime Environment 8 installed on your system in order to run mkgmap. + +Garmin maps consist of a series of .img files, with each file +containing the data for one tile of the map. Unless you intend to +build a very small map, you will need to use the accompanying splitter +program to split your map into smaller tiles. The individual tiles +can be joined together to produce a single gmapsupp.img file which +contains the whole map and can be copied into the /Garmin folder of +an SD card for use by a GPS device. If you want to create more than +one map for use on your GPS, the gmapsupp.img files can be renamed +to be unique, for example gmapsupp1.img, gmapsupp2.img. + +Command line + +The command line is of the format: + + java.exe [java-options] –jar mkgmap.jar [mkgmap-options] + +A typical simple example using both splitter and mkgmap: + + java.exe -Xmx2g -jar splitter.jar england-latest.o5m + java.exe -jar mkgmap.jar --gmapsupp -c template.args + +The first command splits the Open Street Map data into smaller files +with each file containing the data for one tile of the map. It also +produces a file named template.args that contains the names of all +the generated files. + +The second command takes as input all the individual files listed +in the template.args file generated by splitter, produces a .img +file for each tile, then merges all the tiles together into a +single gmapsupp.img file. + +Java options + +Details of the Java options are available at docs.oracle.com. +The most likely options you may need to use are: + +-Xmx[g|G|m|M|k|K] + Use this option to set the maximum Java heap size in GB, MB, KB or bytes. + Mkgmap allows the use of multiple CPU cores and the amount of heap memory + required increases proportionally with the number of CPU cores being used. + The default value may not be sufficient to allow mkgmap to use all the + available CPU cores, which will cause the run time to be longer than + necessary. To allow mkgmap to run optimally, you may need to use this + option to allow more memory to be allocated to the Java heap. Typically, + mkgmap requires about 500MB per core, so an 8-core processor might need + to specify –Xmx4g – note there is no space or equals sign in the option. + +-enableassertions + Causes an error to be thrown if an assertion written in the mkgmap code + is evaluated as not true. This is useful in detecting bugs in the mkgmap + code. + +-Dlog.config=filename + Specifies a logging configuration file that allows you to enable and + disable specific logging messages. This is useful if you want to see + certain types of message that are not logged by default or choose where + the messages should be written. The configuration file contains details + of the handler(s) used to write the messages, parameters used to format + the messages and the severity of messages that should be logged at Java + package or class level, plus a default value. An example file is: + +# The default level FINE, WARNING, INFO, SEVERE +.level=SEVERE +#handlers: java.util.logging.ConsoleHandler +handlers: java.util.logging.FileHandler java.util.logging.ConsoleHandler +# package or class name with .level appended and then the level +uk.me.parabola.imgfmt.level=INFO +uk.me.parabola.mkgmap.build.level=INFO +uk.me.parabola.mkgmap.main.Main.level=INFO +uk.me.parabola.mkgmap.main.MapMaker.level=INFO +uk.me.parabola.mkgmap.general.RoadNetwork.level=INFO +uk.me.parabola.mkgmap.general.MapLine.level=INFO +uk.me.parabola.mkgmap.osmstyle.level=INFO +uk.me.parabola.mkgmap.reader.osm.level=INFO +uk.me.parabola.mkgmap.reader.osm.xml.level=INFO +uk.me.parabola.mkgmap.reader.osm.RestrictionRelation.level=FINE +uk.me.parabola.mkgmap.reader.osm.Restriction.level=FINE +# For ConsoleHandler +java.util.logging.ConsoleHandler.level=WARNING +java.util.logging.ConsoleHandler.formatter=uk.me.parabola.log.UsefulFormatter +# For FileHandler +java.util.logging.FileHandler.level=FINE +java.util.logging.FileHandler.encoding=UTF-8 +java.util.logging.FileHandler.formatter=uk.me.parabola.log.UsefulFormatter +java.util.logging.FileHandler.limit=20000000 +java.util.logging.FileHandler.count=4 +java.util.logging.FileHandler.pattern=mkgmap.log +java.util.logging.FileHandler.append=false + +Mkgmap options: + +The order of the options is significant in that options only apply +to subsequent input files. If you are using splitter, you probably +will need to put most of your options before '-c template.args' +(this file is generated by splitter). + General options: --help=topic @@ -13,8 +111,8 @@ filename --input-file=filename - Read input data from the give file. This option (or just a - filename) may be given more than once. Make sure to set all + Read input data from the given file. This option (or just a + filename) may be specified more than once. Make sure you set all wanted options before using this. --gmapsupp @@ -868,7 +966,6 @@ --charset=name Obsolete; use --code-page instead. - option. --map-features=filename Obsolete; use --style-file instead.