1340084Svangyzen[![Travis CI Build Status](https://travis-ci.org/libexpat/libexpat.svg?branch=master)](https://travis-ci.org/libexpat/libexpat) 2340084Svangyzen[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/libexpat/libexpat?svg=true)](https://ci.appveyor.com/project/libexpat/libexpat) 3355604Sdelphij[![Packaging status](https://repology.org/badge/tiny-repos/expat.svg)](https://repology.org/metapackage/expat/versions) 4340084Svangyzen 5340084Svangyzen 6355604Sdelphij# Expat, Release 2.2.9 7340084Svangyzen 8340084SvangyzenThis is Expat, a C library for parsing XML, started by 9340084Svangyzen[James Clark](https://en.wikipedia.org/wiki/James_Clark_(programmer)) in 1997. 10340084SvangyzenExpat is a stream-oriented XML parser. This means that you register 11340084Svangyzenhandlers with the parser before starting the parse. These handlers 12340084Svangyzenare called when the parser discovers the associated structures in the 13340084Svangyzendocument being parsed. A start tag is an example of the kind of 14340084Svangyzenstructures for which you may register handlers. 15340084Svangyzen 16355604SdelphijExpat supports the following compilers: 17355604Sdelphij- GNU GCC >=4.5 18355604Sdelphij- LLVM Clang >=3.5 19355604Sdelphij- Microsoft Visual Studio >=8.0/2005 20355604Sdelphij 21340084SvangyzenWindows users should use the 22340084Svangyzen[`expat_win32` package](https://sourceforge.net/projects/expat/files/expat_win32/), 23340084Svangyzenwhich includes both precompiled libraries and executables, and source code for 24340084Svangyzendevelopers. 25340084Svangyzen 26340084SvangyzenExpat is [free software](https://www.gnu.org/philosophy/free-sw.en.html). 27340084SvangyzenYou may copy, distribute, and modify it under the terms of the License 28340084Svangyzencontained in the file 29340084Svangyzen[`COPYING`](https://github.com/libexpat/libexpat/blob/master/expat/COPYING) 30340084Svangyzendistributed with this package. 31340084SvangyzenThis license is the same as the MIT/X Consortium license. 32340084Svangyzen 33340084SvangyzenIf you are building Expat from a check-out from the 34340084Svangyzen[Git repository](https://github.com/libexpat/libexpat/), 35340084Svangyzenyou need to run a script that generates the configure script using the 36340084SvangyzenGNU autoconf and libtool tools. To do this, you need to have 37340084Svangyzenautoconf 2.58 or newer. Run the script like this: 38340084Svangyzen 39340084Svangyzen```console 40340084Svangyzen./buildconf.sh 41340084Svangyzen``` 42340084Svangyzen 43340084SvangyzenOnce this has been done, follow the same instructions as for building 44340084Svangyzenfrom a source distribution. 45340084Svangyzen 46340084SvangyzenTo build Expat from a source distribution, you first run the 47340084Svangyzenconfiguration shell script in the top level distribution directory: 48340084Svangyzen 49340084Svangyzen```console 50340084Svangyzen./configure 51340084Svangyzen``` 52340084Svangyzen 53340084SvangyzenThere are many options which you may provide to configure (which you 54340084Svangyzencan discover by running configure with the `--help` option). But the 55340084Svangyzenone of most interest is the one that sets the installation directory. 56340084SvangyzenBy default, the configure script will set things up to install 57340084Svangyzenlibexpat into `/usr/local/lib`, `expat.h` into `/usr/local/include`, and 58340084Svangyzen`xmlwf` into `/usr/local/bin`. If, for example, you'd prefer to install 59340084Svangyzeninto `/home/me/mystuff/lib`, `/home/me/mystuff/include`, and 60340084Svangyzen`/home/me/mystuff/bin`, you can tell `configure` about that with: 61340084Svangyzen 62340084Svangyzen```console 63340084Svangyzen./configure --prefix=/home/me/mystuff 64340084Svangyzen``` 65340084Svangyzen 66340084SvangyzenAnother interesting option is to enable 64-bit integer support for 67340084Svangyzenline and column numbers and the over-all byte index: 68340084Svangyzen 69340084Svangyzen```console 70340084Svangyzen./configure CPPFLAGS=-DXML_LARGE_SIZE 71340084Svangyzen``` 72340084Svangyzen 73340084SvangyzenHowever, such a modification would be a breaking change to the ABI 74340084Svangyzenand is therefore not recommended for general use — e.g. as part of 75340084Svangyzena Linux distribution — but rather for builds with special requirements. 76340084Svangyzen 77340084SvangyzenAfter running the configure script, the `make` command will build 78340084Svangyzenthings and `make install` will install things into their proper 79340084Svangyzenlocation. Have a look at the `Makefile` to learn about additional 80340084Svangyzen`make` options. Note that you need to have write permission into 81340084Svangyzenthe directories into which things will be installed. 82340084Svangyzen 83340084SvangyzenIf you are interested in building Expat to provide document 84340084Svangyzeninformation in UTF-16 encoding rather than the default UTF-8, follow 85340084Svangyzenthese instructions (after having run `make distclean`). 86340084SvangyzenPlease note that we configure with `--without-xmlwf` as xmlwf does not 87340084Svangyzensupport this mode of compilation (yet): 88340084Svangyzen 89340084Svangyzen1. Mass-patch `Makefile.am` files to use `libexpatw.la` for a library name: 90340084Svangyzen <br/> 91340084Svangyzen `find -name Makefile.am -exec sed 92340084Svangyzen -e 's,libexpat\.la,libexpatw.la,' 93340084Svangyzen -e 's,libexpat_la,libexpatw_la,' 94340084Svangyzen -i {} +` 95340084Svangyzen 96340084Svangyzen1. Run `automake` to re-write `Makefile.in` files:<br/> 97340084Svangyzen `automake` 98340084Svangyzen 99340084Svangyzen1. For UTF-16 output as unsigned short (and version/error strings as char), 100340084Svangyzen run:<br/> 101340084Svangyzen `./configure CPPFLAGS=-DXML_UNICODE --without-xmlwf`<br/> 102340084Svangyzen For UTF-16 output as `wchar_t` (incl. version/error strings), run:<br/> 103340084Svangyzen `./configure CFLAGS="-g -O2 -fshort-wchar" CPPFLAGS=-DXML_UNICODE_WCHAR_T 104340084Svangyzen --without-xmlwf` 105340084Svangyzen <br/>Note: The latter requires libc compiled with `-fshort-wchar`, as well. 106340084Svangyzen 107340084Svangyzen1. Run `make` (which excludes xmlwf). 108340084Svangyzen 109340084Svangyzen1. Run `make install` (again, excludes xmlwf). 110340084Svangyzen 111340084SvangyzenUsing `DESTDIR` is supported. It works as follows: 112340084Svangyzen 113340084Svangyzen```console 114340084Svangyzenmake install DESTDIR=/path/to/image 115340084Svangyzen``` 116340084Svangyzen 117340084Svangyzenoverrides the in-makefile set `DESTDIR`, because variable-setting priority is 118340084Svangyzen 119340084Svangyzen1. commandline 120340084Svangyzen1. in-makefile 121340084Svangyzen1. environment 122340084Svangyzen 123340084SvangyzenNote: This only applies to the Expat library itself, building UTF-16 versions 124340084Svangyzenof xmlwf and the tests is currently not supported. 125340084Svangyzen 126340084SvangyzenWhen using Expat with a project using autoconf for configuration, you 127340084Svangyzencan use the probing macro in `conftools/expat.m4` to determine how to 128340084Svangyzeninclude Expat. See the comments at the top of that file for more 129340084Svangyzeninformation. 130340084Svangyzen 131340084SvangyzenA reference manual is available in the file `doc/reference.html` in this 132340084Svangyzendistribution. 133355604Sdelphij 134355604Sdelphij 135355604SdelphijThe CMake build system is still *experimental* and will replace the primary 136355604Sdelphijbuild system based on GNU Autotools at some point when it is ready. 137355604SdelphijFor an idea of the available (non-advanced) options for building with CMake: 138355604Sdelphij 139355604Sdelphij```console 140355604Sdelphij# rm -f CMakeCache.txt ; cmake -D_EXPAT_HELP=ON -LH . | grep -B1 ':.*=' | sed 's,^--$,,' 141355604Sdelphij// Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel ... 142355604SdelphijCMAKE_BUILD_TYPE:STRING= 143355604Sdelphij 144355604Sdelphij// Install path prefix, prepended onto install directories. 145355604SdelphijCMAKE_INSTALL_PREFIX:PATH=/usr/local 146355604Sdelphij 147355604Sdelphij// Path to a program. 148355604SdelphijDOCBOOK_TO_MAN:FILEPATH=/usr/bin/docbook2x-man 149355604Sdelphij 150355604Sdelphij// build man page for xmlwf 151355604SdelphijEXPAT_BUILD_DOCS:BOOL=ON 152355604Sdelphij 153355604Sdelphij// build the examples for expat library 154355604SdelphijEXPAT_BUILD_EXAMPLES:BOOL=ON 155355604Sdelphij 156355604Sdelphij// build fuzzers for the expat library 157355604SdelphijEXPAT_BUILD_FUZZERS:BOOL=OFF 158355604Sdelphij 159355604Sdelphij// build the tests for expat library 160355604SdelphijEXPAT_BUILD_TESTS:BOOL=ON 161355604Sdelphij 162355604Sdelphij// build the xmlwf tool for expat library 163355604SdelphijEXPAT_BUILD_TOOLS:BOOL=ON 164355604Sdelphij 165355604Sdelphij// Character type to use (char|ushort|wchar_t) [default=char] 166355604SdelphijEXPAT_CHAR_TYPE:STRING=char 167355604Sdelphij 168355604Sdelphij// install expat files in cmake install target 169355604SdelphijEXPAT_ENABLE_INSTALL:BOOL=ON 170355604Sdelphij 171355604Sdelphij// Use /MT flag (static CRT) when compiling in MSVC 172355604SdelphijEXPAT_MSVC_STATIC_CRT:BOOL=OFF 173355604Sdelphij 174355604Sdelphij// build a shared expat library 175355604SdelphijEXPAT_SHARED_LIBS:BOOL=ON 176355604Sdelphij 177355604Sdelphij// Treat all compiler warnings as errors 178355604SdelphijEXPAT_WARNINGS_AS_ERRORS:BOOL=OFF 179355604Sdelphij 180355604Sdelphij// Make use of getrandom function (ON|OFF|AUTO) [default=AUTO] 181355604SdelphijEXPAT_WITH_GETRANDOM:STRING=AUTO 182355604Sdelphij 183355604Sdelphij// utilize libbsd (for arc4random_buf) 184355604SdelphijEXPAT_WITH_LIBBSD:BOOL=OFF 185355604Sdelphij 186355604Sdelphij// Make use of syscall SYS_getrandom (ON|OFF|AUTO) [default=AUTO] 187355604SdelphijEXPAT_WITH_SYS_GETRANDOM:STRING=AUTO 188355604Sdelphij``` 189