| | 270 | === Language Binding Generation === |
| | 271 | |
| | 272 | MapGuide's core and API is all C++. To make the MapGuide API available to higher level languages, the following set of tools are used to generate the necessary bindings in .net/Java/PHP: |
| | 273 | |
| | 274 | * A modified version of [http://www.swig.org SWIG] |
| | 275 | * [http://trac.osgeo.org/mapguide/browser/trunk/MgDev/BuildTools/WebTools/IMake IMake.exe] |
| | 276 | |
| | 277 | You can see the design of the C++ classes in the MapGuide API mostly being a convention-based lowest common denominator approach to facilitate the ease of language binding generation to the 3 platforms. The C++ classes in the MapGuide API do not use C++ features that may not be expressible or convertible to the target language. Some examples include: |
| | 278 | |
| | 279 | * enums (not supported by PHP) |
| | 280 | * const correctness (not supported and/or expressible in .net/Java/PHP) |
| | 281 | * Pass-by-reference (not supported and/or expressible in PHP/Java). Where possible, C++ classes employ "boxing" to work around this (see [wiki:MapGuideRfc44] for an example |
| | 282 | |
| | 283 | ==== Build process ==== |
| | 284 | ||[[Image(SWIG build process.png)]]|| |
| | 285 | ||Figure ? - SWIG build process for generating PHP/Java/.net wrappers for the MapGuide API|| |
| | 286 | |
| | 287 | IMake.exe reads from 2 XML files: |
| | 288 | |
| | 289 | * Constants.xml (for .net this is split into 5 different files due to [wiki:MapGuideRfc68], but the same principle applies) |
| | 290 | * MapGuideApiGen.xml (for .net this is split into 5 different files due to [wiki:MapGuideRfc68], but the same principle applies) |
| | 291 | |
| | 292 | These two files mainly define: |
| | 293 | |
| | 294 | * The paths of the header files of the MapGuide public API |
| | 295 | * SWIG input file generation options |
| | 296 | |
| | 297 | IMake.exe takes these 2 files and produces the following: |
| | 298 | |
| | 299 | * A set of source files in the target language, defining the various constants in the MapGuide API |
| | 300 | * A SWIG input file containing a "sanitized" class definition from each header file |
| | 301 | |
| | 302 | IMake.exe looks for special #define'd markers in the header files: |
| | 303 | |
| | 304 | * `PUBLISHED_API`: Members under here are included in the sanitized class definition and represent the public API |
| | 305 | * `INTERNAL_API`: Members under here are excluded from the sanitized class definition |
| | 306 | * `EXTERNAL_API`: Members under here are included in the sanitized class definition and represent undocumented public APIs that are not for general use (but nothing stops a MapGuide application developer from using them) |
| | 307 | |
| | 308 | Because C++ does not expose the concept of internal visibility, this IMake build system in conjunction with the above markers approximates this type of desired encapsulation. |
| | 309 | |
| | 310 | Once the SWIG input file is generated, it is then fed to SWIG which will do the following: |
| | 311 | |
| | 312 | * Generate the source code for the managed-native interop glue library |
| | 313 | * Generate the MapGuide API proxy classes that call into this managed-native interop glue library |
| | 314 | |
| | 315 | SWIG will use whatever supported native interop mechanism that is provided by the target language: |
| | 316 | |
| | 317 | * For Java, this is [http://en.wikipedia.org/wiki/Java_Native_Interface JNI] |
| | 318 | * For .net, this is [http://en.wikipedia.org/wiki/Platform_Invocation_Services P/Invoke] |
| | 319 | |
| | 320 | Once SWIG has generated the files, MSVC/gcc is used to compile the glue library while csc/javac is used to compile the proxy classes into a matching assemblies/jar file. These two binary outputs, combined with the [http://trac.osgeo.org/mapguide/wiki/MapGuideArchitecture#SharedComponentOverview shared component binaries and its dependencies] comprises the final set of binaries needed to build a MapGuide application |
| | 321 | |
| | 322 | ==== .net binding specifics ==== |
| | 323 | |
| | 324 | IMake.exe has special behavior for .net. You may see markers like these throughout the MapGuide headers: |
| | 325 | |
| | 326 | * `__get` |
| | 327 | * `__set` |
| | 328 | |
| | 329 | In addition, you may see files [http://trac.osgeo.org/mapguide/browser/trunk/MgDev/Web/src/DotNetUnmanagedApi/Foundation/FoundationCustom liek this] |
| | 330 | |
| | 331 | These files and markers serve as hints to IMake to do the following: |
| | 332 | |
| | 333 | * Generate a read-only property for any method with a `__get` marker. Generate a regular property for a method if a `__get` and `__set` marker. Such methods follow a convention of being applied to any method of the form Get<Name>. So IMake will generate an equivalent property named <Name> |
| | 334 | * Apply .net exception serialization info for each file |
| | 335 | |
| | 336 | === mapagent === |
| | 337 | |
| | 338 | TBD |
| | 339 | |
| | 340 | === AJAX Viewer === |
| | 341 | |
| | 342 | TBD |
| | 343 | |
