Index: doc/options.txt =================================================================== --- doc/options.txt (revision 4270) +++ doc/options.txt (working copy) @@ -1,8 +1,74 @@ -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. The configuration +file contains lines in the form + +=== 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,7 +81,7 @@ === File options === ;--input-file=filename -: Read input data from the give file. This option (or just a +: Read input data from the given file. This option (or just a filename) may be given more than once. Make sure to set all wanted options before using this. Index: resources/help/en/options =================================================================== --- resources/help/en/options (revision 4270) +++ resources/help/en/options (working copy) @@ -1,7 +1,74 @@ -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. The configuration + file contains lines in the form + +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,7 +80,7 @@ filename --input-file=filename - Read input data from the give file. This option (or just a + Read input data from the given file. This option (or just a filename) may be given more than once. Make sure to set all wanted options before using this. @@ -76,8 +143,8 @@ Label options: --code-page=number - Specify which international character set is to be used. Only 8 bit - character sets are supported so you have to specify which code page you + Specify which international character set is to be used. Only 8 bit + character sets are supported so you have to specify which code page you want to use. It is entirely dependent on the device firmware which code pages are @@ -132,7 +199,7 @@ See also option road-name-config. --road-name-config=filename - Provide the name of a file containing commonly used road name prefixes + Provide the name of a file containing commonly used road name prefixes and suffixes. This option handles the problem that some countries have road names which often start or end with very similar words, e.g. in France the first word @@ -868,7 +935,6 @@ --charset=name Obsolete; use --code-page instead. - option. --map-features=filename Obsolete; use --style-file instead.