README.md
1XML/Ada: A XML parser for Ada95
2===============================
3
4INSTALLING THIS LIBRARY ON UNIX
5-------------------------------
6
7Make sure that you do not have a previous installation of XML/Ada in one
8of the directories given in ADA_OBJECTS_PATH, or some files will not be
9properly recompiled.
10
11Compiling with GNAT 3.16 or newer versions of GNAT
12~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13
14You need to automatically detect a few aspects of your build environment,
15which is done by running
16 ./configure --prefix=PREFIX
17where PREFIX is the installation directory you wish to use. It is recommended
18to install into the GNAT directory. This way the project files will be
19installed into the default location where gnatmake and gprbuild are looking
20for projects.
21
22If, however, you are running a cross-compiler, you need to add an additional
23command line switch to configure, namely
24 ./configure --prefix=PREFIX --target=TARGET
25where target will be similar to "powerpc-wrs-vxworks", "powerpc-elinos-linux",
26or any other prefix used to find the name of the gnatmake executable to run.
27
28By default, XML/Ada will build both static and shared libraries, if
29"configure" detected that the latter were supported on your system. You can
30prevent the building of shared libraries by specifying --disable-shared as
31an extra switch to configure.
32
33Once installed, your applications will by default be linked statically with
34XML/Ada. You can change that default by specifying explicitly --enable-shared
35as an extra switch to configure.
36
37To install the library, use the following command line:
38 make all install
39
40If your application is built using a runtime which is not the default,
41you need to build XmlAda with the same runtime. This is done by simply
42adding an RTS=NAME argument to the make command above. For instance,
43to build and install the XmlAda library with the "rtp" runtime, adjust
44the make command above as follow:
45
46 make all install RTS=rtp
47
48You can also override the default install location by adding the argument
49IPREFIX=PATH to the make command above.
50
51Compiling with other Ada compilers
52~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53
54This library has been reported as being compilable with other compilers than
55GNAT. No build script is provided however.
56
57INSTALLING THIS LIBRARY ON WINDOWS
58----------------------------------
59
601. Due to the nature of GNU Make you need to have a UNIX-type shell and
61 utilities installed to build this library. If you do not have this,
62 you can download a set at:
63
64 Cygwin : http://cygwin.com/
65 Mingw : http://www.mingw.org/ (MSYS Toolset)
66
672. Run 'sh configure --prefix=<installation directory>' to generate the
68 makefile.
69 where "installation directory" is the place where you want to install
70 XML/Ada.
71
723. Before building make sure to set the following values in 'Makefile':
73 PREFIX=C:/GNATPRO/6.4.2
74 the makefile where to install the library. Note the slashes in the path!
75 The value should have been set properly by the call to configure.
76
77 It is recommended to install into the GNAT directory. This way the project
78 files will be installed into the default location where gnatmake and
79 gprbuild are looking for projects.
80
814. As a general rule for GNAT, the temporary directory must be accessible
82 from gnatmake native applications (not a cygwin path). For instance, from
83 cygwin:
84 export TMPDIR=c:/tmp
85 Failing to check this might prevent the building of shared libraries
86
875. The best way to proceed is to do a 'make all install'.
88 It is possible that make complains that it cannot execute an "install"
89 executable. In such a case, it is recommended to execute
90 "make INSTALL=cp install" instead to use "cp" to do the installation
91
92TWEAKING THE LIBRARY
93--------------------
94
95You can change the way the library behaves, in particular the DOM part,
96by changing some of the hard-coded constants in the code. If you change
97these, you will need to recompile the library and your application:
98
99- sax-encodings.ads :: Encoding
100 It contains the encoding used internally by the library. The default is
101 UTF8, which supports the whole Unicode range, and is economical
102 memory-wise
103
104- dom-core.ads :: Shared_Strings and dom-core.ads :: Shared_Node_Names
105 Whether the internal representation of namespaces should be shared among
106 nodes. The default is yes
107
108USING THE LIBRARY
109-----------------
110
111See the XML/Ada user's guide for information on how to use this library.
112
113TESTING THE LIBRARY
114-------------------
115
116Several test programs are provided in the XML/Ada source package. These
117are found in the dom/test and sax/test subdirectories. These are very simple
118examples on how to use the DOM and SAX API.
119
120The w3c organization has constructed an official testsuite that can be used to
121check XML/Ada. Most likely, this is only useful to you if you are modifying
122XML/Ada itself. Here is how you can run this testsuite:
123 You need to download the official XML Conformance Testsuite for XML,
124 The name of the current archive is
125 xmlts20080827.tar
126 The URL is:
127 http://www.w3.org/XML/Test/
128
129 Uncompress it somewhere on your disk, then add a link in tests/dom, which
130 points to the directory where you unpackaged the testsuite. The link should
131 be called "tests".
132
133A similar setup is required for the W3C schema testsuite. The URL of the
134testsuite is:
135 http://www.w3.org/XML/2004/xml-schema-test-suite/xmlschema2006-11-06/xsts-2007-06-20.tar.gz
136This file should be extracted in the tests/schema directory (creating a
137xmlschema-2006-11-06 subdirectory as a result).
138
139 Then execute the command from the toplevel directory:
140 make run_test
141
142 This will report the number of errors found.
143
144The W3C committee has reviewed the status of a number of tests since the
145testsuite was released (as developers of XML parsers have reported issues
146with the testsuite). They provide a public CVS repository that include the
147metadata for the tests (list of tests, their status, expected output,...),
148but unfortunately not the tests themselves. As a result, getting the latest
149version requires several steps. First get the .tar.gz as described above,
150and extract it in schema/test. From the same directory, run:
151
152 cvs -d :pserver:anonymous@dev.w3.org:/sources/public login
153 cvs -d :pserver:anonymous@dev.w3.org:/sources/public -z5 co XML/xml-schema-test-suite/2004-01-14/xmlschema2006-11-06
154
155You can update that directory at any time with:
156 cd XML; cvs update
157
158The XML/Ada testsuite will automatically take advantage of that directory
159if found. You need however to manually run
160 cd schema/test
161 ./schematest --cvs
162to get the output under those conditions, since "make run_test" is setup
163for the .tar.gz output.
164
165
166CONTENTS OF THE LIBRARY
167-----------------------
168
169The sources in this library are split into several subdirectories, each
170with its own README, sources, documentation and unit tests.
171
172The list of subdirectories (aka modules) is:
173
174- unicode:
175 provides a full support for Unicode and Utf8/Utf16/Utf32 encodings. It also
176 support other encodings like Latin1, Latin2, ...
177
178- input_sources
179 provides types to read characters from several types of media.
180
181- sax
182 Provides a common, standard interface for any XML parser, through
183 callback subprograms. You can extend any of the tagged types defined in these
184 package and thus parse XML files without having to store a XML tree in
185 memory.
186 This package is compatible with SAX 2.0, but doesn't implement the functions
187 specific to SAX 1.0
188
189- dom
190 The Document Object Model is a set of standard subprograms to manipulate
191 XML tree in memory.
192 Only the Core module is currently implemented.
193
194- docs
195 This contains the full documentation for this XML library
196
197BUG REPORTS
198-----------
199
200Please send questions and bug reports to report@gnat.com following
201the same procedures used to submit reports with the GNAT toolset itself.
202