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.
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
$ 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
bosce <input files> [options]
Bosce accepts one or more input files:
- Binaries with debug symbols (by default), or
- Text files with
objdumpoutput (if option
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.
--help: Show a help message
--objdump: Input files is an objdump instead of binary
--extract: Only extract an `objdump out of an input binary
--strip: Strip an objdump to contain only relevant data
--list: List all state-machine names
--highlight <name>: Highlight given names in the generated output
--stm <name>: Generate an output for a specific state-machine
--generator <gen>: Specify a generator (plantuml, stmlist, text, yaml)
Bosce depends on
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
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