# HG changeset patch # User Andre Heinecke # Date 1346422399 -7200 # Node ID 6e5fce16b495a434b4f32e389d059dfb517d73d5 # Parent d35744fcfc8ed8d923bfdde9e8eb0ba6d8d60bb3 Update/Rework installation dokumentation diff -r d35744fcfc8e -r 6e5fce16b495 INSTALL.txt --- a/INSTALL.txt Tue Jul 10 13:25:16 2012 +0200 +++ b/INSTALL.txt Fri Aug 31 16:13:19 2012 +0200 @@ -2,145 +2,61 @@ 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 ------------ -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. +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 componentes: +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) - * 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:: +Additionally the following components are recommended: - @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. - + * 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 `_, 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 are using `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. -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``. +Download Apache from https://httpd.apache.org/download.cgi and install it by +executing the .msi-file and following the install-dialogs. -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. +Make sure that you install apache as a service so it is available +directly after system startup. Install UMN MapServer --------------------- -The current documentation uses the Windows binary-builds from http://www.gisinternals.com/sdk/ +It is recommended to use the latest binary release version from http://www.gisinternals.com/sdk/ +as the MapServer for MXD2Map. -1. Unzip the ZIP-file at ``c:/ms_6.1-dev`` +1. Unzip the MapServer ZIP-file at ``c:\ms_6.1-dev`` -#. Configure Apache Webserver to find the cgi-bin-folder:: +#. 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/" @@ -150,28 +66,124 @@ Allow from all -#. 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. +#. 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 Javas Log4J. A -sample configuration could look like this:: +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 @@ -193,7 +205,7 @@ Apache Webserver and UMN MapServer .................................. -They both support logging. MapServers outout ends up in Apaches logfiles +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