README.md

   1 [![Run Linux CI tasks](https://github.com/libexpat/libexpat/actions/workflows/linux.yml/badge.svg)](https://github.com/libexpat/libexpat/actions/workflows/linux.yml)
   2 [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/libexpat/libexpat?svg=true)](https://ci.appveyor.com/project/libexpat/libexpat)
   3 [![Packaging status](https://repology.org/badge/tiny-repos/expat.svg)](https://repology.org/metapackage/expat/versions)
   4 [![Downloads SourceForge](https://img.shields.io/sourceforge/dt/expat?label=Downloads%20SourceForge)](https://sourceforge.net/projects/expat/files/)
   5 [![Downloads GitHub](https://img.shields.io/github/downloads/libexpat/libexpat/total?label=Downloads%20GitHub)](https://github.com/libexpat/libexpat/releases)
   6
   7
   8 # Expat, Release 2.6.0
   9
  10 This 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.
  13 Expat is a stream-oriented XML parser.  This means that you register
  14 handlers with the parser before starting the parse.  These handlers
  15 are called when the parser discovers the associated structures in the
  16 document being parsed.  A start tag is an example of the kind of
  17 structures for which you may register handlers.
  18
  19 Expat 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
  25 Windows users can use the
  26 [`expat-win32bin-*.*.*.{exe,zip}` download](https://github.com/libexpat/libexpat/releases),
  27 which includes both pre-compiled libraries and executables, and source code for
  28 developers.
  29
  30 Expat is [free software](https://www.gnu.org/philosophy/free-sw.en.html).
  31 You may copy, distribute, and modify it under the terms of the License
  32 contained in the file
  33 [`COPYING`](https://github.com/libexpat/libexpat/blob/master/expat/COPYING)
  34 distributed with this package.
  35 This license is the same as the MIT/X Consortium license.
  36
  37
  38 ## Using libexpat in your CMake-Based Project
  39
  40 There are two ways of using libexpat with CMake:
  41
  42 ### a) Module Mode
  43
  44 This approach leverages CMake's own [module `FindEXPAT`](https://cmake.org/cmake/help/latest/module/FindEXPAT.html).
  45
  46 Notice the *uppercase* `EXPAT` in the following example:
  47
  48 ```cmake
  49 cmake_minimum_required(VERSION 3.0)  # or 3.10, see below
  50
  51 project(hello VERSION 1.0.0)
  52
  53 find_package(EXPAT 2.2.8 MODULE REQUIRED)
  54
  55 add_executable(hello
  56     hello.c
  57 )
  58
  59 # a) for CMake >=3.10 (see CMake's FindEXPAT docs)
  60 target_link_libraries(hello PUBLIC EXPAT::EXPAT)
  61
  62 # b) for CMake >=3.0
  63 target_include_directories(hello PRIVATE ${EXPAT_INCLUDE_DIRS})
  64 target_link_libraries(hello PUBLIC ${EXPAT_LIBRARIES})
  65 ```
  66
  67 ### b) Config Mode
  68
  69 This approach requires files from…
  70
  71 - libexpat >=2.2.8 where packaging uses the CMake build system
  72 or
  73 - libexpat >=2.3.0 where packaging uses the GNU Autotools build system
  74   on Linux
  75 or
  76 - libexpat >=2.4.0 where packaging uses the GNU Autotools build system
  77   on macOS or MinGW.
  78
  79 Notice the *lowercase* `expat` in the following example:
  80
  81 ```cmake
  82 cmake_minimum_required(VERSION 3.0)
  83
  84 project(hello VERSION 1.0.0)
  85
  86 find_package(expat 2.2.8 CONFIG REQUIRED char dtd ns)
  87
  88 add_executable(hello
  89     hello.c
  90 )
  91
  92 target_link_libraries(hello PUBLIC expat::expat)
  93 ```
  94
  95
  96 ## Building from a Git Clone
  97
  98 If you are building Expat from a check-out from the
  99 [Git repository](https://github.com/libexpat/libexpat/),
 100 you need to run a script that generates the configure script using the
 101 GNU autoconf and libtool tools.  To do this, you need to have
 102 autoconf 2.58 or newer. Run the script like this:
 103
 104 ```console
 105 ./buildconf.sh
 106 ```
 107
 108 Once this has been done, follow the same instructions as for building
 109 from a source distribution.
 110
 111
 112 ## Building from a Source Distribution
 113
 114 ### a) Building with the configure script (i.e. GNU Autotools)
 115
 116 To build Expat from a source distribution, you first run the
 117 configuration shell script in the top level distribution directory:
 118
 119 ```console
 120 ./configure
 121 ```
 122
 123 There are many options which you may provide to configure (which you
 124 can discover by running configure with the `--help` option).  But the
 125 one of most interest is the one that sets the installation directory.
 126 By default, the configure script will set things up to install
 127 libexpat 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
 129 into `/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
 136 Another interesting option is to enable 64-bit integer support for
 137 line and column numbers and the over-all byte index:
 138
 139 ```console
 140 ./configure CPPFLAGS=-DXML_LARGE_SIZE
 141 ```
 142
 143 However, such a modification would be a breaking change to the ABI
 144 and is therefore not recommended for general use &mdash; e.g. as part of
 145 a Linux distribution &mdash; but rather for builds with special requirements.
 146
 147 After running the configure script, the `make` command will build
 148 things and `make install` will install things into their proper
 149 location.  Have a look at the `Makefile` to learn about additional
 150 `make` options.  Note that you need to have write permission into
 151 the directories into which things will be installed.
 152
 153 If you are interested in building Expat to provide document
 154 information in UTF-16 encoding rather than the default UTF-8, follow
 155 these instructions (after having run `make distclean`).
 156 Please note that we configure with `--without-xmlwf` as xmlwf does not
 157 support this mode of compilation (yet):
 158
 159 1. 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
 166 1. Run `automake` to re-write `Makefile.in` files:<br/>
 167    `automake`
 168
 169 1. 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
 177 1. Run `make` (which excludes xmlwf).
 178
 179 1. Run `make install` (again, excludes xmlwf).
 180
 181 Using `DESTDIR` is supported.  It works as follows:
 182
 183 ```console
 184 make install DESTDIR=/path/to/image
 185 ```
 186
 187 overrides the in-makefile set `DESTDIR`, because variable-setting priority is
 188
 189 1. commandline
 190 1. in-makefile
 191 1. environment
 192
 193 Note: This only applies to the Expat library itself, building UTF-16 versions
 194 of xmlwf and the tests is currently not supported.
 195
 196 When using Expat with a project using autoconf for configuration, you
 197 can use the probing macro in `conftools/expat.m4` to determine how to
 198 include Expat.  See the comments at the top of that file for more
 199 information.
 200
 201 A reference manual is available in the file `doc/reference.html` in this
 202 distribution.
 203
 204
 205 ### b) Building with CMake
 206
 207 The CMake build system is still *experimental* and may replace the primary
 208 build system based on GNU Autotools at some point when it is ready.
 209
 210
 211 #### Available Options
 212
 213 For 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 ...
 218 CMAKE_BUILD_TYPE:STRING=
 219
 220 // Install path prefix, prepended onto install directories.
 221 CMAKE_INSTALL_PREFIX:PATH=/usr/local
 222
 223 // Path to a program.
 224 DOCBOOK_TO_MAN:FILEPATH=/usr/bin/docbook2x-man
 225
 226 // Build man page for xmlwf
 227 EXPAT_BUILD_DOCS:BOOL=ON
 228
 229 // Build the examples for expat library
 230 EXPAT_BUILD_EXAMPLES:BOOL=ON
 231
 232 // Build fuzzers for the expat library
 233 EXPAT_BUILD_FUZZERS:BOOL=OFF
 234
 235 // Build pkg-config file
 236 EXPAT_BUILD_PKGCONFIG:BOOL=ON
 237
 238 // Build the tests for expat library
 239 EXPAT_BUILD_TESTS:BOOL=ON
 240
 241 // Build the xmlwf tool for expat library
 242 EXPAT_BUILD_TOOLS:BOOL=ON
 243
 244 // Character type to use (char|ushort|wchar_t) [default=char]
 245 EXPAT_CHAR_TYPE:STRING=char
 246
 247 // Install expat files in cmake install target
 248 EXPAT_ENABLE_INSTALL:BOOL=ON
 249
 250 // Use /MT flag (static CRT) when compiling in MSVC
 251 EXPAT_MSVC_STATIC_CRT:BOOL=OFF
 252
 253 // Build fuzzers via ossfuzz for the expat library
 254 EXPAT_OSSFUZZ_BUILD:BOOL=OFF
 255
 256 // Build a shared expat library
 257 EXPAT_SHARED_LIBS:BOOL=ON
 258
 259 // Treat all compiler warnings as errors
 260 EXPAT_WARNINGS_AS_ERRORS:BOOL=OFF
 261
 262 // Make use of getrandom function (ON|OFF|AUTO) [default=AUTO]
 263 EXPAT_WITH_GETRANDOM:STRING=AUTO
 264
 265 // Utilize libbsd (for arc4random_buf)
 266 EXPAT_WITH_LIBBSD:BOOL=OFF
 267
 268 // Make use of syscall SYS_getrandom (ON|OFF|AUTO) [default=AUTO]
 269 EXPAT_WITH_SYS_GETRANDOM:STRING=AUTO
 270 ```