diff options
Diffstat (limited to 'contrib/expat/README.md')
| -rw-r--r-- | contrib/expat/README.md | 75 |
1 files changed, 58 insertions, 17 deletions
diff --git a/contrib/expat/README.md b/contrib/expat/README.md index 43c4f4f3dbb3..77c6bf27d307 100644 --- a/contrib/expat/README.md +++ b/contrib/expat/README.md @@ -3,9 +3,16 @@ [](https://repology.org/metapackage/expat/versions) [](https://sourceforge.net/projects/expat/files/) [](https://github.com/libexpat/libexpat/releases) +[](https://www.bestpractices.dev/projects/10205) +> [!CAUTION] +> +> Expat is **understaffed** and without funding. +> There is a [call for help with details](https://github.com/libexpat/libexpat/blob/master/expat/Changes) +> at the top of the `Changes` file. -# Expat, Release 2.6.0 + +# Expat, Release 2.7.1 This is Expat, a C99 library for parsing [XML 1.0 Fourth Edition](https://www.w3.org/TR/2006/REC-xml-20060816/), started by @@ -16,11 +23,11 @@ are called when the parser discovers the associated structures in the document being parsed. A start tag is an example of the kind of structures for which you may register handlers. -Expat supports the following compilers: +Expat supports the following C99 compilers: -- GNU GCC >=4.5 +- GNU GCC >=4.5 (for use from C) or GNU GCC >=4.8.1 (for use from C++) - LLVM Clang >=3.5 -- Microsoft Visual Studio >=15.0/2017 (rolling `${today} minus 5 years`) +- Microsoft Visual Studio >=16.0/2019 (rolling `${today} minus 5 years`) Windows users can use the [`expat-win32bin-*.*.*.{exe,zip}` download](https://github.com/libexpat/libexpat/releases), @@ -37,16 +44,16 @@ This license is the same as the MIT/X Consortium license. ## Using libexpat in your CMake-Based Project -There are two ways of using libexpat with CMake: +There are three documented ways of using libexpat with CMake: -### a) Module Mode +### a) `find_package` with Module Mode This approach leverages CMake's own [module `FindEXPAT`](https://cmake.org/cmake/help/latest/module/FindEXPAT.html). Notice the *uppercase* `EXPAT` in the following example: ```cmake -cmake_minimum_required(VERSION 3.0) # or 3.10, see below +cmake_minimum_required(VERSION 3.10) project(hello VERSION 1.0.0) @@ -56,15 +63,10 @@ add_executable(hello hello.c ) -# a) for CMake >=3.10 (see CMake's FindEXPAT docs) target_link_libraries(hello PUBLIC EXPAT::EXPAT) - -# b) for CMake >=3.0 -target_include_directories(hello PRIVATE ${EXPAT_INCLUDE_DIRS}) -target_link_libraries(hello PUBLIC ${EXPAT_LIBRARIES}) ``` -### b) Config Mode +### b) `find_package` with Config Mode This approach requires files from… @@ -79,7 +81,7 @@ or Notice the *lowercase* `expat` in the following example: ```cmake -cmake_minimum_required(VERSION 3.0) +cmake_minimum_required(VERSION 3.10) project(hello VERSION 1.0.0) @@ -92,6 +94,45 @@ add_executable(hello target_link_libraries(hello PUBLIC expat::expat) ``` +### c) The `FetchContent` module + +This approach — as demonstrated below — requires CMake >=3.18 for both the +[`FetchContent` module](https://cmake.org/cmake/help/latest/module/FetchContent.html) +and its support for the `SOURCE_SUBDIR` option to be available. + +Please note that: +- Use of the `FetchContent` module with *non-release* SHA1s or `master` + of libexpat is neither advised nor considered officially supported. +- Pinning to a specific commit is great for robust CI. +- Pinning to a specific commit needs updating every time there is a new + release of libexpat — either manually or through automation —, + to not miss out on libexpat security updates. + +For an example that pulls in libexpat via Git: + +```cmake +cmake_minimum_required(VERSION 3.18) + +include(FetchContent) + +project(hello VERSION 1.0.0) + +FetchContent_Declare( + expat + GIT_REPOSITORY https://github.com/libexpat/libexpat/ + GIT_TAG 000000000_GIT_COMMIT_SHA1_HERE_000000000 # i.e. Git tag R_0_Y_Z + SOURCE_SUBDIR expat/ +) + +FetchContent_MakeAvailable(expat) + +add_executable(hello + hello.c +) + +target_link_libraries(hello PUBLIC expat) +``` + ## Building from a Git Clone @@ -158,10 +199,10 @@ support this mode of compilation (yet): 1. Mass-patch `Makefile.am` files to use `libexpatw.la` for a library name: <br/> - `find -name Makefile.am -exec sed + `find . -name Makefile.am -exec sed -e 's,libexpat\.la,libexpatw.la,' -e 's,libexpat_la,libexpatw_la,' - -i {} +` + -i.bak {} +` 1. Run `automake` to re-write `Makefile.in` files:<br/> `automake` @@ -250,7 +291,7 @@ EXPAT_ENABLE_INSTALL:BOOL=ON // Use /MT flag (static CRT) when compiling in MSVC EXPAT_MSVC_STATIC_CRT:BOOL=OFF -// Build fuzzers via ossfuzz for the expat library +// Build fuzzers via OSS-Fuzz for the expat library EXPAT_OSSFUZZ_BUILD:BOOL=OFF // Build a shared expat library |