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

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

The current version of the converter only runs on Windows. This is because
the ArcObjects JDK API is not running properly on Linux though. In theory
it should also run on Linux.

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

 * 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)
 * Optinal: Apache2 Webserver for displaying the resulting Mapfiles
 * Optional: MapServer compiled with ArcSDE-plugin
 * Optional: GDAL/OGR compiled with ArcSDE-support
 * Optional: GDAL/OGR compiled with FileGeodatabase-support
 * Optional: Other GDAL/OGR-related tools
 * Optional: Sphinx for building the docs


------------
Installation
------------

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

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

 ant jar

or::

 ant jar-norevision

Create run-environment
----------------------

The current version of MXD2map needs a few steps to run properly.
The following steps assume the runtime folder to be c:/mxd2map/. This path can
be changed.

1. Copy ``mxd2map.jar`` to ``c:/mxd2map/``.

#. Copy folder "conf" from repository to ``c:/mxd2map/``

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

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

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

#. Build the libraries and copy the resulting jar-files to ``c:/mxd2map/lib/``

#. Copy mapscript.jar and mapscript.dll to ``c:/mxd2map/lib/``

#. Create a folder ``c:/mxd2map/logs/``

#. Create or copy a converter.properties file to ``c:/mxd2map/``

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

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

The following example shows the minimum env-vars needed::

    @echo off
    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 %CD%\bin\gdal\plugins-optional mkdir %CD%\bin\gdal\plugins-optional
    if exist %CD%\bin\gdal\plugins\ogr_OCI.dll move %CD%\bin\gdal\plugins\ogr_OCI.dll %CD%\bin\gdal\plugins-optional\ogr_OCI.dll
    if exist %CD%\bin\gdal\plugins\gdal_GEOR.dll move %CD%\bin\gdal\plugins\gdal_GEOR.dll %CD%\bin\gdal\plugins-optional\gdal_GEOR.dll
    
    :setenv2
    SET PATH=C:\Program Files\ArcGIS\DeveloperKit10.0\java\jre\bin;C:\Program Files\ArcGIS\Engine10.0\bin;%CD%\bin;%CD%\bin;%CD%\bin\gdal\python\osgeo;%CD%\bin\proj\apps;%CD%\bin\gdal\apps;%CD%\bin\ms\apps;%CD%\bin\gdal\csharp;%CD%\bin\ms\csharp;%CD%\bin\curl;%CD%\bin\ms\java;C:\Program Files\Vim\vim71;C:\Program Files\TortoiseHg;%PATH%
    SET GDAL_DATA=%CD%\bin\gdal-data
    SET GDAL_DRIVER_PATH=%CD%\bin\gdal\plugins
    SET PYTHONPATH=%CD%\bin\gdal\python\osgeo
    SET PROJ_LIB=%CD%\bin\proj\SHARE
    SET CURL_CA_BUNDLE=C:\ms4w\Apache\conf\ca-bundle\cacert.pem

    :exit

The above batch-script ``SDKShell.bat`` needs to be sources before working
with MXD2map.


Install Apache Webserver
------------------------

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

If you will be able to display the resulting mapfiles directly you need to
install a webserver like Apache2 and the UMN MapServer CGI-file
``mapserv.exe``.

Install Apache webserver by exedcuting the .msi-file and follow the
install-dialogs::

 httpd-2.2.19-win32-x86-openssl-0.9.8r.msi

Make sure that you install apache as a service so it will be available
directly after system bootup.


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

The current documentation uses the Windows binary-builds from http://www.gisinternals.com/sdk/

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

#. Configure Apache Webserver to find the cgi-bin-folder::

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

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

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

#. Add environment-variables to apache in order to have WMS-server available::

    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"

#. Optional: Add your proprietary DLLs to ``c:/ms_6.1-dev/bin`` for Oracle, SDE etc.


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

Logging is supported on different levels. MXD2map logs with Javas Log4J. A
sample configuration 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 outout 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.