127 lines
3.6 KiB
Markdown
127 lines
3.6 KiB
Markdown
# libowfat
|
|
|
|
This tree keeps the original GNUmakefile build untouched and adds an optional
|
|
CMake build for projects that want to consume libowfat directly with CMake.
|
|
|
|
## CMake build
|
|
|
|
Out-of-tree builds are supported:
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
By default the CMake build produces the normal shared library name:
|
|
|
|
```text
|
|
libowfat.so
|
|
```
|
|
|
|
A prefix can be added to the library basename. For example, this builds
|
|
`libnwowfat.so` and, when static builds are enabled, `libnwowfat.a`.
|
|
The same prefix is also applied to the installed and build-tree include
|
|
directory name, so headers are exposed below `nwlibowfat/` instead of
|
|
`libowfat/`:
|
|
|
|
```sh
|
|
cmake -S . -B build-nw \
|
|
-DLIBOWFAT_LIBRARY_PREFIX=nw \
|
|
-DLIBOWFAT_BUILD_STATIC=ON \
|
|
-DLIBOWFAT_BUILD_SHARED=ON
|
|
cmake --build build-nw
|
|
```
|
|
|
|
The library version is read from the first line of `CHANGES`.
|
|
|
|
## Installation
|
|
|
|
CMake installation uses `GNUInstallDirs`, so the library directory follows the
|
|
platform and the configured prefix, for example `lib` or `lib64`:
|
|
|
|
```sh
|
|
cmake --install build --prefix /usr
|
|
```
|
|
|
|
Headers are installed under:
|
|
|
|
```text
|
|
${prefix}/include/libowfat
|
|
```
|
|
|
|
With `-DLIBOWFAT_LIBRARY_PREFIX=nw`, headers are installed under:
|
|
|
|
```text
|
|
${prefix}/include/nwlibowfat
|
|
```
|
|
|
|
Only the directory name is prefixed; header file names are unchanged.
|
|
|
|
Generated compatibility headers such as `haveip6.h`, `havesendfile.h`,
|
|
`haveaccept4.h`, `havesl.h`, `iopause.h`, `select.h`, and `entities.h` are
|
|
installed there too. This lets consumers include either `libowfat/foo.h` or,
|
|
for legacy code that relies on the target include path, plain `foo.h`.
|
|
|
|
## Using from another CMake project
|
|
|
|
As an installed package:
|
|
|
|
```cmake
|
|
find_package(libowfat CONFIG REQUIRED)
|
|
target_link_libraries(myapp PRIVATE libowfat::libowfat)
|
|
```
|
|
|
|
As a subdirectory or submodule:
|
|
|
|
```cmake
|
|
add_subdirectory(extern/libowfat)
|
|
target_link_libraries(myapp PRIVATE libowfat::libowfat)
|
|
```
|
|
|
|
The exported build-tree target includes `${binary_dir}/include` and the
|
|
matching public include directory, for example `${binary_dir}/include/libowfat`
|
|
or `${binary_dir}/include/nwlibowfat`. Generated `have*.h` headers are copied
|
|
there during configure, so a parent project can include `libowfat/foo.h` or
|
|
`nwlibowfat/foo.h` directly from the build tree without copying files into the
|
|
source tree.
|
|
|
|
## Tests
|
|
|
|
When libowfat is built as the top-level CMake project, `BUILD_TESTING=ON`
|
|
registers `t.c` as a smoke test and builds the programs under `test/`:
|
|
|
|
```sh
|
|
cmake -S . -B build -DBUILD_TESTING=ON
|
|
cmake --build build
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
Only the non-interactive tests are registered with CTest. Network/server/demo
|
|
programs and tests that need command-line input are compiled but not run by
|
|
CTest.
|
|
|
|
When libowfat is used through `add_subdirectory()`, tests are off by default so
|
|
that a parent project does not unexpectedly build the whole test tree. They can
|
|
be enabled explicitly:
|
|
|
|
```sh
|
|
-DLIBOWFAT_BUILD_TEST_PROGRAMS=ON
|
|
-DLIBOWFAT_RUN_SELF_TESTS=ON
|
|
```
|
|
|
|
### Prefixed CMake header exports
|
|
|
|
When `LIBOWFAT_LIBRARY_PREFIX` is set, CMake exports public headers below a
|
|
matching include directory, for example `nwlibowfat`. The original sources and
|
|
internal build include tree still keep the upstream `libowfat` layout, but the
|
|
public build/install header copies are rewritten so their nested includes also
|
|
use the selected directory name. For example:
|
|
|
|
```c
|
|
#include <nwlibowfat/buffer.h>
|
|
```
|
|
|
|
will include other libowfat headers through `nwlibowfat/...`, avoiding conflicts
|
|
with a system-installed `libowfat` header set.
|