clang-uml is an automatic C++ to PlantUML class, sequence and package diagram generator, driven by YAML configuration files. The main idea behind the project is to easily maintain up-to-date diagrams within a code-base or document existing project code. The configuration file or files for clang-uml define the type and contents of each generated diagram.

Features

Main features supported so far include:

Class diagram generation
- Basic class properties and methods including visibility
- Class relationships including associations, aggregations, dependencies and friendship
- Template instantiation relationships
- Relationship inference from C++ containers and smart pointers
- Namespace based content filtering
- Optional package generation from namespaces
- Interactive links to online code to classes, methods and class fields
Sequence diagram generation
- Generation of sequence diagram from one code location to another (currently only for non-template code)
Package diagram generation
- Generation of package diagram based on C++ namespaces
- Interactive links to online code to packages

To see what clang-uml can do so far, checkout the diagrams generated for unit test cases here.

Installation

Building from source

Currently the only method to install clang-uml is from source. First make sure that you have the following dependencies installed:

# Ubuntu
apt install ccache cmake libyaml-cpp-dev libfmt-dev libspdlog-dev clang-12 libclang-12-dev libclang-cpp12-dev

# macos
brew install ccache cmake llvm fmt spdlog yaml-cpp

Then proceed with building the sources:

git clone https://github.com/bkryza/clang-uml
cd clang-uml
make submodules
# Please note that top level Makefile is just a convenience wrapper for CMake
make release
release/clang-uml --help

# To build using a specific installed version of LLVM use:
LLVM_CONFIG_PATH=/usr/bin/llvm-config-13 make release

# To build on macos, it is necessary to provide also path to LLVM cmake directory, e.g.:
export LLVM_PREFIX="/usr/local/Cellar/llvm@12/12.0.1_1"
LLVM_CONFIG_PATH="${LLVM_PREFIX}/bin/llvm-config" CMAKE_PREFIX_PATH="${LLVM_PREFIX}/lib/cmake/llvm/" make test

# Optionally
make install
# or
export PATH=$PATH:$PWD/release

Usage

Generating compile commands database

clang-uml requires an up-to-date compile_commands.json file, containing the list of commands used for compiling the source code. Nowadays, this file can be generated rather easily using multiple methods:

For CMake projects, simply invoke the cmake command as cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ...
For Make projects checkout compiledb or Bear
For Boost-based projects try commands_to_compilation_database

Invocation

By default, config-uml will assume that the configuration file .clang-uml and compilation database compile_commands.json files are in the current directory, so if they are in the top level directory of a project, simply run:

clang-uml

The output path for diagrams, as well as alternative location of compilation database can be specified in .clang-uml configuration file.

For other options checkout help:

clang-uml --help

Configuration file format and examples

Configuration files are written in YAML, and provide a list of diagrams which should be generated by clang-uml. Basic example is as follows:

compilation_database_dir: .
output_directory: puml
diagrams:
  myproject_class:
    type: class
    glob:
      - src/*.h
      - src/*.cc
    using_namespace:
      - myproject
    include:
      namespaces:
        - myproject
    exclude:
      namespaces:
        - myproject::detail
    plantuml:
      after:
        - 'note left of {{ alias("MyProjectMain") }}: Main class of myproject library.'

See for detailed configuration file reference guide.

Examples

To see what clang-uml can do, checkout the test cases documentation here.

In order to see diagrams for the clang-uml itself, based on its own config run the following:

make clanguml_diagrams

and checkout the SVG diagrams in docs/diagrams folder.

Class diagrams

Example

Source code:

#include <string>
#include <vector>

namespace clanguml {
namespace t00009 {

template <typename T> class A {
public:
    T value;
};

class B {
public:
    A<int> aint;
    A<std::string> *astring;
    A<std::vector<std::string>> &avector;
};
}
}

generates the following diagram (via PlantUML):

Open the raw image here, and checkout the hover tooltips and hyperlinks to classes and methods.

Default mappings

UML	C++
Inheritance (A is kind of B)	Public, protected or private inheritance
Association (A knows of B)	Class A has a pointer or a reference to class B, or any container with a pointer or reference to B
Dependency (A uses B)	Any method of class A has argument of type B
Aggregation (A has B)	Class A has a field of type B or an owning pointer of type B
Composition (A has B)	Class A has a field of type container of B
Template (T specializes A)	Class A has a template parameter T
Nesting (A has inner class B)	Class B is an inner class of A
Friendship (A is a friend of B)	Class A is an friend class of B

Comment decorators

clang-uml provides a set of in-comment directives, called decorators, which allow custom control over generation of UML diagrams from C++ and overriding default inference rules for relationships.

The following decorators are currently supported:

note - add a PlantUML note to a C++ entity
skip - skip the underlying C++ entity
skiprelationship - skip only relationship generation for a class property
composition - document the property as composition
association - document the property as association
aggregation - document the property as aggregation
style - add PlantUML style to a C++ entity

Doxygen integration

clang-uml decorstors can be omitted completely in , by adding the following lines to the Doxygen config file:

ALIASES                += clanguml=""
ALIASES                += clanguml{1}=""
ALIASES                += clanguml{2}=""
ALIASES                += clanguml{3}=""

Sequence diagrams

Example

The following C++ code:

#include <algorithm>
#include <numeric>
#include <vector>

namespace clanguml {
namespace t20001 {

namespace detail {
struct C {
    auto add(int x, int y) { return x + y; }
};
}

class A {
public:
    A() {}

    int add(int x, int y) { return m_c.add(x, y); }

    int add3(int x, int y, int z)
    {
        std::vector<int> v;
        v.push_back(x);
        v.push_back(y);
        v.push_back(z);
        auto res = add(v[0], v[1]) + v[2];
        log_result(res);
        return res;
    }

    void log_result(int r) {}

private:
    detail::C m_c{};
};

class B {
public:
    B(A &a)
        : m_a{a}
    {
    }

    int wrap_add(int x, int y)
    {
        auto res = m_a.add(x, y);
        m_a.log_result(res);
        return res;
    }

    int wrap_add3(int x, int y, int z)
    {
        auto res = m_a.add3(x, y, z);
        m_a.log_result(res);
        return res;
    }

private:
    A &m_a;
};

int tmain()
{
    A a;
    B b(a);

    return b.wrap_add3(1, 2, 3);
}
}
}

generates the following diagram (via PlantUML):

Package diagrams

Example

The following C++ code:

namespace clanguml {
namespace t30003 {

namespace ns1 {
namespace ns2_v1_0_0 {
class A {
};
}

namespace [[deprecated]] ns2_v0_9_0 {
class A {
};
}

namespace {
class Anon final {
};
}
}

namespace [[deprecated]] ns3 {

namespace ns1::ns2 {
class Anon : public t30003::ns1::ns2_v1_0_0::A {
};
}

class B : public ns1::ns2::Anon {
};
}
}
}

generates the following diagram (via PlantUML):

Test cases

The build-in test cases used for unit testing of the clang-uml, can be browsed here.

Acknowledgements

This project relies on the following great tools:

libclang - a C/C++ frontend for LLVM
cppast - high-level C++ API for libclang
PlantUML - language and diagram for generating UML diagrams
Catch2 - C++ unit test framework
glob - Unix style path expansion for C++
CLI11 - command line parser for C++
inja - a template engine for modern C++

LICENSE

Copyright 2021-present Bartek Kryza <bkryza@gmail.com>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Languages

C++ 94.3%

CMake 2.6%

Python 0.8%

Makefile 0.7%

C# 0.4%

Other 1%