Return to Readme.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libxml2 / win32

libxml2

    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: