Name Date Size

..18-Aug.-20214 KiB

.github/H02-May-20214 KiB

.gitignoreH A D29-Aug.-2017360

.mailmapH A D02-May-2021845

.travis.shH A D02-May-20212.7 KiB

appveyor.ymlH A D02-May-20214.3 KiB

BrewfileH A D06-Apr.-2021208

expat/H20-Sep.-20214 KiB

README.mdH A D23-May-20218.6 KiB

testdata/H29-Aug.-20174 KiB

README.md

1[![Run Linux Travis CI tasks](https://github.com/libexpat/libexpat/actions/workflows/linux.yml/badge.svg)](https://github.com/libexpat/libexpat/actions/workflows/linux.yml)
2[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/libexpat/libexpat?svg=true)](https://ci.appveyor.com/project/libexpat/libexpat)
3[![Packaging status](https://repology.org/badge/tiny-repos/expat.svg)](https://repology.org/metapackage/expat/versions)
4[![Downloads SourceForge](https://img.shields.io/sourceforge/dt/expat?label=Downloads%20SourceForge)](https://sourceforge.net/projects/expat/files/)
5[![Downloads GitHub](https://img.shields.io/github/downloads/libexpat/libexpat/total?label=Downloads%20GitHub)](https://github.com/libexpat/libexpat/releases)
6
7
8# Expat, Release 2.4.1
9
10This is Expat, a C library for parsing XML, started by
11[James Clark](https://en.wikipedia.org/wiki/James_Clark_%28programmer%29) in 1997.
12Expat is a stream-oriented XML parser.  This means that you register
13handlers with the parser before starting the parse.  These handlers
14are called when the parser discovers the associated structures in the
15document being parsed.  A start tag is an example of the kind of
16structures for which you may register handlers.
17
18Expat supports the following compilers:
19
20- GNU GCC >=4.5
21- LLVM Clang >=3.5
22- Microsoft Visual Studio >=15.0/2017 (rolling `${today} minus 5 years`)
23
24Windows users can use the
25[`expat-win32bin-*.*.*.{exe,zip}` download](https://github.com/libexpat/libexpat/releases),
26which includes both pre-compiled libraries and executables, and source code for
27developers.
28
29Expat is [free software](https://www.gnu.org/philosophy/free-sw.en.html).
30You may copy, distribute, and modify it under the terms of the License
31contained in the file
32[`COPYING`](https://github.com/libexpat/libexpat/blob/master/expat/COPYING)
33distributed with this package.
34This license is the same as the MIT/X Consortium license.
35
36
37## Using libexpat in your CMake-Based Project
38
39There are two ways of using libexpat with CMake:
40
41### a) Module Mode
42
43This approach leverages CMake's own [module `FindEXPAT`](https://cmake.org/cmake/help/latest/module/FindEXPAT.html).
44
45Notice the *uppercase* `EXPAT` in the following example:
46
47```cmake
48cmake_minimum_required(VERSION 3.0)  # or 3.10, see below
49
50project(hello VERSION 1.0.0)
51
52find_package(EXPAT 2.2.8 MODULE REQUIRED)
53
54add_executable(hello
55    hello.c
56)
57
58# a) for CMake >=3.10 (see CMake's FindEXPAT docs)
59target_link_libraries(hello PUBLIC EXPAT::EXPAT)
60
61# b) for CMake >=3.0
62target_include_directories(hello PRIVATE ${EXPAT_INCLUDE_DIRS})
63target_link_libraries(hello PUBLIC ${EXPAT_LIBRARIES})
64```
65
66### b) Config Mode
67
68This approach requires files from…
69
70- libexpat >=2.2.8 where packaging uses the CMake build system
71or
72- libexpat >=2.3.0 where packaging uses the GNU Autotools build system
73  on Linux
74or
75- libexpat >=2.4.0 where packaging uses the GNU Autotools build system
76  on macOS or MinGW.
77
78Notice the *lowercase* `expat` in the following example:
79
80```cmake
81cmake_minimum_required(VERSION 3.0)
82
83project(hello VERSION 1.0.0)
84
85find_package(expat 2.2.8 CONFIG REQUIRED char dtd ns)
86
87add_executable(hello
88    hello.c
89)
90
91target_link_libraries(hello PUBLIC expat::expat)
92```
93
94
95## Building from a Git Clone
96
97If you are building Expat from a check-out from the
98[Git repository](https://github.com/libexpat/libexpat/),
99you need to run a script that generates the configure script using the
100GNU autoconf and libtool tools.  To do this, you need to have
101autoconf 2.58 or newer. Run the script like this:
102
103```console
104./buildconf.sh
105```
106
107Once this has been done, follow the same instructions as for building
108from a source distribution.
109
110
111## Building from a Source Distribution
112
113### a) Building with the configure script (i.e. GNU Autotools)
114
115To build Expat from a source distribution, you first run the
116configuration shell script in the top level distribution directory:
117
118```console
119./configure
120```
121
122There are many options which you may provide to configure (which you
123can discover by running configure with the `--help` option).  But the
124one of most interest is the one that sets the installation directory.
125By default, the configure script will set things up to install
126libexpat into `/usr/local/lib`, `expat.h` into `/usr/local/include`, and
127`xmlwf` into `/usr/local/bin`.  If, for example, you'd prefer to install
128into `/home/me/mystuff/lib`, `/home/me/mystuff/include`, and
129`/home/me/mystuff/bin`, you can tell `configure` about that with:
130
131```console
132./configure --prefix=/home/me/mystuff
133```
134
135Another interesting option is to enable 64-bit integer support for
136line and column numbers and the over-all byte index:
137
138```console
139./configure CPPFLAGS=-DXML_LARGE_SIZE
140```
141
142However, such a modification would be a breaking change to the ABI
143and is therefore not recommended for general use — e.g. as part of
144a Linux distribution — but rather for builds with special requirements.
145
146After running the configure script, the `make` command will build
147things and `make install` will install things into their proper
148location.  Have a look at the `Makefile` to learn about additional
149`make` options.  Note that you need to have write permission into
150the directories into which things will be installed.
151
152If you are interested in building Expat to provide document
153information in UTF-16 encoding rather than the default UTF-8, follow
154these instructions (after having run `make distclean`).
155Please note that we configure with `--without-xmlwf` as xmlwf does not
156support this mode of compilation (yet):
157
1581. Mass-patch `Makefile.am` files to use `libexpatw.la` for a library name:
159   <br/>
160   `find -name Makefile.am -exec sed
161       -e 's,libexpat\.la,libexpatw.la,'
162       -e 's,libexpat_la,libexpatw_la,'
163       -i {} +`
164
1651. Run `automake` to re-write `Makefile.in` files:<br/>
166   `automake`
167
1681. For UTF-16 output as unsigned short (and version/error strings as char),
169   run:<br/>
170   `./configure CPPFLAGS=-DXML_UNICODE --without-xmlwf`<br/>
171   For UTF-16 output as `wchar_t` (incl. version/error strings), run:<br/>
172   `./configure CFLAGS="-g -O2 -fshort-wchar" CPPFLAGS=-DXML_UNICODE_WCHAR_T
173       --without-xmlwf`
174   <br/>Note: The latter requires libc compiled with `-fshort-wchar`, as well.
175
1761. Run `make` (which excludes xmlwf).
177
1781. Run `make install` (again, excludes xmlwf).
179
180Using `DESTDIR` is supported.  It works as follows:
181
182```console
183make install DESTDIR=/path/to/image
184```
185
186overrides the in-makefile set `DESTDIR`, because variable-setting priority is
187
1881. commandline
1891. in-makefile
1901. environment
191
192Note: This only applies to the Expat library itself, building UTF-16 versions
193of xmlwf and the tests is currently not supported.
194
195When using Expat with a project using autoconf for configuration, you
196can use the probing macro in `conftools/expat.m4` to determine how to
197include Expat.  See the comments at the top of that file for more
198information.
199
200A reference manual is available in the file `doc/reference.html` in this
201distribution.
202
203
204### b) Building with CMake
205
206The CMake build system is still *experimental* and may replace the primary
207build system based on GNU Autotools at some point when it is ready.
208
209
210#### Available Options
211
212For an idea of the available (non-advanced) options for building with CMake:
213
214```console
215# rm -f CMakeCache.txt ; cmake -D_EXPAT_HELP=ON -LH . | grep -B1 ':.*=' | sed 's,^--$,,'
216// Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel ...
217CMAKE_BUILD_TYPE:STRING=
218
219// Install path prefix, prepended onto install directories.
220CMAKE_INSTALL_PREFIX:PATH=/usr/local
221
222// Path to a program.
223DOCBOOK_TO_MAN:FILEPATH=/usr/bin/docbook2x-man
224
225// build man page for xmlwf
226EXPAT_BUILD_DOCS:BOOL=ON
227
228// build the examples for expat library
229EXPAT_BUILD_EXAMPLES:BOOL=ON
230
231// build fuzzers for the expat library
232EXPAT_BUILD_FUZZERS:BOOL=OFF
233
234// build pkg-config file
235EXPAT_BUILD_PKGCONFIG:BOOL=ON
236
237// build the tests for expat library
238EXPAT_BUILD_TESTS:BOOL=ON
239
240// build the xmlwf tool for expat library
241EXPAT_BUILD_TOOLS:BOOL=ON
242
243// Character type to use (char|ushort|wchar_t) [default=char]
244EXPAT_CHAR_TYPE:STRING=char
245
246// install expat files in cmake install target
247EXPAT_ENABLE_INSTALL:BOOL=ON
248
249// Use /MT flag (static CRT) when compiling in MSVC
250EXPAT_MSVC_STATIC_CRT:BOOL=OFF
251
252// build fuzzers via ossfuzz for the expat library
253EXPAT_OSSFUZZ_BUILD:BOOL=OFF
254
255// build a shared expat library
256EXPAT_SHARED_LIBS:BOOL=ON
257
258// Treat all compiler warnings as errors
259EXPAT_WARNINGS_AS_ERRORS:BOOL=OFF
260
261// Make use of getrandom function (ON|OFF|AUTO) [default=AUTO]
262EXPAT_WITH_GETRANDOM:STRING=AUTO
263
264// utilize libbsd (for arc4random_buf)
265EXPAT_WITH_LIBBSD:BOOL=OFF
266
267// Make use of syscall SYS_getrandom (ON|OFF|AUTO) [default=AUTO]
268EXPAT_WITH_SYS_GETRANDOM:STRING=AUTO
269```
270