Kibble

A utility library to jumpstart my projects.

Report Bug · Request Feature

Table of contents

• About the project
  • Kibble
  • Feature list
• Getting started
  • Prerequisites
  • Installation
  • Examples and tests
  • Documentation
  • Integration
• Changelog
• How to help
• License
• Contact

This C++ library is a collection of utility classes, systems, data structures, algorithms and tools I happen to need quite often in my game development projects. Most of the code is original, some parts stemmed from other open source projects or blog articles I read.
There are numerous examples on how to use it, and most of the code is unit tested.

At the moment, the code has only been tested under GNU/Linux, and although most of it should compile and work as-is under other operating systems, some OS-dependent code was only implemented for GNU/Linux.
This library is under heavy development, and the API is subject to change. Use at your own risk!

• Logger
  • Channel-based system with runtime verbosity levels
  • Extendable sink system (out-of-the-box sinks: console, file and TCP)
  • Extendable formatters
  • Extendable policy system for filtering / transforming log data
  • Output is formatted, color coded and easy to follow
  • Formatting syntax inherited from fmtlib
  • Synchronous and asynchronous operation (both thread-safe)
  • Optional stack trace on error
• Program argument parser
  • Automatically generate usage string and version
  • Modern interface
• File system
  • Handles regular files as well as files inside a resource pack
  • Directory / pack aliasing and universal paths
  • Can create and maintain a config directory located where the OS expects it
  • The kpak utility can pack a directory easily, it can also be done programmatically
  • Safe file saving utility to avoid overwriting files with bad data
  • MD5 checksum computation
• Serialization
  • Stream serialization helpers
  • Most std containers are supported
  • Memory streams
  • Support for versioning and backward compatibility
• Custom assertion
  • Prints a stack trace and can debug break
  • Formatted assertion message strings
• Profiling utility
  • Easily profile execution time
  • Produce a Chrome Tracing json output
• Event system
  • Publish / subscribe model with central message broker (event bus)
  • Deferred event handling with event queues
  • Events can also be fired instantly
  • Abstract delegates allow subscription of free functions as well as member functions
  • Events need not inherit from a base class and can be any type
  • Subscriber priority system to decide which subscribers should respond first
  • Events can be consumed
  • Event tracking / logging
• Job system
  • Launch multiple worker threads and execute tasks asynchronously
  • Lock-free
  • Work stealing scheme for load balancing
  • Dependency graphs
  • Barrier synchronization
  • Worker affinity
  • Recurring tasks
  • Task monitoring and profiling (using the profiling utility)
• Undo engine
  • Qt-like API
  • Push custom commands in a stack-like object that handles the undo / redo logic
  • Manage multiple stacks in an undo group
  • Command merging and compression
  • Clean state
  • Can be wired to an event system thanks to various callbacks
• Random number generation
  • Fast XOR shift engine
  • Coherent noise generation (simplex, octave)
• UUIDv4 generation
  • adapted from: https://github.com/crashoz/uuid_v4
• Multiple math utilities
  • Bezier and cubic Hermite spline interpolation (arc-length parameterized)
  • Catenary curve (arc-length parameterized)
  • Constexpr math function collection
  • Easing functions (a lot of them)
  • Separable Gaussian convolution kernel builder
  • Numerical methods (Newton-Raphson, Simpson integration)
  • Statistics class (useful for profiling)
  • Colors: multiple representations (RGBA, HSLA, CIELab, 32b ARGB) and conversion algorithms, multiple color difference algorithms...
  • Morton encoding / decoding
• Mathematical optimization and graph algorithms
  • Generic stochastic descent optimizer with FDSA / SPSA support
  • Generic A* search implementation
• Constexpr string hashes and intern string system
  • User defined literal allows to write a full string in the source that will be hashed at compile-time
  • The internstring utility can parse sources and write all string hashes to a text file, then it's quite simple to resolve a hash at runtime by reading this file into a map
• Multiple string utilities to avoid boilerplate
  • trimming, stripping, case transform, text centering, tokenization, regex replace
  • Base64 encoding / decoding
• Compile-time type information
  • Drop-in replacement for some features of the CTTI lib
  • Compile-time type name and type ID (as a name hash)
• Memory arena system
  • Fast custom allocators (linear, pool, atomic pool, TLSF)
  • Policy-based memory sanitization
• Basic TCP socket abstraction
  • Simple Berkeley socket wrapper using the Stream / Acceptor / Connector model
• A precision chronometer with a simple interface
• Multiple useful data structures, including sparse sets and sparse pools implementations

(back to top)

To get a local copy up and running follow these steps.

• A compiler with support for C++20 (tested with clang 12.0.0)
• CMake, minimum version 3.19

1. Clone the repo with its submodules

   git clone --recurse-submodules https://github.com/ndoxx/kibble.git

2. Build the lib

    mkdir build
    cd build
    cmake ..
    make kibble

3. Install

    sudo make install

Some of the examples may require additional dependencies like glm to compile.
To build the examples and tests, make sure you are in the build directory.

• You can build every example from the source/examples directory individually with

   make ex_<example_name>

  Replace <example_name> by the file name stem.
• Or you can build all of them at once with

   make examples

• Similarly, to build the unit tests:

   make tests

(back to top)

The source files are documented with Doxygen, and higher-level documentation is on its way. To build the docs, go to the build directory and do:

  make docs

Kibble can be setup as a subproject easily with CMake and git. Add Kibble as a submodule, and in the relevant CMakeLists.txt configure the project with set() directives, then simply call add_subdirectory(). Kibble's CMake script will detect its use as a subproject, disable the tests, examples and install targets, and let the host project handle the configuration of the output directories. For example:

set(KB_AREA_MEMORY_INITIALIZATION ON CACHE BOOL "" FORCE)
set(KB_JOB_SYSTEM_PROFILING ON CACHE BOOL "" FORCE)
add_subdirectory("${CMAKE_SOURCE_DIR}/source/vendor/kibble" "external/kibble")

set_target_properties(kibble
    PROPERTIES
    POSITION_INDEPENDENT_CODE ON
)

Then link your executable / library against the kibble target. That's it.

During a system installation, Kibble also generates CMake config files so it can be found by CMake. Then all you need to do is this:

find_package(kibble 1.2.2 REQUIRED)

See CHANGELOG.md.

If you have any idea on how to make this project better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Any contribution will be greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/FeatureName)
3. Commit your Changes (git commit -m 'Add this awesome feature')
4. Push to the Branch (git push origin feature/FeatureName)
5. Open a Pull Request

If this project was of any help to you, don't hesitate to give it a star!

(back to top)

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Ndoxx - [email protected]

Project Link: https://github.com/ndoxx/kibble

(back to top)