stephan@229: .. index:: installation, requirements, apache, UMN MapServer, compile,
stephan@229:    jar, logging, ArcSDE
stephan@188: 
stephan@140: ------------
aheinecke@292: Installation from Source
aheinecke@292: ------------
aheinecke@292: This Documentation describes how you can install MXD2Map from source. If you only
aheinecke@292: want to use MXD2Map it is strongly recommended that you use our convenient binary
aheinecke@292: installer.
aheinecke@292: 
stephan@140: Requirements
stephan@140: ------------
stephan@140: 
aheinecke@292: Currently MXD2Map only runs on Windows, because the ArcObjects JDK API does not
aheinecke@292: work properly on GNU/Linux systems. All Free Software components of MXD2Map can
aheinecke@292: run on GNU/Linux as well as on Windows.
stephan@140: 
aheinecke@292: To run the converter you need at least the following components:
stephan@140: 
stephan@140:  * Sun Java6 SDK to build, JRE to run
stephan@140:  * ArcGIS Desktop10.x or ArcEngine10.x with a valid licence enabled
stephan@202:  * UMN MapServer with Java MapScript-bindings (>=6.0.1 or recent development-version)
rrenkert@182: 
aheinecke@292: Additionally the following components are recommended:
stephan@202: 
aheinecke@292:  * Apache2 Webserver for displaying the resulting Mapfiles
aheinecke@292:  * MapServer compiled with ArcSDE-plugin
aheinecke@292:  * GDAL/OGR compiled with ArcSDE-support
aheinecke@292:  * GDAL/OGR compiled with FileGeodatabase-support
aheinecke@292:  * Other GDAL/OGR-related tools
aheinecke@292:  * Sphinx for building the docs
stephan@229: 
stephan@229: Install Apache Webserver
stephan@229: ------------------------
aheinecke@292: To display the resulting mapfiles directly you need to
aheinecke@292: install a webserver like Apache2 and the UMN MapServer.
stephan@229: 
stephan@290: .. important::
aheinecke@292:    If you are  using `MS4W <http://www.maptools.org/ms4w/>`_, the following installation
aheinecke@292:    instruction does apply. , although it can be used to preview the `resulting` mapfiles
aheinecke@292:    MS4W does not provide the needed version to run MXD2map.
stephan@290: 
aheinecke@292: Download Apache from https://httpd.apache.org/download.cgi and install it by
aheinecke@292: executing the .msi-file and following the install-dialogs.
stephan@229: 
aheinecke@292: Make sure that you install apache as a service so it is available
aheinecke@292: directly after system startup.
stephan@229: 
stephan@229: 
stephan@229: Install UMN MapServer
stephan@229: ---------------------
stephan@229: 
aheinecke@292: It is recommended to use the latest binary release version from http://www.gisinternals.com/sdk/
aheinecke@292: as the MapServer for MXD2Map.
stephan@229: 
aheinecke@324: 1. Unzip the MapServer ZIP-file at ``c:\mapserver``
stephan@229: 
aheinecke@292: #. Modify the Apache configuration (e.g. ``c:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf``)
aheinecke@292:    by adding::
stephan@229: 
aheinecke@324:     ScriptAlias /cgi-bin/ "C:/mapserver/bin/"
stephan@229: 
stephan@229:     <Location "/cgi-bin">
stephan@229:         Options None
stephan@229:         Order allow,deny
stephan@229:         Allow from all
stephan@229:     </Location>
stephan@229: 
aheinecke@324:     SetEnv PROJ_LIB "c:/mapserver/bin/proj/SHARE"
aheinecke@324:     SetEnv PATH "c:/mapserver/bin"
aheinecke@324:     SetEnv PATH "c:/mapserver/bin/gdal/python/osgeo"
aheinecke@292: 
stephan@235:     # set GDAL_DATA environment variable to location of supporting gdal files
aheinecke@324:     SetEnv GDAL_DATA "c:/mapserver/bin/gdaldata"
aheinecke@292: 
stephan@235:     # set GDAL_DRIVER_PATH environment variable for gdal plugins
aheinecke@324:     SetEnv GDAL_DRIVER_PATH "c:/mapserver/bin/gdal/plugins"
stephan@235: 
stephan@290: 
aheinecke@324: #. Copy mapserv.exe from ``c:\mapserver\bin\ms\apps`` to ``c:\mapserver\bin\``
aheinecke@292: 
aheinecke@324: #. Optional: Add additional Libraries (DLL's) to ``c:\mapserver\bin`` for Oracle, SDE etc.
aheinecke@292: 
aheinecke@292: Install the Converter
aheinecke@292: ------------
aheinecke@292: The following steps assume the runtime folder to be c:\mxd2map.
aheinecke@292: 
aheinecke@292: 1. Download the Source Package from https://mxd2map.org/download.html
aheinecke@292: 
aheinecke@292: #. Extract the tarball using 7-Zip (http://7-zip.org) or something similar to ``c:\mxd2map\``.
aheinecke@292: 
aheinecke@292: #. Create folder ``c:\mxd2map\lib\``
aheinecke@292: 
aheinecke@292: #. Create folder ``c:\mxd2map\logs\``
aheinecke@292: 
aheinecke@292: #. Get log4j from http://logging.apache.org/log4j/1.2/download.html
aheinecke@292: 
aheinecke@292: #. Get jargs http://jargs.sourceforge.net/ (Version 1.0)
aheinecke@292: 
aheinecke@292: #. Get apache commons codec from https://commons.apache.org/codec/download_codec.cgi
aheinecke@292: 
aheinecke@292: #. Copy the jar-files of log4j, jargs and commons codec to ``c:\mxd2map\lib\``
aheinecke@292: 
aheinecke@292: #. Remove the version numbers of the jar file names in lib, or adopt the build.xml accordingly!
aheinecke@292: 
aheinecke@324: #. Copy mapscript.jar and mapscript.dll from your MapServer Installation (e.g. ``c:\mapserver\bin\ms\java``) to ``c:\mxd2map\lib\``
aheinecke@292: 
aheinecke@292: #. Copy the converter.properties.sample file to ``c:\mxd2map\converter.properties`` and edit it
aheinecke@292:    according to your needs.
aheinecke@292: 
aheinecke@292: Compile the converter-sources
aheinecke@292: -----------------------------
aheinecke@292: 
aheinecke@292: To compile the sources you need to have a properly configured
aheinecke@292: ant-environment available. ArcGIS SDK provides an ant-installation which
aheinecke@292: suffices::
aheinecke@292: 
aheinecke@292:  ant jar
aheinecke@292: 
aheinecke@292: or::
aheinecke@292: 
aheinecke@292:  ant jar-norevision
aheinecke@292: 
aheinecke@292: Setup environment-variables
aheinecke@292: ---------------------------
aheinecke@292: 
aheinecke@292: For running the converter it is necessary to set up some environment
aheinecke@292: variables and adjust the path accordingly.
aheinecke@292: 
aheinecke@292: Adapt the following example script to set the minimum variables needed::
aheinecke@292: 
aheinecke@292:     @echo off
aheinecke@292: 
aheinecke@292:     rem ###########################EDIT HERE#############################
aheinecke@292: 
aheinecke@292:     rem Set the following Path variables according to your installation:
aheinecke@292: 
aheinecke@292:     set MXD2MAP_PATH=c:\mxd2map
aheinecke@324:     set MAPSERVER_PATH=c:\mapserver
aheinecke@292:     set ARCGISSDK_PATH=c:\Program Files\ArcGIS\DeveloperKit10.0
aheinecke@292:     set ARCGISENGINE_PATH=c:\Program Files\ArcGIS\Engine10.0
aheinecke@292: 
aheinecke@292:     rem No editing should be necessary below this line (in an ideal world)
aheinecke@292:     rem ##################################################################
aheinecke@292: 
aheinecke@292:     if "%1" == "setenv" goto setenv
aheinecke@292: 
aheinecke@292:     %comspec% /k SDKShell.bat setenv %1
aheinecke@292:     goto exit
aheinecke@292: 
aheinecke@292:     :setenv
aheinecke@292:     @echo Setting environment for using the GDAL and MapServer tools.
aheinecke@292: 
aheinecke@292:     if "%2"=="hideoci" goto hideoci
aheinecke@292: 
aheinecke@292:     set ocipath=0
aheinecke@292:     set _path="%PATH:;=" "%"
aheinecke@292:     for %%p in (%_path%) do if not "%%~p"=="" if exist %%~p\oci.dll set ocipath=1
aheinecke@292: 
aheinecke@292:     if "%ocipath%"=="0" goto hideoci
aheinecke@292:     @echo WARNING: If you encounter problems with missing oci libraries then type:
aheinecke@292:     @echo   SDKShell hideoci
aheinecke@292:     goto setenv2
aheinecke@292: 
aheinecke@292:     :hideoci
aheinecke@292:     @echo Hiding the OCI plugin library.
aheinecke@347:     if not exist %GDAL_PATH%\bin\gdal\plugins-optional ^
aheinecke@347:         mkdir %GDAL_PATH%\bin\gdal\plugins-optional
aheinecke@347:     if exist %GDAL_PATH%\bin\gdal\plugins\ogr_OCI.dll ^
aheinecke@347:         move %GDAL_PATH%\bin\gdal\plugins\ogr_OCI.dll ^
aheinecke@347:         %GDAL_PATH%\bin\gdal\plugins-optional\ogr_OCI.dll
aheinecke@347:     if exist %GDAL_PATH%\bin\gdal\plugins\gdal_GEOR.dll ^
aheinecke@347:         move %GDAL_PATH%\bin\gdal\plugins\gdal_GEOR.dll ^
aheinecke@347:         %GDAL_PATH%\bin\gdal\plugins-optional\gdal_GEOR.dll
aheinecke@292: 
aheinecke@292:     :setenv2
aheinecke@347:     SET PATH=%ARCGISSDK_PATH%\java\jre\bin;%ARCGISENGINE_PATH%\bin;^
aheinecke@347:     %MXD2MAP_PATH%\bin;%MAPSERVER_PATH%\bin\gdal\python\osgeo;^
aheinecke@347:     %MAPSERVER_PATH%\bin\proj\apps;%MAPSERVER_PATH%\bin\gdal\apps;^
aheinecke@347:     %MAPSERVER_PATH%\bin\ms\apps;%MAPSERVER_PATH%\bin\gdal\csharp;^
aheinecke@347:     %MAPSERVER_PATH%\bin\ms\csharp;%MAPSERVER_PATH%\bin\curl;^
aheinecke@347:     %MAPSERVER_PATH%\bin\ms\java;%PATH%
aheinecke@292:     SET GDAL_DATA=%MAPSERVER_PATH%\bin\gdal-data
aheinecke@292:     SET GDAL_DRIVER_PATH=%MAPSERVER_PATH%\bin\gdal\plugins
aheinecke@292:     SET PYTHONPATH=%MAPSERVER_PATH%\bin\gdal\python\osgeo;%PYTHONPATH%
aheinecke@292:     SET PROJ_LIB=%MAPSERVER_PATH%\bin\proj\SHARE
aheinecke@292: 
aheinecke@292:     :exit
aheinecke@292: 
aheinecke@292: Save the above script as ``c:\mxd2map\SDKShell.bat`` and execute it before working with MXD2map.
stephan@229: 
stephan@229: Configure Logging
stephan@229: -----------------
stephan@229: 
aheinecke@292: Logging is supported on different levels. MXD2map logs with Log4J. A
aheinecke@292: sample configuration for Log4J could look like this::
stephan@229: 
stephan@229:   #### Log just errors and warnings to a file.
stephan@229:   log4j.rootLogger=DEBUG, MXD, Console
stephan@229:   
stephan@229:   log4j.appender.MXD=org.apache.log4j.RollingFileAppender
stephan@229:   log4j.appender.MXD.File=./logs/console-client.log
stephan@229:   log4j.appender.MXD.MaxFileSize=5000KB
stephan@229:   log4j.appender.MXD.MaxBackupIndex=1
stephan@229:   log4j.appender.MXD.layout=org.apache.log4j.PatternLayout
stephan@229:   log4j.appender.MXD.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
stephan@229:   
stephan@229:   #log4j.rootLogger=WARN, Console
stephan@229:   log4j.appender.Console=org.apache.log4j.ConsoleAppender
stephan@229:   log4j.appender.Console.Threshold=INFO
stephan@229:   log4j.appender.Console.layout=org.apache.log4j.PatternLayout
stephan@229:   log4j.appender.Console.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
stephan@229: 
stephan@229: 
stephan@229: Apache Webserver and UMN MapServer
stephan@229: ..................................
stephan@229: 
aheinecke@292: They both support logging. MapServers output ends up in Apaches logfiles
stephan@229: if not configured differently within a  providing template. The loglevel
stephan@229: can be adjusted at template-level. For further information consult the UMN
stephan@229: MapServer manual regarding logging at
stephan@229: http://mapserver.org/optimization/debugging.html#steps-to-enable-mapserver-debugging.