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