steve-downey/example

Example Beman project

example

About

example is an example Beman library.

example is useful for nothing, though it might contain value as an experiment in modern and minimal C++ project structure.

Building

Dependencies

This project is mainly tested on Ubuntu 22.04, but it should be as portable as CMake is.

This project has zero C or C++ depenendencies.

It does require two tools as build-time dependencies:

• cmake
• ninja, make, or another CMake-supported build system
  • CMake defaults to "Unix Makefiles" on POSIX systems

Instructions

Basic Build

This project strives to be as normal and simple a CMake project as possible. This build workflow in particular will work, producing a static example library, ready to package:

cmake -B /some/build/dir -S .
cmake --build /some/build/dir
ctest --test-dir /some/build/dir \
  --output-junit build/xunit/results.xml
DESTDIR=/some/staging/dir cmake --install /some/build/dir --component libexample-dev --prefix /opt/example

If all of those steps complete successfully, you should see the library installed in your staging directory.

An example command:

find /some/staging/dir -type f

You will see files like so:

/some/staging/dir
└── opt
    └── example
        ├── include
        │   └── example.hxx
        └── lib
            ├── cmake
            │   └── example
            │       ├── example-noconfig.cmake
            │       └── example.cmake
            └── libexample.a

Manipulating Warnings

To build this project with warnings enabled, simply use CMAKE_CXX_FLAGS as documented in upstream CMake documentation:

cmake -B /some/build/dir -S . -DCMAKE_CXX_FLAGS='-Werror=all -Wno-error=deprecated-declarations'

Otherwise follow the Basic Build workflow as described above.

Sanitizers and Coverage Analysis

To build this project with sanitizers enabled, simply use CMAKE_CXX_FLAGS as documented in upstream CMake documentation. For instance, to enable an address sanitizer build:

cmake -B /some/build/dir -S . -DCMAKE_CXX_FLAGS='-sanitize=address'

Similarly, but enabling coverage analysis:

cmake -B /some/build/dir -S . -DCMAKE_CXX_FLAGS='--coverage'

Otherwise follow the Basic Build workflow as described above.

clang-tidy

To enable clang-tidy on this project, simply use CMAKE_CXX_CLANG_TIDY as documented in upstream CMake documentation. For instance, to enable only the cppcoreguidelines checks:

cmake -B /some/build/dir -S . -DCMAKE_CXX_CLANG_TIDY="clang-tidy;-checks=-*,cppcoreguidelines-*"

Otherwise follow the Basic Build workflow as described above.

Usage

From C++

If you really want to use example from your project (why???), you can include example.hxx from your C++ source files

#include <example.hxx>

example supports C++98, C++03, C++11, C++14, C++17, C++20, and C++23. It has no known issues with C++26 or C++29, though there are no compilation toolchains available to test against in those build modes.

Note that example is incidentally compatible with most C dialects, but that behavior is not regularly tested and should be considered unsupported.

From CMake

For consumers using CMake, you will need to use the example CMake module to define the example CMake target:

find_package(example REQUIRED)

You will also need to add example::example to the link libraries of any libraries or executables that include example.hxx in their source or header file.

target_link_libraries(yourlib PUBLIC example::example)

From Other Build Systems

Build systems that support pkg-config by providing a example.pc file. Build systems that support interoperation via pkg-config should be able to detect example for you automatically.

Contributing

Please do! Issues and pull requests are appreciated.

Note that adding more C++ code will be out of scope for this project. Changes that further improve or simplify this project given that goal are appreciated. Enhancements to better support packaging ecosystems would also make sense.