.. index:: installation, requirements, apache, UMN MapServer, compile,
   jar, logging, ArcSDE

------------
Installation from Source
------------
This Documentation describes how you can install MXD2Map from source. If you only
want to use MXD2Map it is strongly recommended that you use our convenient binary
installer.

Requirements
------------

Currently MXD2Map only runs on Windows, because the ArcObjects JDK API does not
work properly on GNU/Linux systems. All Free Software components of MXD2Map can
run on GNU/Linux as well as on Windows.

To run the converter you need at least the following components:

 * Sun Java6 SDK to build, JRE to run
 * ArcGIS Desktop10.x or ArcEngine10.x with a valid licence enabled
 * UMN MapServer with Java MapScript-bindings (>=6.0.1 or recent development-version)

Additionally the following components are recommended:

 * Apache2 Webserver for displaying the resulting Mapfiles
 * MapServer compiled with ArcSDE-plugin
 * GDAL/OGR compiled with ArcSDE-support
 * GDAL/OGR compiled with FileGeodatabase-support
 * Other GDAL/OGR-related tools
 * Sphinx for building the docs

Install Apache Webserver
------------------------
To display the resulting mapfiles directly you need to
install a webserver like Apache2 and the UMN MapServer.

.. important::
   If you are  using `MS4W <http://www.maptools.org/ms4w/>`_, the following installation
   instruction does apply. , although it can be used to preview the `resulting` mapfiles
   MS4W does not provide the needed version to run MXD2map.

Download Apache from https://httpd.apache.org/download.cgi and install it by
executing the .msi-file and following the install-dialogs.

Make sure that you install apache as a service so it is available
directly after system startup.


Install UMN MapServer
---------------------

It is recommended to use the latest binary release version from http://www.gisinternals.com/sdk/
as the MapServer for MXD2Map.

1. Unzip the MapServer ZIP-file at ``c:\ms_6.1-dev``

#. Modify the Apache configuration (e.g. ``c:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf``)
   by adding::

    ScriptAlias /cgi-bin/ "C:/ms_6.1-dev/bin/"

    <Location "/cgi-bin">
        Options None
        Order allow,deny
        Allow from all
    </Location>

    SetEnv PROJ_LIB "c:/ms_6.1-dev/bin/proj/SHARE"
    SetEnv PATH "c:/ms_6.1-dev/bin"
    SetEnv PATH "c:/ms_6.1-dev/bin/gdal/python/osgeo"

    # set GDAL_DATA environment variable to location of supporting gdal files
    SetEnv GDAL_DATA "c:/ms_6.1-dev/bin/gdaldata"

    # set GDAL_DRIVER_PATH environment variable for gdal plugins
    SetEnv GDAL_DRIVER_PATH "c:/ms_6.1-dev/bin/gdal/plugins"


#. Copy mapserv.exe from ``c:\ms_6.1-dev\bin\ms\apps`` to ``c:\ms_6.1-dev\bin\``

#. Optional: Add additional Libraries (DLL's) to ``c:\ms_6.1-dev\bin`` for Oracle, SDE etc.

Install the Converter
------------
The following steps assume the runtime folder to be c:\mxd2map.

1. Download the Source Package from https://mxd2map.org/download.html

#. Extract the tarball using 7-Zip (http://7-zip.org) or something similar to ``c:\mxd2map\``.

#. Create folder ``c:\mxd2map\lib\``

#. Create folder ``c:\mxd2map\logs\``

#. Get log4j from http://logging.apache.org/log4j/1.2/download.html

#. Get jargs http://jargs.sourceforge.net/ (Version 1.0)

#. Get apache commons codec from https://commons.apache.org/codec/download_codec.cgi

#. Copy the jar-files of log4j, jargs and commons codec to ``c:\mxd2map\lib\``

#. Remove the version numbers of the jar file names in lib, or adopt the build.xml accordingly!

#. Copy mapscript.jar and mapscript.dll from your MapServer Installation (e.g. ``c:\ms_6.1-dev\bin\ms\java``) to ``c:\mxd2map\lib\``

#. Copy the converter.properties.sample file to ``c:\mxd2map\converter.properties`` and edit it
   according to your needs.

Compile the converter-sources
-----------------------------

To compile the sources you need to have a properly configured
ant-environment available. ArcGIS SDK provides an ant-installation which
suffices::

 ant jar

or::

 ant jar-norevision

Setup environment-variables
---------------------------

For running the converter it is necessary to set up some environment
variables and adjust the path accordingly.

Adapt the following example script to set the minimum variables needed::

    @echo off

    rem ###########################EDIT HERE#############################

    rem Set the following Path variables according to your installation:

    set MXD2MAP_PATH=c:\mxd2map
    set MAPSERVER_PATH=c:\ms_6.1-dev
    set ARCGISSDK_PATH=c:\Program Files\ArcGIS\DeveloperKit10.0
    set ARCGISENGINE_PATH=c:\Program Files\ArcGIS\Engine10.0

    rem No editing should be necessary below this line (in an ideal world)
    rem ##################################################################

    if "%1" == "setenv" goto setenv

    %comspec% /k SDKShell.bat setenv %1
    goto exit

    :setenv
    @echo Setting environment for using the GDAL and MapServer tools.

    if "%2"=="hideoci" goto hideoci

    set ocipath=0
    set _path="%PATH:;=" "%"
    for %%p in (%_path%) do if not "%%~p"=="" if exist %%~p\oci.dll set ocipath=1

    if "%ocipath%"=="0" goto hideoci
    @echo WARNING: If you encounter problems with missing oci libraries then type:
    @echo   SDKShell hideoci
    goto setenv2

    :hideoci
    @echo Hiding the OCI plugin library.
    if not exist %GDAL_PATH%\bin\gdal\plugins-optional mkdir %GDAL_PATH%\bin\gdal\plugins-optional
    if exist %GDAL_PATH%\bin\gdal\plugins\ogr_OCI.dll move %GDAL_PATH%\bin\gdal\plugins\ogr_OCI.dll %GDAL_PATH%\bin\gdal\plugins-optional\ogr_OCI.dll
    if exist %GDAL_PATH%\bin\gdal\plugins\gdal_GEOR.dll move %GDAL_PATH%\bin\gdal\plugins\gdal_GEOR.dll %GDAL_PATH%\bin\gdal\plugins-optional\gdal_GEOR.dll

    :setenv2
    SET PATH=%ARCGISSDK_PATH%\java\jre\bin;%ARCGISENGINE_PATH%\bin;%MXD2MAP_PATH%\bin;%MAPSERVER_PATH%\bin\gdal\python\osgeo;%MAPSERVER_PATH%\bin\proj\apps;%MAPSERVER_PATH%\bin\gdal\apps;%MAPSERVER_PATH%\bin\ms\apps;%MAPSERVER_PATH%\bin\gdal\csharp;%MAPSERVER_PATH%\bin\ms\csharp;%MAPSERVER_PATH%\bin\curl;%MAPSERVER_PATH%\bin\ms\java;%PATH%
    SET GDAL_DATA=%MAPSERVER_PATH%\bin\gdal-data
    SET GDAL_DRIVER_PATH=%MAPSERVER_PATH%\bin\gdal\plugins
    SET PYTHONPATH=%MAPSERVER_PATH%\bin\gdal\python\osgeo;%PYTHONPATH%
    SET PROJ_LIB=%MAPSERVER_PATH%\bin\proj\SHARE

    :exit

Save the above script as ``c:\mxd2map\SDKShell.bat`` and execute it before working with MXD2map.

Configure Logging
-----------------

Logging is supported on different levels. MXD2map logs with Log4J. A
sample configuration for Log4J could look like this::

  #### Log just errors and warnings to a file.
  log4j.rootLogger=DEBUG, MXD, Console
  
  log4j.appender.MXD=org.apache.log4j.RollingFileAppender
  log4j.appender.MXD.File=./logs/console-client.log
  log4j.appender.MXD.MaxFileSize=5000KB
  log4j.appender.MXD.MaxBackupIndex=1
  log4j.appender.MXD.layout=org.apache.log4j.PatternLayout
  log4j.appender.MXD.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
  
  #log4j.rootLogger=WARN, Console
  log4j.appender.Console=org.apache.log4j.ConsoleAppender
  log4j.appender.Console.Threshold=INFO
  log4j.appender.Console.layout=org.apache.log4j.PatternLayout
  log4j.appender.Console.layout.ConversionPattern=%d [%t] %-5p %c - %m%n


Apache Webserver and UMN MapServer
..................................

They both support logging. MapServers output ends up in Apaches logfiles
if not configured differently within a  providing template. The loglevel
can be adjusted at template-level. For further information consult the UMN
MapServer manual regarding logging at
http://mapserver.org/optimization/debugging.html#steps-to-enable-mapserver-debugging.