README.WIN32
1========================================================================
2(This file has UNIX Linefeeds. Get an editor which can handle them.)
3========================================================================
4This is the README for building libs11n under Microsoft(tm)
5Windows(tm) environments. This is only supported for s11n 1.1.2 and
6higher: there are no plans to port 1.0.x to Win32.
7
8The shipped source files do not provide a 100% standalone build tree,
9but it can be made to build with relatively little effort. Please read
10this whole file before attempting to compile the code under Windows.
11
12This document assumes you are using MS Dev Studio 7.1 (2003) or higher
13or Visual C++ 2005 Express Edition. It is believed that s11n will not
14compile on MS compilers older than 7.1 due to template features which
15aren't supported by the older compilers.
16
17This document does not cover compilation under Cygwin. There is
18currently (June 2005) no Cygwin port of s11n, though it is thought to
19be easily portable to Cygwin if someone will modify the build tree to
20properly build DLLs under Cygwin.
21
22========================================================================
23Feedback:
24
25Please send any and all feedback, patches, etc., to our development
26list:
27 s11n-devel@lists.sourceforge.net
28
29s11n home page:
30
31 http://s11n.net
32
33Disclaimer: s11n's maintainer does not have a copy of Windows and does
34not do the Win32 porting himself, so when sending mails with vague
35error messages from those platforms, he won't be able to help
36much. Windows portability is a high priority, but turnaround time for
37fixes will be longer than for Unix platforms, due to tools
38availability. (As of August 2006 i DO have a Windows machine, so i
39am able to at least partially support Windows ports.)
40
41========================================================================
42License:
43
44All source code distributed with the s11n Win32 source bundle is
45released into the Public Domain.
46
47========================================================================
48Here is the basic approach to getting the code running, at least for
49test purposes:
50
51- Create a project file for a Console Application. See below for
52important notes on specific project settings.
53
54- Add ./src/*.cpp to the project EXCEPT for:
55 - the files plugin.*.cpp. Those are conditionally included by
56 plugin.cpp, and will not build by themselves.
57 - do not add expat*.?pp unless you have libexpat installed and
58 link your project against it.
59
60- Set the build flags mentioned later in this document.
61
62- Build.
63
64- Copy ./src/in.* to the directory your project compiles the
65 executable to. These are only used by the test program, and not
66 necessary for your own applications.
67
68- Run the executable.
69
70If it throws an exception, something didn't work. There are a huge
71number of reasons things can go wrong, but the major ones are listed
72below.
73
74
75========================================================================
76General Build Limitations:
77
78- It cannot currently be built as a DLL because the code does not
79 provide the exports needed to make symbols accessible outside
80 the DLL. (Linux platforms don't require this, so it's never been
81 needed before.)
82
83- Static libs don't yet work for the same reasons as under Unix.
84
85- It must be built as part of your project, or you must at least
86 link in objects from this project into yours. This will be fixed
87 once DLL support is working.
88
89- Support for optional s11n features, namely libexpat and libzfstream,
90 are disabled under Windows. This means that expat_serializer and
91 support for gzip/bzip2 files are disabled. Those parts sit really
92 low on the porting priorities list.
93
94- The code generates lots of warnings under Windows, despite
95 generating none under gcc with -Wall. There's not much i can do
96 about the warnings from the flex-generated code (*.flex.cpp),
97 and the other warnings will be analyzed as time (and access to a
98 Windows box) permits. The warning you'll likely see from all of
99 the flex code is:
100funxml.flex(648) : warning C4244: 'initializing' : conversion from
101'__w64 int' to 'int', possible loss of data
102
103- The s11n code cannot be built as-is from CVS under Windows because
104 several files are generated by the build process and require
105 several Unix-based tools, like flex and perl. The code itself is
106 portable, but the build tree is more complex than Windows IDE tools
107 can comfortably deal with, so the Win32 copy is created by
108 "flattening" the sources into one directory.
109
110- If you are building with Visual C++ Express then you must install the
111 Platform SDK because VC++ Express doesn't come with the <windows.h>
112 header.
113
114
115========================================================================
116Important Project File Settings:
117
118- The macro WIN32 must be defined (the value, if any, is unimportant).
119
120- INCLUDES path must have the 'include' dir shipped with this code.
121 All source files refer their headers using <s11n.net/..../foo.hpp>,
122 not "foo.hpp" You may of course rename 'include' or move its
123 subdirectories into your own project's general include dir.
124
125- The option to "keep unreferenced data" MUST be enabled (found under
126 "Code Generation" preferences), or else factory registrations will
127 not work. The factory layer depends on some "unused objects" who's
128 sole purpose is to be automatically created once during the static
129 initialization phase, and as a side-effect of their creation they
130 trigger other tasks. If unreferenced data is optimized out then
131 these tasks never happen.
132 MS Dev Studio 2003: Project Properties:
133 Linker -> Optimization -> References -> Keep Unreferenced Data (/OPT:NOREF)
134
135- TURN OFF Precompiled Headers!
136
137- If you want to build s11n directly in your own project tree, then
138 remove test.cpp and main.cpp from the project altogether. They are not
139 part of the library.
140
141- Do not turn of C++ Language Extensions because the code in <windows.h>
142 will not compile if you do(!!!). Menu: Configuration Properties -->
143 C/C++ --> Language --> Disable Language Extensions = NO
144
145========================================================================
146Creating a Win32 source tree from a Unix-centric source tree:
147
148If you've got a CVS or source copy of s11n you can create the
149"skeleton" Win32 project tree (no project files, just the sources)
150AFTER you have built the tree once on your platform. Simply go to the
151top source dir and:
152
153 make nobuild
154
155That will create a fresh copy of the sources and headers, structured
156such that they should be easy to introduce into a project file.
157
158
159========================================================================
160Thanks for Reading The Fine Manual. :)
161----- stephan@s11n.net
162========================================================================
163
README.src
1This readme explains the different source distributions of libs11n.
2
3If your source tree has scripts called 'configure' and 'configure.libs11n',
4then you have the "full" build tree. If your distribution has only a couple of
5README files and 'src' and 'include' subdirectories, then you have the
6"generated" build tree.
7
8The full tree is the standard distribution method. It builds on most systems
9hosting GNU versions of common system tools and gcc. It relies on tools like
10flex for generating parts of the source tree, and uses tools like sed and perl
11to filter some files at configure- or build-time.
12
13The generated tree is intended for platforms with simpler build
14needs. It includes pre-generated copies of all generated files, has
15the headers in their proper place, and is otherwise straightforward
16to build. The intention of this distribution is to ease the creation
17of libs11n packages for a wider range of platforms, like Solaris,
18Windows, and BSD.
19
20Some of s11n's features can be enabled or disabled by editing the
21*_config.hpp files. Some of these changes also require changing the
22Makefile (or build process). For example, if
23s11n_config.hpp:s11n_CONFIG_ENABLE_PLUGINS is defined to 0, the files
24defined in src/Makefile:SOURCES_PLUGIN are not needed at all.
25
26
27