102 lines
2.5 KiB
Markdown
102 lines
2.5 KiB
Markdown
# plugin initialization support
|
|
|
|
subsys is a small header-only library providing support for plugin initialization
|
|
|
|
## Features
|
|
|
|
- provide application control of initialization order across c++ libraries
|
|
- circumvents the 'static order initialization fiasco'
|
|
- ensure initialization code runs exactly once if subsystem is linked
|
|
- enforce initialization order constraints
|
|
- defend against static linker stripping essential initialization code
|
|
- designed to work cleanly for libraries integrating into existing executable like python, java runtime, ..
|
|
- initialization state browseable at runtime
|
|
|
|
## Getting Started
|
|
|
|
### build + install `indentlog` dependency
|
|
|
|
see [github/rconybea/indentlog](https://github.com/Rconybea/indentlog)
|
|
|
|
### copy `subsys` repository locally
|
|
```
|
|
$ git clone git@github.com:rconybea/subsys.git
|
|
$ ls -d subsys
|
|
subsys
|
|
```
|
|
|
|
### build + install
|
|
```
|
|
$ cd subsys
|
|
$ mkdir build
|
|
$ cd build
|
|
$ INSTALL_PREFIX=/usr/local # or wherever you prefer
|
|
$ cmake -DCMAKE_MODULE_PATH=${INSTALL_PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ..
|
|
$ make
|
|
$ make install
|
|
```
|
|
|
|
`CMAKE_PREFIX_PATH` should point to prefix where `indentlog` is installed
|
|
|
|
alternatively, if you're a nix user:
|
|
```
|
|
$ git clone git@github.com:rconybea/xo-nix.git
|
|
$ ls -d xo-nix
|
|
xo-nix
|
|
$ cd xo-nix
|
|
$ nix-build -A subsys
|
|
```
|
|
|
|
### build for unit test coverage
|
|
```
|
|
$ cd subsys
|
|
$ mkdir ccov
|
|
$ cd ccov
|
|
$ cmake -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} -DCODE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug ..
|
|
```
|
|
|
|
## Examples
|
|
|
|
### 1
|
|
```
|
|
// initialization code in .hpp for a subsystem foo, that relies on related subsystem bar
|
|
|
|
#include "subsys/Subsystem.hpp"
|
|
|
|
enum S_foo_tag {}; /* tag to represent initialization of subsystem foo */
|
|
|
|
template<>
|
|
struct InitSubsys<S_foo_tag> {
|
|
static void init() {
|
|
// plugin initialization for subsystem foo
|
|
}
|
|
|
|
static InitEvidence require() {
|
|
InitEvidence retval;
|
|
|
|
// demand initialization of dependent subsystem bar,
|
|
// before initialization subsystem foo
|
|
//
|
|
retval ^= InitSubsys<S_bar_tag>::require();
|
|
|
|
// initialization of this subsystem foo
|
|
retval ^= Subsystem::provide<S_foo_tag>("foo", &init);
|
|
|
|
return retval;
|
|
}
|
|
};
|
|
```
|
|
|
|
```
|
|
// in application code that relies on foo (perhaps along with other subsystems),
|
|
// for example in a pybind11 module:
|
|
//
|
|
PYBIND11_MODULE(pyfoo, m) {
|
|
// include foo in initialization set
|
|
InitSubsys<S_foo_tag>::require();
|
|
// ensure foo + dependencies are initialized
|
|
Subsystem::initialize_all();
|
|
|
|
...
|
|
}
|
|
```
|