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.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 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 two ways of using libexpat with CMake: 47 48### a) 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) 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 102## Building from a Git Clone 103 104If you are building Expat from a check-out from the 105[Git repository](https://github.com/libexpat/libexpat/), 106you need to run a script that generates the configure script using the 107GNU autoconf and libtool tools. To do this, you need to have 108autoconf 2.58 or newer. Run the script like this: 109 110```console 111./buildconf.sh 112``` 113 114Once this has been done, follow the same instructions as for building 115from a source distribution. 116 117 118## Building from a Source Distribution 119 120### a) Building with the configure script (i.e. GNU Autotools) 121 122To build Expat from a source distribution, you first run the 123configuration shell script in the top level distribution directory: 124 125```console 126./configure 127``` 128 129There are many options which you may provide to configure (which you 130can discover by running configure with the `--help` option). But the 131one of most interest is the one that sets the installation directory. 132By default, the configure script will set things up to install 133libexpat into `/usr/local/lib`, `expat.h` into `/usr/local/include`, and 134`xmlwf` into `/usr/local/bin`. If, for example, you'd prefer to install 135into `/home/me/mystuff/lib`, `/home/me/mystuff/include`, and 136`/home/me/mystuff/bin`, you can tell `configure` about that with: 137 138```console 139./configure --prefix=/home/me/mystuff 140``` 141 142Another interesting option is to enable 64-bit integer support for 143line and column numbers and the over-all byte index: 144 145```console 146./configure CPPFLAGS=-DXML_LARGE_SIZE 147``` 148 149However, such a modification would be a breaking change to the ABI 150and is therefore not recommended for general use — e.g. as part of 151a Linux distribution — but rather for builds with special requirements. 152 153After running the configure script, the `make` command will build 154things and `make install` will install things into their proper 155location. Have a look at the `Makefile` to learn about additional 156`make` options. Note that you need to have write permission into 157the directories into which things will be installed. 158 159If you are interested in building Expat to provide document 160information in UTF-16 encoding rather than the default UTF-8, follow 161these instructions (after having run `make distclean`). 162Please note that we configure with `--without-xmlwf` as xmlwf does not 163support this mode of compilation (yet): 164 1651. Mass-patch `Makefile.am` files to use `libexpatw.la` for a library name: 166 <br/> 167 `find . -name Makefile.am -exec sed 168 -e 's,libexpat\.la,libexpatw.la,' 169 -e 's,libexpat_la,libexpatw_la,' 170 -i.bak {} +` 171 1721. Run `automake` to re-write `Makefile.in` files:<br/> 173 `automake` 174 1751. For UTF-16 output as unsigned short (and version/error strings as char), 176 run:<br/> 177 `./configure CPPFLAGS=-DXML_UNICODE --without-xmlwf`<br/> 178 For UTF-16 output as `wchar_t` (incl. version/error strings), run:<br/> 179 `./configure CFLAGS="-g -O2 -fshort-wchar" CPPFLAGS=-DXML_UNICODE_WCHAR_T 180 --without-xmlwf` 181 <br/>Note: The latter requires libc compiled with `-fshort-wchar`, as well. 182 1831. Run `make` (which excludes xmlwf). 184 1851. Run `make install` (again, excludes xmlwf). 186 187Using `DESTDIR` is supported. It works as follows: 188 189```console 190make install DESTDIR=/path/to/image 191``` 192 193overrides the in-makefile set `DESTDIR`, because variable-setting priority is 194 1951. commandline 1961. in-makefile 1971. environment 198 199Note: This only applies to the Expat library itself, building UTF-16 versions 200of xmlwf and the tests is currently not supported. 201 202When using Expat with a project using autoconf for configuration, you 203can use the probing macro in `conftools/expat.m4` to determine how to 204include Expat. See the comments at the top of that file for more 205information. 206 207A reference manual is available in the file `doc/reference.html` in this 208distribution. 209 210 211### b) Building with CMake 212 213The CMake build system is still *experimental* and may replace the primary 214build system based on GNU Autotools at some point when it is ready. 215 216 217#### Available Options 218 219For an idea of the available (non-advanced) options for building with CMake: 220 221```console 222# rm -f CMakeCache.txt ; cmake -D_EXPAT_HELP=ON -LH . | grep -B1 ':.*=' | sed 's,^--$,,' 223// Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel ... 224CMAKE_BUILD_TYPE:STRING= 225 226// Install path prefix, prepended onto install directories. 227CMAKE_INSTALL_PREFIX:PATH=/usr/local 228 229// Path to a program. 230DOCBOOK_TO_MAN:FILEPATH=/usr/bin/docbook2x-man 231 232// Build man page for xmlwf 233EXPAT_BUILD_DOCS:BOOL=ON 234 235// Build the examples for expat library 236EXPAT_BUILD_EXAMPLES:BOOL=ON 237 238// Build fuzzers for the expat library 239EXPAT_BUILD_FUZZERS:BOOL=OFF 240 241// Build pkg-config file 242EXPAT_BUILD_PKGCONFIG:BOOL=ON 243 244// Build the tests for expat library 245EXPAT_BUILD_TESTS:BOOL=ON 246 247// Build the xmlwf tool for expat library 248EXPAT_BUILD_TOOLS:BOOL=ON 249 250// Character type to use (char|ushort|wchar_t) [default=char] 251EXPAT_CHAR_TYPE:STRING=char 252 253// Install expat files in cmake install target 254EXPAT_ENABLE_INSTALL:BOOL=ON 255 256// Use /MT flag (static CRT) when compiling in MSVC 257EXPAT_MSVC_STATIC_CRT:BOOL=OFF 258 259// Build fuzzers via ossfuzz for the expat library 260EXPAT_OSSFUZZ_BUILD:BOOL=OFF 261 262// Build a shared expat library 263EXPAT_SHARED_LIBS:BOOL=ON 264 265// Treat all compiler warnings as errors 266EXPAT_WARNINGS_AS_ERRORS:BOOL=OFF 267 268// Make use of getrandom function (ON|OFF|AUTO) [default=AUTO] 269EXPAT_WITH_GETRANDOM:STRING=AUTO 270 271// Utilize libbsd (for arc4random_buf) 272EXPAT_WITH_LIBBSD:BOOL=OFF 273 274// Make use of syscall SYS_getrandom (ON|OFF|AUTO) [default=AUTO] 275EXPAT_WITH_SYS_GETRANDOM:STRING=AUTO 276``` 277
){kind=link}
){kind=link}