kangaru 🦘

Kangaru is an inversion of control container for C++11, C++14 and later. It provides many features to automate dependency injection and reduce the amount of wiring boilerplate in your code. We are achiving that by exposing in code configuration for autowiring, constructor and function parameters injection. We aim to keep the simplest interface possible and keep boilerplate to a minimum. On top of that, we don't want to be intrusive into user/library code.

Kangaru is a header only library because of it's extensive use of templates. The name kangaru comes from the container's feature to inject itself into a service as a dependency, and because kangaroos are awesome.

Documentation and tutorial is in the wiki and the doc folder!

Looking for the latest stable version? Check out our release page.

Overview

Here's a quick demo to show usage of this library. This is some basic usage of the library with two user classes.

#include <kangaru/kangaru.hpp>
#include <cassert>

// We define some normal classes with dependencies between them
struct Camera {};

struct Scene {
    Camera& camera;
};

// The following is the configuration of our user classes above.
// The structure and dependency graph is defined by these configs.

// Camera is a single service so the service has a shared instance.
// It will be injected and returned as a reference.
struct CameraService : kgr::single_service<Camera> {};

// Scene is not single, so the container return scenes by value.
// Also, we depends on a camera to be constructed.
struct SceneService : kgr::service<Scene, kgr::dependency<CameraService>> {};

int main()
{
    kgr::container container;
    
    // The service function return instances of the normal classes.
    Scene scene = container.service<SceneService>();
    Camera& camera = container.service<CameraService>();
    
    assert(&scene.camera == &camera); // passes, both cameras are the same instance.
}

Try this example online to see how it runs.

Features

• Non intrusive, no existing classes need modification
• You tell the container how to construct your types, store and inject them
• Injection by setters
• Autowiring by class constructors
• Function parameter injection
• Clean and simple API for simple cases, flexible enough for complex cases
• Low runtime overhead
• Header only library
• Clean diagnostics at compile-time

Installation

To make kangaru available on your machine, you must clone the repository and create a build directory:

$ git clone https://github.com/gracicot/kangaru.git && cd kangaru
$ mkdir build && cd build

Then use cmake to generate the makefile and export the package informations:

$ cmake ..

That's it! Link it to your project using cmake and you can already include and code!

Optionally, you can also install kangaru on your system:

$ sudo make install # optional step

Adding Include Path

You must use the find_package function:

find_package(kangaru REQUIRED)

And then add the include dirs to your target:

target_link_libraries(<YOUR TARGET> PUBLIC kangaru)

Then you can include the library as follow:

#include <kangaru/kangaru.hpp>

If you skip the installation, simply tell CMake where to find kangaru:

# in your project build directory
$ cmake .. -DCMAKE_PREFIX_PATH=../../path/to/kangaru/build

Compiler Requirement

Kangaru is tested by our continuous integration with all major compiler versions. The minimum required versions are:

• MSVC: 2015 update 3 or better
• GCC: 4.8.5 or better
• Clang: 3.6 or better
• AppleClang: 7.0 or better

What's Next

There is some feature I would like to see become real. Here's a list of those, feel free to contribute!

• Tests for compile-time errors
• Better messages for compile-time errors (ongoing)
• Service sources, more detail here: #41
• Even better performance (ongoing)
• Expose a zero-overhead interface for cases it can apply
• Move service definitions to service map.

Got suggestions or questions? Discovered a bug? Please open an issue and we'll gladly respond!

Contributing

To contribute, simply open a pull request or an issue and we'll discuss together about how to make this library even more awesome! See our complete contribution guideline for more details.

Want to help? Pick an issue on our issue tracker!

Found an issue? Have an idea to make this library better? Please submit an issue and we will respond within a few days, and commit to address the needs.

Running Tests

Tests are enabled using the cmake option -DKANGARU_TEST=ON. Enabling this will make our CMake scripts to try finding the Catch2 library. We also contain a submodule for this library in our git repository in case you don't have it available in a prefix directory.

Using this option adds the the test target.

To enable tests specifically designed arount C++14 and C++17 features, there's the -DKANGARU_TEST_CXX14=ON and the -DKANGARU_TEST_CXX17=ON options.

Who's Using Kangaru

Here's a list of projets making use of kangaru

• Our team's game engine
• The people I helped integrating this library into their projects
• Surely more!

Using kangaru?

Let me know of your projects using kangaru! I'll be glad to fill the list above with your project's name.

Acknowledgements

A big thanks to Louis-Alexandre Vallières-Lavoie for reviewing and proposing various improvement to our documentation.