search

bitweeder / lucenaBAL

C++ utility library providing build platform, compiler, and Standard Library feature detection
https://bitweeder.github.io/lucenaBAL
Other
4 stars 1 forks source link
c-plus-plus cpp cpp-library cpp17 cpp20 cpp23 cpp26 cxx cxx-library cxx17 cxx20 cxx23 cxx26 feature-detection linux macos windows

readme

Actions Status

Lucena Build Abstraction Library

The purpose of the Lucena Build Abstraction Library (lucenaBAL) is to provide tools to smooth over the differences between build environments when working with C++11 and later Standards. It’s a foundational tool that allows code built upon it to remain agnostic to compilers, C++ Standard Library variants, and aspects of the runtime. Note that lucenaBAL is not a build system, but rather a C++ header library with a collection of build system support scripts.

Motivating Example

Imagine that you are working on a project that would benefit from using the C++17 parallelized algorithm for std::sort, and you would like to use it conditionally based on availability.

Enter lucenaBAL:

#include <lucenaBAL/lucenaBAL.hpp>

#include <algorithm>
#include <vector>

#if LBAL_LIBCPP17_STANDARDIZATION_OF_PARALLELISM_TS
    #include <execution>
#endif

/**
    Sort the supplied vector in place and return a reference to it,
    using a parallelized sort if available.
*/
inline std::vector<int> & sort_vector (std::vector<int> & io_vector)
{
    #if LBAL_LIBCPP17_STANDARDIZATION_OF_PARALLELISM_TS
        std::sort (std::execution::par, io_vector.begin(), io_vector.end());
    #else
        std::sort (io_vector.begin(), io_vector.end());
    #endif

    return io_vector;
}

Getting Started

CMake scripts are provided which will install the library itself, build and run test applications, and generate documentation. We require at least CMake 3.15, so that will need to be installed first.

More detailed instructions are provided below, but for a quick start, simply clone the repository, open up a terminal window, change to the local repo directory, and execute the following:

Under macOS or Linux (or other UNIX derivatives):

> mkdir build
> cd build
> cmake ..
> cmake --build . --config Release
> sudo make install

Under Windows:

> mkdir build
> cd build
> cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
> cmake --build . --config Release
> cmake --build . --target install

This will:

  1. Generate headers, test binaries, and docs in the build directory.
  2. Copy the headers to /usr/local/include/lucenaBAL (or the equivalent specified directory).
  3. Copy any support files to /usr/local/share/lucenaBAL (or the equivalent specified directory).

(Note that tests and docs will remain in the build directory.)

Since lucenaBAL is a header-only library, it is not necessary to link to it; simply #include <lucenaBAL/lucenaBAL.hpp> where you need feature tests once the headers are installed. Usage information is available in the online docs, as well as in the headers themselves (primarily in <lucenaBAL/lbalFeatureSetup.hpp>).

Prerequisites

lucenaBAL requires compiler support for C++11 or later. It has been tested with gcc 6 thru 14.2, Microsoft Visual Studio 2015 Update 3 thru MSVS 2022 17.11.4, Xcode 9 thru 16.0, and llvm/clang 6 thru 20. All testing thus far has been with the compilers’ bundled Standard Library implementations, although lucenaBAL should support mixing them.

Building, Installing, and Testing

The project uses CMake as its primary build system. Originally, hand-built project files for a number of different IDEs were used, but they were dependent on a particular folder hierarchy and also didn’t lend themselves very well to automation.

lucenaBAL is a header-only library. The basic build instructions are provided above under Getting Started. We give two different methods since, by default, macOS and Linux installs are to /usr/local, which requires sudo or root access, while Windows uses a different model. Ignoring these differences, we have the following, with line numbers added:

1 > mkdir build
2 > cd build
3 > cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
4 > cmake --build . --config Release
5 > cmake --build . --target install

Line 3 can be changed to:

3 > cmake -G "<generator>" -DCMAKE_INSTALL_PREFIX=/path/to/install ..

<generator> should be replaced with one of the supported generator strings. The -DCMAKE_INSTALL_PREFIX switch could be left out if the default installation directory is acceptable.

In line 4, the config may be chosen from the usual set with the usual meanings for CMake: Debug, Release, RelWithDebInfo and MinSizeRel. Alternatively, you may simply call make.

Line 5 can be replaced by make install (or sudo make install). Tests are generated by default and left in <build>/tests. They can be automatically run by changing line 5 to:

5 > cmake --build . --target tests

Tests can be scripted in the usual way for CMake and CTest, for example in order to only install the library if testing succeeds.

Docs can also be generated, if desired, and are left in <build>/docs.

Planning

Tokens deprecated prior to the official lucenaBAL 2.0 release—in particular, placeholder tokens superseded by formalized C++20/C++23 variants—will be removed as part of the eventual lucenaBAL 3.0 release, but will remain available until then.

As always, prefer to use the non-deprecated version of a token, especially when starting a new project.

To-Do

Roughly in order of precedence

A more formal action items list will be maintained on our GitHub issues page.

Support

lucenaBAL aggressively tracks the latest tools and standards, but maintaining support for older tools in new releases is unlikely to happen. The cold reality is that we do not have the bandwidth to pay the interest on anyone else’s technical debt. If an older release does what you need, use it. If you find a bug in any release, we greatly appreciate patches, though we strongly encourage you to at least open an issue even if you can’t submit a pull request. Feature requests will be considered, but requests to increase our maintenance surface are unlikely to be carried out.

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests to us.

Please note that this project is released with a Contributor Code of Conduct, documented in CODE_OF_CONDUCT.md By participating in this project you agree to abide by its terms.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

License

This project is licensed under the University of Illinois/NCSA Open Source License - see the LICENSE.md file for details. Some portions of the project are governed by other compatible licenses included in that same file, notably:

Acknowledgments