1  
  2                               Windows port
  3                               ============
  4  
  5  This directory contains the files required to build this software on the
  6  native Windows platform. This is not a place to look for help if you are
  7  using a POSIX emulator, such as Cygwin. Check the Unix instructions for 
  8  that.
  9  
 10  
 11  
 12  CONTENTS
 13  ========
 14  
 15  1. General
 16     1.1 Building From the Command-Line
 17     1.2 Configuring The Source
 18     1.3 Compiling
 19     1.4 Installing
 20  
 21  2. Compiler Specifics
 22     2.1 Microsoft Visual C/C++
 23     2.1 GNU C/C++, Mingw Edition
 24     2.2 Borland C++ Builder
 25         2.2.1 Building with iconv support
 26  	   2.2.2 Compatability problems with MSVC (and probably CYGWIN)
 27  	   2.2.3 Other caveats
 28  
 29  
 30  
 31  
 32  1. General
 33  ==========
 34  
 35  
 36  1.1 Building From The Command-Line
 37  ----------------------------------
 38  
 39  This is the easiest, preferred and currently supported method. It can
 40  be that a subdirectory of the directory where this file resides 
 41  contains project files for some IDE. If you want to use that, please
 42  refer to the readme file within that subdirectory.
 43  
 44  In order to build from the command-line you need to make sure that
 45  your compiler works from the command line. This is not always the
 46  case, often the required environment variables are missing. If you are
 47  not sure, test if this works first. If it doesn't, you will first have
 48  to configure your compiler suite to run from the command-line - please
 49  refer to your compiler's documentation regarding that.
 50  
 51  The first thing you want to do is configure the source. You can have
 52  the configuration script do this automatically for you. The
 53  configuration script is written in JScript, a Microsoft's
 54  implementation of the ECMA scripting language. Almost every Windows
 55  machine can execute this through the Windows Scripting Host. If your
 56  system lacks the ability to execute JScript for some reason, you must
 57  perform the configuration manually and you are on your own with that.
 58  
 59  The second step is compiling the source and, optionally, installing it
 60  to the location of your choosing.
 61  
 62  
 63  1.2 Configuring The Source
 64  --------------------------
 65  
 66  The configuration script accepts numerous options. Some of these
 67  affect features which will be available in the compiled software,
 68  others affect the way the software is built and installed. To see a
 69  full list of options supported by the configuration script, run
 70  
 71    cscript configure.js help
 72  
 73  from the win32 subdirectory. The configuration script will present you
 74  the options it accepts and give a biref explanation of these. In every
 75  case you will have two sets of options. The first set is specific to
 76  the software you are building and the second one is specific to the
 77  Windows port.
 78  
 79  Once you have decided which options suit you, run the script with that
 80  options. Here is an example:
 81  
 82    cscript configure.js compiler=msvc prefix=c:\opt 
 83      include=c:\opt\include lib=c:\opt\lib debug=yes
 84  
 85  The previous example will configure the process to use the Microsoft's
 86  compiler, install the library in c:\opt, use c:\opt\include and 
 87  c:\opt\lib as additional search paths for the compiler and the linker 
 88  and build executables with debug symbols.
 89  
 90  Note: Please do not use path names which contain spaces. This will
 91  fail. Allowing this would require me to put almost everything in the
 92  Makefile in quotas and that looks quite ugly with my
 93  syntax-highlighting engine. If you absolutely must use spaces in paths
 94  send me an email and tell me why. If there are enough of you out there
 95  who need this, or if a single one has a very good reason, I will
 96  modify the Makefile to allow spaces in paths.
 97  
 98  
 99  1.3 Compiling
100  -------------
101  
102  After the configuration stage has been completed, you want to build
103  the software. You will have to use the make tool which comes with
104  your compiler. If you, for example, configured the source to build
105  with Microsoft's MSVC compiler, you would use the NMAKE utility. If
106  you configured it to build with GNU C compiler, mingw edition, you
107  would use the GNU make. Assuming you use MSVC, type
108  
109    nmake /f Makefile.msvc
110  
111  and if you use MinGW, you would type
112  
113    make -f Makefile.mingw
114  
115  and if you use Borland's compiler, you would type
116  
117    bmake -f Makefile.bcb
118  
119  in the win32 subdirectory. When the building completes, you will find
120  the executable files in win32\bin.* directory, where * stands for the
121  name of the compiler you have used.
122  
123  
124  1.4 Installing
125  --------------
126  
127  You can install the software into the directory you specified to the
128  configure script during the configure stage by typing (with MSVC in
129  this example)
130  
131    nmake /f Makefile.msvc install
132  
133  That would be it, enjoy.
134  
135  
136  
137  
138  
139  2. Compiler Specifics
140  =====================
141  
142  
143  2.1 Microsoft Visual C/C++
144  --------------------------
145  
146  If you use the compiler which comes with Visual Studio .NET, note that
147  it will link to its own C-runtime named msvcr70.dll or msvcr71.dll. This 
148  file is not available on any machine which doesn't have Visual Studio 
149  .NET installed.
150  
151  
152  2.2 GNU C/C++, Mingw edition
153  ----------------------------
154  
155  When specifying paths to configure.js, please use slashes instead of 
156  backslashes for directory separation. Sometimes Mingw needs this. If
157  this is the case, and you specify backslashes, then the compiler will 
158  complain about not finding necessary header files.
159  
160  
161  2.2 Borland C++ Builder
162  -----------------------
163  
164  To compile libxml2 with the BCB6 compiler and associated tools, just follow
165  the basic instructions found in this file file. Be sure to specify 
166  the "compiler=bcb" option when running the configure script. To compile the
167  library and test programs, just type
168  
169    make -fMakefile.bcb
170  
171  That should be all that's required. But there are a few other things to note:
172  
173  2.2.1 Building with iconv support
174  
175  If you configure libxml2 to include iconv support, you will obviously need to
176  obtain the iconv library and include files. To get them, just follow the links 
177  at http://www.gnu.org/software/libiconv/ - there are pre-compiled Win32 
178  versions available, but note that these where built with MSVC. Hence the 
179  supplied import library is in COFF format rather than OMF format. You can 
180  convert this library by using Borland's COFF2OMF utility, or use IMPLIB to 
181  build a new import library from the DLL. Alternatively, it is possible to
182  obtain the iconv source, and build the DLL using the Borland compiler.
183  
184  There is a minor problem with the header files for iconv - they expect a
185  macro named "EILSEQ" in errno.h, but this is not defined in the Borland
186  headers, and its absence can cause problems. To circumvent this problem, I
187  define EILSEQ=2 in Makefile.bcb. The value "2" is the value for ENOFILE (file
188  not found). This should not have any disastrous side effects beyond possibly
189  displaying a misleading error message in certain situations.
190  
191  2.2.2 Compatability problems with MSVC (and probably CYGWIN)
192  
193  A libxml2 DLL generated by BCB is callable from MSVC programs, but there is a
194  minor problem with the names of the symbols exported from the library. The
195  Borland compiler, by default, prepends an underscore character to global 
196  identifiers (functions and global variables) when generating object files.
197  Hence the function "xmlAddChild" is added to the DLL with the name
198  "_xmlAddChild". The MSVC compiler does not have this behaviour, and looks for
199  the unadorned name. I currently circumvent this problem by writing a .def file
200  which causes BOTH the adorned and unadorned names to be exported from the DLL.
201  This behaviour may not be supported in the future.
202  
203  An even worse problem is that of generating an import library for the DLL. The
204  Borland-generated DLL is in OMF format. MSVC expects libraries in COFF format,
205  but they don't provide a "OMF2COFF" utility, or even the equivalent of
206  Borland's IMPLIB utility. But it is possible to create an import lib from the
207  .def file, using the command:
208    LIB /DEF:libxml2.def
209  
210  If you don't have the .def file, it's possible to create one manually. Use
211  DUMPBIN /EXPORTS /OUT:libxml2.tmp libxml2.dll to get a list of the exported
212  names, and edit this into .def file format.
213  
214  A similar problem is likely with Cygwin.
215  
216  2.2.3 Other caveats
217  
218  We have tested this only with BCB6, Professional Edition, and BCB 5.5 free
219  command-line tools.
220  
221  
222  
223  Authors: Igor Zlatkovic <igor@zlatkovic.com>
224           Eric Zurcher <Eric.Zurcher@csiro.au>
225  
226