xmlada/README

XML/Ada: A XML parser for Ada95

I   - INSTALLING THIS LIBRARY ON UNIX
II  - INSTALLING THIS LIBRARY ON VMS
III - INSTALLING THIS LIBRARY ON WINDOWS
IV  - TESTING THE LIBRARY
V   - CONTENTS OF THE LIBRARY
VI  - LICENSING
VII - BUG REPORTS


I - INSTALLING THIS LIBRARY ON UNIX
===================================

Make sure that you do not have a previous installation of XML/Ada in one
of the directories given in ADA_OBJECTS_PATH, or some files will not be
properly recompiled.

Compiling with GNAT 3.14p and GNAT 3.15p
----------------------------------------

Compilation with these older versions of GNAT is done differently than
with more versions, since the GNAT project files were lacking some important
features at that point.

To compile with such versions, do the following:
  >  ./configure --prefix=<PREFIX>
  > <possible Makefile.module.314 modification, as documented below>
  >  make -f Makefile.314 install

This will compile and install XML/Ada in the <PREFIX> directory. The resulting
installation can only be used through xmlada-config, as documented below,
and not with project files.

If your system requires -fPIC when compiling source files for shared
libraries, modify the Makefile.module.314 file to change
   FPIC=
to
   FPIC=-fPIC

Compiling with GNAT 3.16a or newer versions of GNAT
---------------------------------------------------

You might need to modify the following lines in the Makefile.in:
    GNATMAKE= gnatmake
    CC= gcc
if you are using a compiler other than native GNAT. For instance, if 
you are using a cross-compiler for powerpc/vxworks, you would set them
to
    GNATMAKE= powerpc-wrs-vxworks-gnatmake
    CC= powerpc-wrs-vxworks-gcc

You can also chose the type of library you want to build. The default is
to build relocatable libraries, although you can chose to build static
libraries as well. This is done by changing the value of
   LIBRARY_TYPE=relocatable
in the Makefile.in.

Note that if you wish to build both types of libraries, you should first build
and install the static libraries, then clean the build directory with
"make clean", and then build and install the shared libraries. The installation
directories should be different, since the generated code might not be the
same in both cases, and the second set of project files (see below) would
overwrite the ones previously installed.

Configure and compile with the following commands:
   >  ./configure --prefix=<PREFIX>
   >  make install
to build and install the library.

Compiling with other Ada compilers
----------------------------------

This library has been reported as being compilable with other compilers than
GNAT. No build script is provided however, but take a look at
Makefile.314 and Makefile.module.314 to get ideas on how this could be done.

II - INSTALLING THIS LIBRARY ON VMS
===================================

On VMS, you should have a recent version of GNAT (3.15 or more recent), since
the makefile is set up to use the GNAT project files that are now available.

Do the following, from the root directory of XML/Ada:

   - Edit makefile.vms, and change the PREFIX variable to reflect the directory
     where you want to install XML/Ada
   - make -f makefile.vms
   - make -f makefile.vms install
     If you do not have MKDIR.EXE and other unix-like tools, this command
     will fail.
     You can replace it with some manual steps:
       * Create the installation directory
       * copy the files 
           unicode/obj/*
           unicode/*.adb unicode/*.ads
           input_sources/obj/*
           input_sources/*.ads input_sources/*.adb
           sax/obj/*
           sax/*.adb sax/*.ads
           dom/obj/*
           dom/*.adb dom/*.ads
         into this directory

      To use XML/Ada in your own applications, you need to add the installation
      directory on the gnatmake command line with a -I switch

   - (optional) make -f makefile.vms test
     This last step is only required if you want to build the test executables
     testsax and testdom which can be used to test the library on any XML file.


III - INSTALLING THIS LIBRARY ON WINDOWS
========================================

1. Due to the nature of GNU Make you need to have a UNIX-type shell and
   utilities installed to build this library. If you do not have this,
   you can download a set at:

      http://www.weihenstephan.de/~syring/win32/UnxUtils.html

2. Run 'configure' to generate the makefile.

3. Before building make sure to set the following values in 'Makefile':

      PREFIX=C:/GNAT/XMLada

   the makefile where to install the library. Note the slashes in the path!

4. The best way to proceed is to do a 'make install'.

5. If you have GNAT 3.14 or later, you can register the library as a
   standard library using the 'gnatreg' command.

IV - USING THE LIBRARY
======================

There are two ways to use this library. One solution is to use Makefiles to
build your application, specifying all search patchs and libraries directly
on the command line of the compiler.
The other solution is to use the project files provided by GNAT. These have
evolved a lot in recent versions of GNAT, and the provided project files
might not work correctly with older versions of GNAT.

One you have managed to build your application, you might need to edit the
LD_LIBRARY_PATH environment variable on Unix systems, or the PATH variable
on Windows systems to make the library visible to the dynamic linker. The
directory ${PREFIX}/lib should be added to this path.

Using the library through project files
---------------------------------------

If you are building your application with the help of GNAT project files (see
the GNAT documentation for more information on these), you just have to add
the following statement at the beginning of your project file:

   with "xmlada";

This assumes that the xmlada.gpr project file is visible through the
environment variable ADA_PROJECT_PATH. You should add the directory ${PREFIX}
to that path to be able to build your application.

The statement above with automatically set the appropriate search paths for
the compiler, as well as the proper linker arguments.

An example of such a project file is provided as the dom/test/default.gpr.
To use this example project, change to that dom/test directory, and run
    gnatmake -Pdefault
This automatically creates an executable using dynamic libraries


Using the library through Makefiles
-----------------------------------

Files will be copied into ${PREFIX}/lib and ${PREFIX}/include/xmlada.

To use this library, add the following arguments to the gnatmake
command line:
   -aI${PREFIX}/include/xmlada -largs -L${PREFIX}/lib -lxmlada_input_sources \
   -lxmlada_unicode -lxmlada_dom -lxmlada_sax

Alternatively, a script is provided in ${PREFIX}/bin, that outputs all
the command line arguments. You should compile with:
   gnatmake test.adb `xmlada-config`

You can also build a static version of your program by using:
   gnatmake test.adb `xmlada-config --static`


V - TESTING THE LIBRARY
=======================

Several test programs are provided in the XML/Ada source package. These
are found in the dom/test and sax/test subdirectories. These are very simple
examples on how to use the DOM and SAX API.

The w3c organization has constructed an official testsuite that can be used to
check XML/Ada. Most likely, this is only useful to you if you are modifying
XML/Ada itself. Here is how you can run this testsuite:
   You need to download the official OASIS test suite for XML,
   from www.xml.org. The name of the current archive is
     xmlconf-19990712.tar.Z.

   Uncompress it somewhere on your disk, then edit the file dom/test/testsuite to
   reflect the location of that testsuite (BASE should point to the directory
   containing these official tests)

   Execute the file
     make test
     cd dom/test
     ./testsuite

   This will report the number of errors found.


VI - CONTENTS OF THE LIBRARY
============================

The sources in this library are split into several subdirectories, each
with its own README, sources, documentation and unit tests.

The list of subdirectories (aka modules) is:

- unicode:
  provides a full support for Unicode and Utf8/Utf16/Utf32 encodings. It also
  support other encodings like Latin1, Latin2, ...

- input_sources
  provides types to read characters from several types of media.

- sax
  Provides a common, standard interface for any XML parser, through
  callback subprograms. You can extend any of the tagged types defined in these
  package and thus parse XML files without having to store a XML tree in
  memory.
  This package is compatible with SAX 2.0, but doesn't implement the functions
  specific to SAX 1.0

- dom
  The Document Object Model is a set of standard subprograms to manipulate
  XML tree in memory.
  Only the Core module is currently implemented.

- docs
  This contains the full documentation for this XML library


VII - LICENSING
===============

This library is distributed under the GNAT-Modified GNU Public License.
It has the following addition to the GPL:

"As a special exception, if other files instantiate generics from
 this unit, or you link this unit with other files to produce an
 executable, this  unit  does not  by itself cause  the resulting
 executable to be covered by the GNU General Public License. This
 exception does not however invalidate any other reasons why the
 executable file  might be covered by the  GNU Public License."

VIII - BUG REPORTS
==================

Please send questions and bug reports to report@gnat.com following
the same procedures used to submit reports with the GNAT toolset itself.