======================================================================== (This file has UNIX Linefeeds. Get an editor which can handle them.) ======================================================================== This is the README for building libs11n under Microsoft(tm) Windows(tm) environments. This is only supported for s11n 1.1.2 and higher: there are no plans to port 1.0.x to Win32. The shipped source files do not provide a 100% standalone build tree, but it can be made to build with relatively little effort. Please read this whole file before attempting to compile the code under Windows. This document assumes you are using MS Dev Studio 7.1 (2003) or higher. It is believed that s11n will not compile on MS compilers older than 7.1, due to template features which aren't supported by the older compilers. This document does not cover compilation under Cygwin. There is currently (June 2005) no Cygwin port of s11n, though it is though to be easily portable to Cygwin if someone will modify the build tree to properly build DLLs under Cygwin. ======================================================================== Feedback: Please send any and all feedback, patches, etc., to our development list: s11n-devel@lists.sourceforge.net s11n home page: http://s11n.net Disclaimer: s11n's maintainer does not have a copy of Windows and does not do the Win32 porting himself, so when sending mails with vague error messages from those platforms, he won't be able to help much. Windows portability is a high priority, but turnaround time for fixes will be longer than for Unix platforms, due to tools availability. ======================================================================== License: All source code distributed with the s11n Win32 source bundle is released into the Public Domain. ======================================================================== Here is the basic approach to getting the code running, at least for test purposes: - Create a project file for a Console Application. See below for important notes on specific project settings. - Add ./src/*.cpp to the project EXCEPT for: - the files plugin.*.cpp. Those are conditionally included by plugin.cpp, and will not build by themselves. - do not add expat*.?pp unless you have libexpat installed and link your project against it. - Set the build flags mentioned later in this document. - Build. - Copy ./src/in.* to the directory your project compiles the executable to. These are only used by the test program, and not necessary for your own applications. - Run the executable. If it throws an exception, something didn't work. There are a huge number of reasons things can go wrong, but the major ones are listed below. ======================================================================== General Build Limitations: - It cannot currently be built as a DLL because the code does not provide the exports needed to make symbols accessible outside the DLL. (Linux platforms don't require this, so it's never been needed before.) - Static libs don't yet work for the same reasons as under Unix. - It must be built as part of your project, or you must at least link in objects from this project into yours. This will be fixed once DLL support is working. - Support for optional s11n features, namely libexpat and libzfstream, are disabled under Windows. This means that expat_serializer and support for gzip/bzip2 files are disabled. Those parts sit really low on the porting priorities list. - The code generates lots of warnings under Windows, despite generating none under gcc with -Wall. There's not much i can do about the warnings from the flex-generated code (*.flex.cpp), and the other warnings will be analyzed as time (and access to a Windows box) permits. The warning you'll likely see from all of the flex code is: funxml.flex(648) : warning C4244: 'initializing' : conversion from '__w64 int' to 'int', possible loss of data - The s11n code cannot be built as-is from CVS under Windows because several files are generated by the build process and require several Unix-based tools, like flex and perl. The code itself is portable, but the build tree is more complex than Windows IDE tools can comfortably deal with, so the Win32 copy is created by "flattening" the sources into one directory. ======================================================================== Important Project File Settings: - The macro WIN32 must be defined (the value, if any, is unimportant). - INCLUDES path must have the 'include' dir shipped with this code. All source files refer their headers using , not "foo.hpp" You may of course rename 'include' or move its subdirectories into your own project's general include dir. - The option to "keep unreferenced data" MUST be enabled (found under "Code Generation" preferences), or else factory registrations will not work. The factory layer depends on some "unused objects" who's sole purpose is to be automatically created once during the static initialization phase, and as a side-effect of their creation they trigger other tasks. If unreferenced data is optimized out then these tasks never happen. MS Dev Studio 2003: Project Properties: Linker -> Optimization -> References -> Keep Unreferenced Data (/OPT:NOREF) - TURN OFF Precompiled Headers! - If you want to build s11n directly in your own project tree, then remove test.cpp and main.cpp from the project altogether. They are not part of the library. ======================================================================== Creating a Win32 source tree from a Unix-centric source tree: If you've got a CVS or source copy of s11n you can create the "skeleton" Win32 project tree (no project files, just the sources) AFTER you have built the tree once on your platform. Simply go to the top source dir and: make nobuild That will create a fresh copy of the sources and headers, structured such that they should be easy to introduce into a project file. ======================================================================== Thanks for Reading The Fine Manual. :) ----- stephan@s11n.net ========================================================================