[][src]Module spirit::fragment

Fragments of configuration.

There are several crates that provide common fragments of configuration to configure some specific functionality. These fragments are described in terms of the Fragment trait.

How to use them

A Fragment can be used directly, usually through create method. The trait has some other methods and associated types, but these are usually used only internally.

The other option is to use fragments through Pipelines. A pipeline describes how the fragment is extracted from the configuration, how instances of resources it describes are cached and created, how to post-process them and how to install or activate them. Depending on the kind of fragment, less or more tweaking may be needed or desirable.

How pipelines work

A Pipeline manages certain fragment of configuration and creates Resources out of it. There are several traits in play there.


Most methods around the mentioned traits take a name: &'static str parameter. This is used by them to enrich log messages, as there might be multiple distinct parts of configuration of the same type.

The name is provided when creating the Pipeline. It needs to be a string literal, but as this should correspond to specific functionality in the program, this should not be very limiting.

TODO: An example

How to create a fragment

First, try to do it manually, without fragments or pipeline ‒ eg. write the code that takes the configuration and creates something out of it and activates it.

Then decide how this should be reloaded when new configuration appears, how it can be reinstalled or if and how it should be cached.

Then you can have a look at available pieces, like ready-made drivers or installers. Sometimes, they come from another trait ‒ eg. the spirit_tokio crate comes with an installer for futures. Usually, you need to implement only the Fragment trait (either in two-stage or single-stage fashion), but sometimes you might need to add some kind of Transformation to tie the part that comes from the configuration with some actual code.

You may also want to implement the Stackable and possibly Comparable traits for the fragment.



A collection of Drivers for use by Fragments.


The home of the Pipeline.



A sequence installer.



A trait describing something that extracts a fragment from configuration and command line options.


A fragment of configuration.


An entity that is able to install a resource.


A trait similar to Stackable, but marking the ability to be optional.


A trait to mark Fragments that can form collections.


A transformation of resources.