Subversion Repositories mkgmap

=== Tuning ===

Building a map is a resource intensive process that may take several hours to complete.
To minimise execution time and make sure the process does not run out of memory, it is necessary to tune the process using command line options.

Mkgmap is designed to allow multi-threaded operation and, providing sufficient memory is available, will complete in the shortest time if the number of threads used is the same as the number of CPU cores available.
Each input file is processed in a separate thread with a scheduler determining when a thread is available for use and which input file is next to be processed.
You can specify the maximum number of threads to be used by mkgmap with the --max-jobs option.
If you do not specify this option, mkgmap will attempt to determine how many threads it can handle simultaneously by dividing the available heap memory by the amount of memory used when processing the first input file on the command line.
In this case, it is important to make sure that the first input file is representative of the other files.
If one of your input files is a typ file and you do not specify --max-jobs in your command line, make sure that the typ file is not the first input file specified.
As typ file compilation uses few resources this would be likely to lead mkgmap to believe it could run more simultaneous jobs than is realistic.

If mkgmap crashes with a message that it is out of memory, or it does not use all the available cores, you may need to allow it to use more memory.
Typically, mkgmap requires about 500MB of heap memory per thread, so an 8-core processor might need 4GB memory to be allocated to the Java heap.
You can specify the maximum Java heap size using the -Xmx Java option. 
Note that this option needs to be specified before -jar mkgmap.jar, unlike the mkgmap options, which are specified after.
The format is -Xmx<size>[g|G|m|M|k|K] where g, m and k indicate gigabytes, megabytes and kilobytes respectively, so to specify 4GB use -Xmx4g.
Note that there is no space or equals sign in this option.

After processing all the input files, any required processes that operate on all tiles are undertaken.
This includes generating a gmapsupp.img file if --gmapsupp is specified, and creating indexes if --index is specified.
If the --gmapsupp and --index options are both specified along with any of --tdbfile, --gmapi, or --nsis then two indexes will be created.
This is likely to require roughly twice as much memory.
If you run out of memory at this stage, rather than increasing the amount of memory you may find it beneficial to separate these tasks into separate commands, with --gmapsupp and --index in one command and --index and --tdbfile, --gmapi, or --nsis in another.