Common C++ classes and routines used by my applications such as argument parser, IO and conversion utilities
Go to file
Martchus cabcc11d3e Incorporate extra target suffix used when targeting MinGW in pkg-config file 2021-01-08 00:43:51 +01:00
application Add Argument::firstValueOr() for conveniently accessing the first value with a fallback 2021-01-01 18:30:17 +01:00
chrono Apply clang-format 2020-10-31 20:31:04 +01:00
cmake Incorporate extra target suffix used when targeting MinGW in pkg-config file 2021-01-08 00:43:51 +01:00
conversion Apply clang-format 2020-11-25 17:53:28 +01:00
doc Document BUILTIN_TRANSLATIONS_OF_QT 2020-11-11 18:08:58 +01:00
feature_detection Support NativeFileStream via Boost.Iostreams 2018-09-30 13:55:30 +02:00
io Mark destructor of NativeFileStream as override 2020-12-18 21:09:35 +01:00
misc Add helper to modify a flag enum 2020-12-14 20:56:37 +01:00
testfiles Allow ArgumentParserTests to pass when working dir present within testfiles dir 2020-06-16 01:03:39 +02:00
tests Add operators '*' and '/' to TimeSpan 2020-10-24 22:10:25 +02:00
.gitignore Fix INI test 2017-06-09 12:15:24 +02:00
CMakeLists.txt Bump patch version 2021-01-07 19:43:51 +01:00
LICENSE Create LICENSE 2015-04-22 19:01:00 +02:00
README.md Document API/ABI stability 2020-11-25 17:53:14 +01:00
coding-style.clang-format Set clang-format standard to Cpp11 2017-05-04 22:43:20 +02:00
global.h Prefix most of the macros in global.h 2019-06-12 20:34:25 +02:00

README.md

C++ utilities

Useful C++ classes and routines such as argument parser, IO and conversion utilities.

Features

The library contains helpers for:

  • parsing command-line arguments and providing Bash completion
    • supports nested arguments
    • supports operations (no -- or - prefix, eg. git status)
    • can check for invalid or uncombinable arguments
    • can print help automatically
    • provides automatic Bash completion for argument names
    • allows customizing Bash completion for argument values
  • dealing with dates and times
  • conversion of primitive data types to byte-buffers and vice versa (litte-endian and big-endian)
  • common string conversions/operations, eg.
    • character set conversions via iconv
    • split, join, find and replace
    • conversion from number to string and vice verca
    • encoding/decoding base-64
    • building string without multiple heap allocations ("string builder")
  • using standard IO streams
    • reading/writing primitive data types of various sizes (little-endian and big-endian)
    • reading/writing terminated strings and size-prefixed strings
    • reading/writing INI files
    • reading bitwise (from a buffer; not using standard IO streams)
    • writing formatted output using ANSI escape sequences
    • instantiating a standard IO stream from a native file descriptor to support UTF-8 encoded file paths under Windows and Android's content:// URLs
  • using SFINAE by providing additional traits, eg. for checking whether a type is iteratable
  • testing with CppUnit
    • finding testfiles and make working copies of testfiles
    • assert standard output
    • various helper
  • building with CMake by providing some modules and templates

Besides, the library provides a few useful algorithms and data structures:

  • min(), max() for any number of arguments
  • digitsum(), factorial(), powerModulo(), inverseModulo(), orderModulo()
  • DamerauLevenshtein distance
  • N-dimensional array

API/ABI stability

The following counts for c++utilities and my other libraries unless stated otherwise:

  • Different major versions are incompatible (API- and ABI-wise). Different major versions can be installed within the same prefix using the CMake variable CONFIGURATION_NAME (see documentation about build variables mentioned below).
  • Minor versions are backwards compatible (API- and ABI-wise) to previous ones within the same major version.
  • Patch versions are interchangeable (API- and ABI-wise) within the same major/minor version.
  • Some functions or classes are experimental. They might be modified in an incompatible way or even removed in the next minor or patch release.

Build instructions

Requirements

Build-only dependencies

  • C++ compiler supporting C++17, tested with
    • clang++ to compile for GNU/Linux and Android
    • g++ to compile for GNU/Linux and Windows
  • CMake (at least 3.3.0)
  • cppunit for unit tests (optional)
  • Doxygen for API documentation (optional)
  • Graphviz for diagrams in the API documentation (optional)
  • clang-format for tidying (optional)
  • llvm-profdata, llvm-cov and cppunit for source-based code coverage analysis (optional)

Runtime dependencies

  • The c++utilities library itself only needs
    • C++ standard library supporting C++17, tested with
      • libstdc++ under GNU/Linux and Windows
      • libc++ under GNU/Linux and Android
    • glibc with iconv support or standalone iconv library
    • libstdc++ or Boost.Iostreams for NativeFileStream (optional)
  • For dependencies of my other projects check the README.md of these projects.

How to build

Example using make:

cd "path/to/build/directory"
cmake -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX="/final/install/location" \
      "path/to/projectdirectory"
make tidy # format source files (optional, must be enabled via CLANG_FORMAT_ENABLED)
make # build the binaries
make check # build and run tests (optional)
make coverage # build and run tests measuring test coverage (optional, must be enabled via CLANG_SOURCE_BASED_COVERAGE_ENABLED)
make apidoc # build API documentation (optional)
make DESTDIR="/temporary/install/location" install # install binaries, headers and additional files

General notes

  • The make option -j can be used for concurrent compilation.
  • LIB_SUFFIX, LIB_SUFFIX_32 and LIB_SUFFIX_64 can be set to specify a suffix for the library directory, eg. lib64 or lib32. The 32/64 variants are only used when building for 32/64-bit architecture.
  • By default the build system will build static libs. To build shared libraries instead, set BUILD_SHARED_LIBS=ON.
  • By default the build system will prefer linking against shared libraries. To force linking against static libraries set STATIC_LINKAGE=ON. However, this will only affect applications. To force linking statically when building shared libraries set STATIC_LIBRARY_LINKAGE=ON.
  • If thread local storage is not supported by your compiler/platform (might be the case on MacOS), you can disable making use of it via ENABLE_THREAD_LOCAL=OFF.
  • To disable use of std::filesystem, set USE_STANDARD_FILESYSTEM=OFF. This is required when building for MacOS and Android at the time of writing this documentation. Note that the Bash completion will not be able to suggest files and directories with USE_STANDARD_FILESYSTEM=OFF.
  • For more detailed documentation, see the documentation about build variables (in directory doc and in Doxygen version accessible via "Related Pages").
  • The repository PKGBUILDs contains build scripts for GNU/Linux, Android, Windows and MacOS X in form of Arch Linux packages. These scripts can be used as an example also when building under/for other platforms.

Building for Windows

  • Building for Windows with GCC as cross compiler and mingw-w64 can be simplified by using a small Cmake wrapper and a custom toolchain file:

    ${_arch}-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="/final/install/location" "path/to/source/directory"
    make DESTDIR="/temporary/install/location" install-mingw-w64-strip
    
  • To create the *.ico file for the application icon ffmpeg/avconv is required.

  • The target install-mingw-w64-strip can be used as in the example above to only install files suitable for creating a cross-compiler package and additionally strip the binaries.

Building for MacOS X

Development builds

During development I find it useful to build all required projects (for instace c++utilities, qtutilities, tagparser and tageditor) as one big project.

This can be easily achieved by using CMake's add_subdirectory() function. For project files see the repository subdirs. For an example, see build instructions for Syncthing Tray.

For a debug build, use -DCMAKE_BUILD_TYPE=Debug.

Arch Linux package

The repository PKGBUILDs contains files for building Arch Linux packages of the latest release and the Git master.

PKGBUILDs to cross compile for Android, Windows (using mingw-w64) and for MacOS X (using osxcross) are included as well.

RPM packages for openSUSE and Fedora

RPM *.spec files can be found at openSUSE Build Servide. Packages are available for several architectures.

There is also a sub project containing the builds from the Git master branch.

Gentoo

Packages are provided by perfect7gentleman; checkout his repository.