third_party/libxml/src/win32/Readme.txt

   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