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