summaryrefslogtreecommitdiffstats
path: root/libxml2/win32/Readme.txt
diff options
context:
space:
mode:
Diffstat (limited to 'libxml2/win32/Readme.txt')
-rw-r--r--libxml2/win32/Readme.txt226
1 files changed, 226 insertions, 0 deletions
diff --git a/libxml2/win32/Readme.txt b/libxml2/win32/Readme.txt
new file mode 100644
index 0000000..6b3eddd
--- /dev/null
+++ b/libxml2/win32/Readme.txt
@@ -0,0 +1,226 @@
+
+ Windows port
+ ============
+
+This directory contains the files required to build this software on the
+native Windows platform. This is not a place to look for help if you are
+using a POSIX emulator, such as Cygwin. Check the Unix instructions for
+that.
+
+
+
+CONTENTS
+========
+
+1. General
+ 1.1 Building From the Command-Line
+ 1.2 Configuring The Source
+ 1.3 Compiling
+ 1.4 Installing
+
+2. Compiler Specifics
+ 2.1 Microsoft Visual C/C++
+ 2.1 GNU C/C++, Mingw Edition
+ 2.2 Borland C++ Builder
+ 2.2.1 Building with iconv support
+ 2.2.2 Compatability problems with MSVC (and probably CYGWIN)
+ 2.2.3 Other caveats
+
+
+
+
+1. General
+==========
+
+
+1.1 Building From The Command-Line
+----------------------------------
+
+This is the easiest, preferred and currently supported method. It can
+be that a subdirectory of the directory where this file resides
+contains project files for some IDE. If you want to use that, please
+refer to the readme file within that subdirectory.
+
+In order to build from the command-line you need to make sure that
+your compiler works from the command line. This is not always the
+case, often the required environment variables are missing. If you are
+not sure, test if this works first. If it doesn't, you will first have
+to configure your compiler suite to run from the command-line - please
+refer to your compiler's documentation regarding that.
+
+The first thing you want to do is configure the source. You can have
+the configuration script do this automatically for you. The
+configuration script is written in JScript, a Microsoft's
+implementation of the ECMA scripting language. Almost every Windows
+machine can execute this through the Windows Scripting Host. If your
+system lacks the ability to execute JScript for some reason, you must
+perform the configuration manually and you are on your own with that.
+
+The second step is compiling the source and, optionally, installing it
+to the location of your choosing.
+
+
+1.2 Configuring The Source
+--------------------------
+
+The configuration script accepts numerous options. Some of these
+affect features which will be available in the compiled software,
+others affect the way the software is built and installed. To see a
+full list of options supported by the configuration script, run
+
+ cscript configure.js help
+
+from the win32 subdirectory. The configuration script will present you
+the options it accepts and give a biref explanation of these. In every
+case you will have two sets of options. The first set is specific to
+the software you are building and the second one is specific to the
+Windows port.
+
+Once you have decided which options suit you, run the script with that
+options. Here is an example:
+
+ cscript configure.js compiler=msvc prefix=c:\opt
+ include=c:\opt\include lib=c:\opt\lib debug=yes
+
+The previous example will configure the process to use the Microsoft's
+compiler, install the library in c:\opt, use c:\opt\include and
+c:\opt\lib as additional search paths for the compiler and the linker
+and build executables with debug symbols.
+
+Note: Please do not use path names which contain spaces. This will
+fail. Allowing this would require me to put almost everything in the
+Makefile in quotas and that looks quite ugly with my
+syntax-highlighting engine. If you absolutely must use spaces in paths
+send me an email and tell me why. If there are enough of you out there
+who need this, or if a single one has a very good reason, I will
+modify the Makefile to allow spaces in paths.
+
+
+1.3 Compiling
+-------------
+
+After the configuration stage has been completed, you want to build
+the software. You will have to use the make tool which comes with
+your compiler. If you, for example, configured the source to build
+with Microsoft's MSVC compiler, you would use the NMAKE utility. If
+you configured it to build with GNU C compiler, mingw edition, you
+would use the GNU make. Assuming you use MSVC, type
+
+ nmake /f Makefile.msvc
+
+and if you use MinGW, you would type
+
+ make -f Makefile.mingw
+
+and if you use Borland's compiler, you would type
+
+ bmake -f Makefile.bcb
+
+in the win32 subdirectory. When the building completes, you will find
+the executable files in win32\bin.* directory, where * stands for the
+name of the compiler you have used.
+
+
+1.4 Installing
+--------------
+
+You can install the software into the directory you specified to the
+configure script during the configure stage by typing (with MSVC in
+this example)
+
+ nmake /f Makefile.msvc install
+
+That would be it, enjoy.
+
+
+
+
+
+2. Compiler Specifics
+=====================
+
+
+2.1 Microsoft Visual C/C++
+--------------------------
+
+If you use the compiler which comes with Visual Studio .NET, note that
+it will link to its own C-runtime named msvcr70.dll or msvcr71.dll. This
+file is not available on any machine which doesn't have Visual Studio
+.NET installed.
+
+
+2.2 GNU C/C++, Mingw edition
+----------------------------
+
+When specifying paths to configure.js, please use slashes instead of
+backslashes for directory separation. Sometimes Mingw needs this. If
+this is the case, and you specify backslashes, then the compiler will
+complain about not finding necessary header files.
+
+
+2.2 Borland C++ Builder
+-----------------------
+
+To compile libxml2 with the BCB6 compiler and associated tools, just follow
+the basic instructions found in this file file. Be sure to specify
+the "compiler=bcb" option when running the configure script. To compile the
+library and test programs, just type
+
+ make -fMakefile.bcb
+
+That should be all that's required. But there are a few other things to note:
+
+2.2.1 Building with iconv support
+
+If you configure libxml2 to include iconv support, you will obviously need to
+obtain the iconv library and include files. To get them, just follow the links
+at http://www.gnu.org/software/libiconv/ - there are pre-compiled Win32
+versions available, but note that these where built with MSVC. Hence the
+supplied import library is in COFF format rather than OMF format. You can
+convert this library by using Borland's COFF2OMF utility, or use IMPLIB to
+build a new import library from the DLL. Alternatively, it is possible to
+obtain the iconv source, and build the DLL using the Borland compiler.
+
+There is a minor problem with the header files for iconv - they expect a
+macro named "EILSEQ" in errno.h, but this is not defined in the Borland
+headers, and its absence can cause problems. To circumvent this problem, I
+define EILSEQ=2 in Makefile.bcb. The value "2" is the value for ENOFILE (file
+not found). This should not have any disastrous side effects beyond possibly
+displaying a misleading error message in certain situations.
+
+2.2.2 Compatability problems with MSVC (and probably CYGWIN)
+
+A libxml2 DLL generated by BCB is callable from MSVC programs, but there is a
+minor problem with the names of the symbols exported from the library. The
+Borland compiler, by default, prepends an underscore character to global
+identifiers (functions and global variables) when generating object files.
+Hence the function "xmlAddChild" is added to the DLL with the name
+"_xmlAddChild". The MSVC compiler does not have this behaviour, and looks for
+the unadorned name. I currently circumvent this problem by writing a .def file
+which causes BOTH the adorned and unadorned names to be exported from the DLL.
+This behaviour may not be supported in the future.
+
+An even worse problem is that of generating an import library for the DLL. The
+Borland-generated DLL is in OMF format. MSVC expects libraries in COFF format,
+but they don't provide a "OMF2COFF" utility, or even the equivalent of
+Borland's IMPLIB utility. But it is possible to create an import lib from the
+.def file, using the command:
+ LIB /DEF:libxml2.def
+
+If you don't have the .def file, it's possible to create one manually. Use
+DUMPBIN /EXPORTS /OUT:libxml2.tmp libxml2.dll to get a list of the exported
+names, and edit this into .def file format.
+
+A similar problem is likely with Cygwin.
+
+2.2.3 Other caveats
+
+We have tested this only with BCB6, Professional Edition, and BCB 5.5 free
+command-line tools.
+
+
+
+Authors: Igor Zlatkovic <igor@zlatkovic.com>
+ Eric Zurcher <Eric.Zurcher@csiro.au>
+
+