Crate lockjaw[][src]

Expand description


Lockjaw is a fully static, compile-time dependency injection framework for Rust inspired by Dagger. It is also what you get when jabbed by a rusty dagger.


  • Compile time dependency resolution
    • Lockjaw makes sure all dependencies are fulfilled at compile time. The code will fail to compile if a dependency is missing, there are duplicated bindings for the same type, or if the dependency graph has cycles. There will be no runtime errors which are harder to detect.
  • Relatively readable diagnostic messages.
    • When a dependency is missing Lockjaw tries to tell you why it is even in the dependency graph, and where the dependency cycle is.
  • Cross-crate injection
    • Lockjaw is designed to be used across crates. Clients are able to inject bindings provided by libraries if they also use Lockjaw.
  • Minimal generated code surface
    • While procedural macros are utilized heavily by Lockjaw, it avoids directly modifying the code the attributes macros are placed on. Only a few generated methods are visible to the user. This is especially important since most Rust IDEs today does not understand the output of procedural macros, a few extra type hints on let expressions is enough to make autocomplete functional.
  • Optional binding, Multibinding, and generated components for plugin systems
    • Lockjaw allows inversion of control between library crates and their user. A library is able to define hooks for clients that depends on the library to inject. This is especially useful to test multiple clients using a library in isolation.

See user guide for more information.


use lockjaw::*;
use std::ops::Add;


struct GreetCounter {
    counter: ::std::cell::RefCell<i32>

// Allow GreetCounter to be created in the dependency graph. These bindings are available anywhere.
impl GreetCounter {
    // Marks a method as the inject constructor. Lockjaw will call this to create the object.
    pub fn new() -> Self {
        Self{counter : std::cell::RefCell::new(0) }

impl GreetCounter{
    pub fn increment(&self) -> i32 {
        let mut m = self.counter.borrow_mut();
        *m = m.add(1);

pub trait Greeter {
    fn greet(&self) -> String;

struct GreeterImpl {
    greet_counter : crate::GreetCounter,
    phrase : String

impl GreeterImpl {
    // Lockjaw will call this with other injectable objects provided.
    pub fn new(greet_counter : GreetCounter, phrase : String) -> Self {
        Self {

impl Greeter for GreeterImpl{
    fn greet(&self) -> String{
        format!("{} {}", self.phrase, self.greet_counter.increment())

// Declare a module so we can do special bindings. These bindings are only available if the
// component installs the module, so different bindings can be used based on the situation.
struct MyModule {}
impl MyModule {
    // When ever someone needs a Greeter, use GreeterImpl as the actual implementation 
    pub fn bind_greeter(_impl : crate::GreeterImpl) -> Cl<dyn Greeter> {}

    // Called when a String is requested
    pub fn provide_string() -> String {

// Components stitch modules and injectables together into a dependency graph, and can create
// objects in the graph. The component installs modules listed in `modules`
#[component(modules: MyModule)]
trait MyComponent {
    // Allows creating a greeter with the component. The created object has the lifetime of the
    // component
    fn greeter(&self) -> Cl<dyn Greeter>;

pub fn main() {
    // Creates the component
    let component = MyComponent::new();
    // Creates a greeter.
    let greeter = component.greeter();
    assert_eq!(greeter.greet(), "helloworld 1");
    // Internal states of the greeter is kept.
    assert_eq!(greeter.greet(), "helloworld 2");
    // A new greeter has a new independent set of injected objects.
    assert_eq!(component.greeter().greet(), "helloworld 1");
// called after the last use of lockjaw to perform validation and code generation

A more complicated game example can be found at

Comparison with Dagger

Lockjaw Aims for feature parity with Dagger and uses very similar APIs. If you have used Dagger before, lockjaw should feel familiar.


This is not an officially supported Google product.

Lockjaw is currently in early development and all APIs are subjected to changes. Some feature are also implemented in a hacky way. Use at your own risk.


Additional nested attributes for items under a #[component]

Additional nested attributes for items under a #[injectable]

Additional nested attributes for items under a #[module]


Resolves the dependency graph and generate component code. Must be called in in the crate root ( or, after any other lockjaw macros, and outside any mod/functions

Prepares lockjaw to be used in the current file. Must be called in every file that uses any lockjaw attribute macros, and before such usage.


Wraps a binding so it can be lazily created.

Creates a binding on demand


“Component Lifetime”. Wrapper around an injection that may be scoped(owned by the component) or free standing(owned by the item injecting it). Deref to access the content.


Represents “any component” which can be used with the scope and install_in metadata.


Function that must be called inside the cargo build script to setup the lockjaw environment.

Attribute Macros

Annotates a struct that contains modules instances to be installed in a component with the builder_modules field. If a module contains fields, it cannot be auto generated and must be explicitly provided to

Annotates a trait that composes the dependency graph and provides items in the graph (An “injector”) .

Annotates a non-public [injectable] struct, a #[module] struct, or a trait used by components so their implementation can be generated.

Generates a #[component] at the root of the binary.

Generates a #[subcomponent] at the root of the binary, similar to #[define_component]

Annotates a trait to provide bindings access to an opaque #[define_component] /#[define_subcomponent] component.

Annotates a struct impl that can be provided to the dependency graph.

Annotates a impl block that defines the bindings.

Annotates a struct to declare a binding qualifier.

Annotates a trait that composes a sub-dependency graph, which has additional bindings/scoped bindings, and can also access bindings from the parent #[component]/ #[subcomponent].