1[](https://github.com/libexpat/libexpat/actions/workflows/linux.yml) 2[](https://ci.appveyor.com/project/libexpat/libexpat) 3[](https://repology.org/metapackage/expat/versions) 4[](https://sourceforge.net/projects/expat/files/) 5[](https://github.com/libexpat/libexpat/releases) 6 7 8# Expat, Release 2.5.0 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
){kind=link}
){kind=link}