README.md

   1 [![Travis CI Build Status](https://travis-ci.org/libexpat/libexpat.svg?branch=master)](https://travis-ci.org/libexpat/libexpat)
   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
   5
   6 # Expat, Release 2.2.9
   7
   8 This is Expat, a C library for parsing XML, started by
   9 [James Clark](https://en.wikipedia.org/wiki/James_Clark_(programmer)) in 1997.
  10 Expat is a stream-oriented XML parser.  This means that you register
  11 handlers with the parser before starting the parse.  These handlers
  12 are called when the parser discovers the associated structures in the
  13 document being parsed.  A start tag is an example of the kind of
  14 structures for which you may register handlers.
  15
  16 Expat supports the following compilers:
  17 - GNU GCC >=4.5
  18 - LLVM Clang >=3.5
  19 - Microsoft Visual Studio >=8.0/2005
  20
  21 Windows users should use the
  22 [`expat_win32` package](https://sourceforge.net/projects/expat/files/expat_win32/),
  23 which includes both precompiled libraries and executables, and source code for
  24 developers.
  25
  26 Expat is [free software](https://www.gnu.org/philosophy/free-sw.en.html).
  27 You may copy, distribute, and modify it under the terms of the License
  28 contained in the file
  29 [`COPYING`](https://github.com/libexpat/libexpat/blob/master/expat/COPYING)
  30 distributed with this package.
  31 This license is the same as the MIT/X Consortium license.
  32
  33 If you are building Expat from a check-out from the
  34 [Git repository](https://github.com/libexpat/libexpat/),
  35 you need to run a script that generates the configure script using the
  36 GNU autoconf and libtool tools.  To do this, you need to have
  37 autoconf 2.58 or newer. Run the script like this:
  38
  39 ```console
  40 ./buildconf.sh
  41 ```
  42
  43 Once this has been done, follow the same instructions as for building
  44 from a source distribution.
  45
  46 To build Expat from a source distribution, you first run the
  47 configuration shell script in the top level distribution directory:
  48
  49 ```console
  50 ./configure
  51 ```
  52
  53 There are many options which you may provide to configure (which you
  54 can discover by running configure with the `--help` option).  But the
  55 one of most interest is the one that sets the installation directory.
  56 By default, the configure script will set things up to install
  57 libexpat into `/usr/local/lib`, `expat.h` into `/usr/local/include`, and
  58 `xmlwf` into `/usr/local/bin`.  If, for example, you'd prefer to install
  59 into `/home/me/mystuff/lib`, `/home/me/mystuff/include`, and
  60 `/home/me/mystuff/bin`, you can tell `configure` about that with:
  61
  62 ```console
  63 ./configure --prefix=/home/me/mystuff
  64 ```
  65
  66 Another interesting option is to enable 64-bit integer support for
  67 line and column numbers and the over-all byte index:
  68
  69 ```console
  70 ./configure CPPFLAGS=-DXML_LARGE_SIZE
  71 ```
  72
  73 However, such a modification would be a breaking change to the ABI
  74 and is therefore not recommended for general use &mdash; e.g. as part of
  75 a Linux distribution &mdash; but rather for builds with special requirements.
  76
  77 After running the configure script, the `make` command will build
  78 things and `make install` will install things into their proper
  79 location.  Have a look at the `Makefile` to learn about additional
  80 `make` options.  Note that you need to have write permission into
  81 the directories into which things will be installed.
  82
  83 If you are interested in building Expat to provide document
  84 information in UTF-16 encoding rather than the default UTF-8, follow
  85 these instructions (after having run `make distclean`).
  86 Please note that we configure with `--without-xmlwf` as xmlwf does not
  87 support this mode of compilation (yet):
  88
  89 1. Mass-patch `Makefile.am` files to use `libexpatw.la` for a library name:
  90    <br/>
  91    `find -name Makefile.am -exec sed
  92        -e 's,libexpat\.la,libexpatw.la,'
  93        -e 's,libexpat_la,libexpatw_la,'
  94        -i {} +`
  95
  96 1. Run `automake` to re-write `Makefile.in` files:<br/>
  97    `automake`
  98
  99 1. For UTF-16 output as unsigned short (and version/error strings as char),
 100    run:<br/>
 101    `./configure CPPFLAGS=-DXML_UNICODE --without-xmlwf`<br/>
 102    For UTF-16 output as `wchar_t` (incl. version/error strings), run:<br/>
 103    `./configure CFLAGS="-g -O2 -fshort-wchar" CPPFLAGS=-DXML_UNICODE_WCHAR_T
 104        --without-xmlwf`
 105    <br/>Note: The latter requires libc compiled with `-fshort-wchar`, as well.
 106
 107 1. Run `make` (which excludes xmlwf).
 108
 109 1. Run `make install` (again, excludes xmlwf).
 110
 111 Using `DESTDIR` is supported.  It works as follows:
 112
 113 ```console
 114 make install DESTDIR=/path/to/image
 115 ```
 116
 117 overrides the in-makefile set `DESTDIR`, because variable-setting priority is
 118
 119 1. commandline
 120 1. in-makefile
 121 1. environment
 122
 123 Note: This only applies to the Expat library itself, building UTF-16 versions
 124 of xmlwf and the tests is currently not supported.
 125
 126 When using Expat with a project using autoconf for configuration, you
 127 can use the probing macro in `conftools/expat.m4` to determine how to
 128 include Expat.  See the comments at the top of that file for more
 129 information.
 130
 131 A reference manual is available in the file `doc/reference.html` in this
 132 distribution.
 133
 134
 135 The CMake build system is still *experimental* and will replace the primary
 136 build system based on GNU Autotools at some point when it is ready.
 137 For an idea of the available (non-advanced) options for building with CMake:
 138
 139 ```console
 140 # rm -f CMakeCache.txt ; cmake -D_EXPAT_HELP=ON -LH . | grep -B1 ':.*=' | sed 's,^--$,,'
 141 // Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel ...
 142 CMAKE_BUILD_TYPE:STRING=
 143
 144 // Install path prefix, prepended onto install directories.
 145 CMAKE_INSTALL_PREFIX:PATH=/usr/local
 146
 147 // Path to a program.
 148 DOCBOOK_TO_MAN:FILEPATH=/usr/bin/docbook2x-man
 149
 150 // build man page for xmlwf
 151 EXPAT_BUILD_DOCS:BOOL=ON
 152
 153 // build the examples for expat library
 154 EXPAT_BUILD_EXAMPLES:BOOL=ON
 155
 156 // build fuzzers for the expat library
 157 EXPAT_BUILD_FUZZERS:BOOL=OFF
 158
 159 // build the tests for expat library
 160 EXPAT_BUILD_TESTS:BOOL=ON
 161
 162 // build the xmlwf tool for expat library
 163 EXPAT_BUILD_TOOLS:BOOL=ON
 164
 165 // Character type to use (char|ushort|wchar_t) [default=char]
 166 EXPAT_CHAR_TYPE:STRING=char
 167
 168 // install expat files in cmake install target
 169 EXPAT_ENABLE_INSTALL:BOOL=ON
 170
 171 // Use /MT flag (static CRT) when compiling in MSVC
 172 EXPAT_MSVC_STATIC_CRT:BOOL=OFF
 173
 174 // build a shared expat library
 175 EXPAT_SHARED_LIBS:BOOL=ON
 176
 177 // Treat all compiler warnings as errors
 178 EXPAT_WARNINGS_AS_ERRORS:BOOL=OFF
 179
 180 // Make use of getrandom function (ON|OFF|AUTO) [default=AUTO]
 181 EXPAT_WITH_GETRANDOM:STRING=AUTO
 182
 183 // utilize libbsd (for arc4random_buf)
 184 EXPAT_WITH_LIBBSD:BOOL=OFF
 185
 186 // Make use of syscall SYS_getrandom (ON|OFF|AUTO) [default=AUTO]
 187 EXPAT_WITH_SYS_GETRANDOM:STRING=AUTO
 188 ```