bosce

Bosce, or boost::statechart extractor, is a command line tool to extract information about boost::statecharts from an arbitrary binary with debug symbols and transform it to a user-friendly form, e.g. UML diagrams.

It relies on objdump to extract information from binaries and is primarily intended to be used in a Linux environment.

Demo

First, we need a binary with debug symbols to work on.

$ g++ -g demo.cpp -o demo

Then, we get a list of state machine in this binary.

$ bosce demo -l
Available state-machines:
    StopWatch

Now, we generate a StopWatch state-machine representation in a PlantUML format.

$ bosce demo -s StopWatch > uml.pu

Finally, we use PlantUML to generate a PNG file and open it.

$ plantuml uml.pu
$ xdg-open uml.png

Usage

bosce <input files> [options]

Input Files

Bosce accepts one or more input files:

Binaries with debug symbols (by default), or
Text files with objdump output (if option -O is used).

All information extracted from input files is merged into a single model. This is useful, e.g. if a state machine is split between a shared library and a binary using this library.

Options

-h, --help: Show a help message
-O, --objdump: Input files is an objdump instead of binary
-X, --extract: Only extract an `objdump out of an input binary
-S, --strip: Strip an objdump to contain only relevant data
-l, --list: List all state-machine names
-t <name>, --highlight <name>: Highlight given names in the generated output
-s <name>, --stm <name>: Generate an output for a specific state-machine
-g <gen>, --generator <gen>: Specify a generator (plantuml, stmlist, text, yaml)

Build Instructions

Bosce depends on boost::program_options and boost::process and requires a C++17 compatible compiler.

First, clone the repository.

$ git clone https://github.com/kanje/bosce.git
Cloning into 'bosce'...
remote: Enumerating objects: 48, done.
remote: Total 48 (delta 0), reused 0 (delta 0), pack-reused 48
Unpacking objects: 100% (48/48), done.

Then, create a build directory and run cmake to configure the project.

$ mkdir bosce-build
$ cd bosce-build
$ cmake -DCMAKE_BUILD_TYPE=Release ../bosce
-- The CXX compiler identification is GNU 9.2.1
...
-- Configuring done
-- Generating done
-- Build files have been written to: /.../bosce-build

Finally, build bosce.

$ make -j10
Scanning dependencies of target bosce
[ 12%] Building CXX object CMakeFiles/bosce.dir/src/ScModel.cpp.o
...
[100%] Built target bosce

Optionally, build a demo statechart binary to experiment on.

$ make demo
Scanning dependencies of target demo
[100%] Building a demo statechert binary
[100%] Built target demo

Reporting Issues

If you have encountered a problem and want to report it, please do not forget to provide an objdump which shows the problem. If the objdump is too big or contains proprietary code, it can be stripped.

$ bosce -SO original.objdump > stripped.objdump
$ bosce -SX binary > stripped.objdump

The stripped objdump contains only information related to boost::statecharts. Note, this includes state-machine, state and event names as well as assembly for react() methods.

kanje / bosce