clang-uml/docs/architecture.md

Architecture

• Overview
• Configuration model
• Diagram model
  • Common model
  • Diagram filters
• Translation unit visitors
• Diagram generators
• Command line handler
• Tests
  • Unit tests
  • Test cases
  • Real code tests

This section presents general architecture and components of clang-uml.

All diagrams below are generated by clang-uml and updated automatically.

Overview

clang-uml is written in C++17 and uses Clang LibTooling API to traverse the AST (Abstract Syntax Tree) of the source code and extract any information relevant for a specified diagram.

The code is divided into several packages (namespaces), the main of them are:

• clanguml::config - configuration handling
• clanguml::common - common interfaces
• clanguml::class_diagram - specializations for class diagrams
• clanguml::sequence_diagram - specializations for sequence diagrams
• clanguml::include_diagram - specializations for include diagrams
• clanguml::package_diagram - specializations for package diagrams

Configuration model

The configuration model consists of classes representing the configuration specified in the YAML configuration files.

Depending on the option, it can either:

• be specified only at the top level of the configuration file
• only in the specific diagram configuration
• either of the above

The first group of options are stored in the config::config class.

The second group is stored in a specific diagram config subclass, e.g. config::sequence_diagram

The options in the last group are modeled in the config::inheritable_diagram_options.

The YAML configuration file is parsed using yaml-cpp library:

For each possible option type, there must an implementation of a YAML decoder - e.g. YAML::convert<filter> (for converting YAML nodes to configuration model classes) and a YAML emitter - e.g. operator<< (for generating YAML from configuration model classes).

Diagram model

The diagram model namespace is divided into the common model namespace and 1 namespace for each supported diagram type.

Common model

The common diagram model namespace, provides a set of classes representing typical UML and C++ concepts such as diagram elements, packages, templates, and others which are shared by more than 1 diagram type.

The diagram elements are composed into a hierarchy spanning all major namespaces, depending on whether the element is specific for a single diagram type ( e.g. participant), or whether it's common for several diagram types ( e.g. package).

Diagram filters

In order to ease the generation of diagrams, clang-uml has a (very) simple intermediate UML model, which covers only the features necessary for generation of the supported diagram types. The model can be extended if necessary to add new features.

Translation unit visitors

The first stage in the diagram generation involves traversing the AST of each translation unit from the compile_commands.json compilation database, which matched at least one pattern specified in the glob pattern of the configuration file.

Each visitor is implemented in a subclass of translation_unit_visitor, and must also implement relevant methods from Clang's RecursiveASTVisitor.

The output of the translation_unit_visitor for each diagram type is an intermediate diagram model, which is then passed to the relevant diagram generator.

Diagram generators

Diagram generators convert the clang-uml's internal UML model into actual diagram in one of the supported formats:

• PlantUML
• JSON

Each diagram generator extends a common interface appropriate for the selected output format, i.e.:

• PlantUML
• JSON

and renders the output to a file. For each diagram type there is a separate generator for each supported output format.

Command line handler

The cli_handler is a command line handler class is a wrapper around CLI11, and implements handlers for various actions, validates command line parameters and reports errors.

Tests

Unit tests

Basic set of units tests are stored in tests/test_*.cc test files. The unit tests do not aim to cover the entire codebase, only specific algorithms or methods, which should behave as expected and if their errors can be difficult to diagnose when running the test cases on C++ code.

Test cases

These tests are the main tests of clang-uml. Each test case tests one or more feature of a specific diagram type. Each of them has a separated directory in the tests directory and its own .clang-uml with diagram configuration as well as a test_case.h file which contains the tests assertions.

Any other sources in that directory are compiled and then used to generate the diagrams, whose contents should be then verified within test_case.h for correctness. All the sources should be wrapped within a namespace: clanguml::

These test directories are numbered in consecutive numbers using the following convention:

• Start with a letter t
• The first digit of the number is the diagram type:
  • 0 - class diagram
  • 2 - sequence diagram
  • 3 - package diagram
  • 4 - include diagram
  • 9 - other test cases
• The rest of the name is the consecutive number of the test case

Each test case is also referenced in test_cases.yaml where it has assigned a title. That file is used to generate the test cases documentation page.

Real code tests

Each release is tested on a set of open-source C++ projects, to be sure that at least the new version does not crash or introduce some obvious regressions.

The tests are stored in a separate repository: clang-uml-examples.