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