-- $Id$

C# mapscript
==============

1. Compilation
-------------
Before compiling C# mapscript you should compile mapserver with the options for your requirements.
For more information about the compilation of mapserver please visit
http://mapserver.gis.umn.edu/docs
It is highly recommended to minimize the library dependency of your application, so
when compiling mapserver enable only the features really needed.
To compile the C# binding SWIG 1.3.27 or later is required.


1.1 Win32 compilation targeting the MS.NET framework 1.1
------------
You should compile mapserver, mapscript and all of the subsequent libraries using Visual Studio 2003.
Download and uncompress the latest SWIGWIN package that contains the precompiled swig.exe
Open the Visual Studio .NET 2003 Command Prompt and step into the /mapscript/csharp directory
Edit makefile.vc and set the SWIG variable to the location of your swig.exe
Use 
       nmake -f makefile.vc 

to compile mapscript.dll and mapscript_csharp.dll.


1.2 Win32 compilation targeting the MS.NET framework 2.0
------------
You should compile mapserver, mapscript and all of the subsequent libraries using Visual Studio 2005.
Download and uncompress the latest SWIGWIN package that contains the precompiled swig.exe
Open the Visual Studio 2005 Command Prompt and step into the /mapscript/csharp directory
Edit makefile.vc and set the SWIG variable to the location of your swig.exe
Use 
       nmake -f makefile.vc 

to compile mapscript.dll and mapscript_csharp.dll.

1.3 Win32 compilation targeting the MONO framework
------------
Before the compilation you should download and install the recent mono Win32 setup package
(mono-1.1.13.2-gtksharp-2.8.1-win32-1.exe)
Edit makefile.vc and set the CSC variable to the location of your mcs.exe
You should use the same compiler for compiling mapscript as the compiler has been used for
the mapserver compilation. To compile mapscript open the Command Prompt supplied with your compiler
and use
        nmake -f makefile.vc 

to compile mapscript.dll and mapscript_csharp.dll.

1.4 Alternative compilation methods on Windows
------------
Beginning from mapserver 4.8.3 you can invoke the C# compilation from the mapserver directory by uncommenting DOT_NET in nmake.opt

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# .NET/C# MapScript
# ----------------------------------------------------------------------
# .NET will of course only work with MSVC 7.0 and 7.1.  Also note that
# you will definitely want USE_THREAD defined.
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#DOT_NET = YES

and invoking the compilation by

nmake -f makefile.vc csharp

You can also use

nmake -f makefile.vc install

for making the compilation an copying the targets into a common output directory.

1.5 Linux compilation targeting the MONO framework
------------
Before the compilation you should download and install the recent mono Linux package.
Some distributions have precompiled binaries to install, but for using the latest
version you might want to compile and install it from the source.
Download and uncompress the latest SWIG release. You should probably compile it
from the source if precompiled binaries are not available for your platform.

Before compiling mapscript mapserver sould be configured and compiled. During
configuration the mapscript/csharp/Makefile will be created according to the configuration
options. Edit this file and set the SWIG and CSC for the corresponding executable pathes if
the files could not be accessed by default.
To compile at a console step into the /mapscript/csharp directory
Use
      make
      
to compile libmapscript.so and mapscript_csharp.dll.


2. Installation
-------------
The files required for your application should be manually installed. It is highly recommended
to copy the files into the same folder as the executable resides.

3. Known issues
-------------
3.1 If you have compiled mapserver for using the CRT libraries and you are using the MS.NET 
framework 2.0 as the execution runtime you should supply a proper manifest file along with
your executable, like:

<?xml version="1.0" encoding="utf-8"?>
<assembly xsi:schemaLocation="urn:schemas-microsoft-com:asm.v1 assembly.adaptive.xsd" manifestVersion="1.0" xmlns:asmv1="urn:schemas-microsoft-com:asm.v1" xmlns:asmv2="urn:schemas-microsoft-com:asm.v2" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <assemblyIdentity name="drawmap.exe" version="1.0.0.0" type="win32" />
  <dependency>
    <dependentAssembly asmv2:dependencyType="install" asmv2:codebase="Microsoft.VC80.CRT.manifest" asmv2:size="522">
      <assemblyIdentity name="Microsoft.VC80.CRT" version="8.0.50608.0" publicKeyToken="1fc8b3b9a1e18e3b" processorArchitecture="x86" type="win32" />
      <hash xmlns="urn:schemas-microsoft-com:asm.v2">
        <dsig:Transforms>
          <dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>UMOlhUBGeKRrrg9DaaPNgyhRjyM=</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
</assembly>

This will inform the CLR that your exe depends on the CRT and the proper assembly wrapper is to be used.
If you are using the IDE the manifest file could be pregenerated by adding a reference to
Microsoft.VC80.CRT.manifest within the \Microsoft Visual Studio 8\VC\redist\x86\Microsoft.VC80.CRT
directory.

3.2 When compiling with Microsoft Visual Studio 2005 variable name collision may occur between regex.c
and crtdefs.h. For more details see:
    http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1651

3.3 To run the C# module on Mono/Linux, a dll.config file is needed.  This simply
maps the library file the DllImport is looking for to its unix equivalent. The file
normally contains the following information (mapscript_csharp.dll.config):

<configuration>
    <dllmap dll="mapscript" target="libmapscript.so" />
 </configuration>
 
The file should be placed along with the corresponding mapscript_csharp.dll file.
For more information see:
	http://mapserver.gis.umn.edu/bugs/show_bug.cgi?id=1596
    http://www.mono-project.com/Interop_with_Native_Libraries
  
4. Bug reports
-------------
If you find a problem dedicated to the mapscript C# interface feel free to file a bug report to BugZilla.