search

bkryza / clang-uml

Customizable automatic UML diagram generator for C++ based on Clang.
Apache License 2.0
611 stars 44 forks source link
clang cplusplus cpp cpp17 libclang mermaidjs plantuml uml

readme

C++ UML diagram generator based on Clang

Linux build status macos build status Coverage Version Version Doxygen

clang-uml is an automatic C++ to UML class, sequence, package and include 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 legacy code. The configuration file or files for clang-uml define the types and contents of each generated diagram. The diagrams can be generated in PlantUML, MermaidJS and JSON formats.

clang-uml currently supports C++ up to version 20, as well as C and Objective-C.

Full documentation can be found at clang-uml.github.io.

To see what clang-uml can do, check out the diagrams generated for unit test cases here or examples in clang-uml-examples repository.

Features

Main features supported so far include:

More comprehensive documentation can be at clang-uml.github.io.

Installation

Installation instructions for Linux, macos and Windows can be found here.

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.

See my repository compile_commands_gallery for examples on how to generate compile_commands.json from some of the existing C++ build systems.

Invocation

By default, clang-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 or through command line parameters.

For other options see help:

clang-uml --help

Configuration file format and examples

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

compilation_database_dir: .
output_directory: diagrams
diagrams:
  myproject_class:
    type: class
    glob:
      - 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 here for detailed configuration file reference guide.

Examples

To see what clang-uml can do, browse 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 open the SVG diagrams in docs/diagrams folder.

Class diagrams

Example

The following C++ code:

template <typename T, typename P> struct A {
    T t;
    P p;
};

struct B {
    std::string value;
};

template <typename T> using AString = A<T, std::string>;
template <typename T> using AStringPtr = A<T, std::unique_ptr<std::string>>;

template <typename T>
using PairPairBA = std::pair<std::pair<B, A<long, T>>, long>;

template <class T> using VectorPtr = std::unique_ptr<std::vector<T>>;
template <class T> using APtr = std::unique_ptr<A<double, T>>;
template <class T> using ASharedPtr = std::shared_ptr<A<double, T>>;

template <class T, class U>
using AAPtr = std::unique_ptr<std::pair<A<double, T>, A<long, U>>>;

template <typename T> using SimpleCallback = std::function<void(T, int)>;
template <typename... T> using GenericCallback = std::function<void(T..., int)>;
using VoidCallback = GenericCallback<void *>;

using BVector = std::vector<B>;
using BVector2 = BVector;

using AIntString = AString<int>;
using ACharString = AString<char>;

using AStringString = AString<std::string>;
using BStringString = AStringString;

template <typename T> class R {
    using AWCharString = AString<wchar_t>;

    PairPairBA<bool> bapair;

    APtr<bool> abool;
    AAPtr<bool, float> aboolfloat;
    ASharedPtr<float> afloat;
    A<bool, std::string> boolstring;
    AStringPtr<float> floatstring;
    AIntString intstring;
    AStringString stringstring;
    BStringString bstringstring;
    AAPtr<T, float> atfloat;

protected:
    BVector bs;

public:
    BVector2 bs2;
    SimpleCallback<ACharString> cb;
    GenericCallback<AWCharString> gcb;
    VoidCallback vcb;
    VectorPtr<B> vps;
};

results in the following diagram (via PlantUML):

class_diagram_example

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

Sequence diagrams

Example

The following C++ code:

#include <atomic>
#include <functional>
#include <iostream>
#include <memory>
#include <string>

namespace clanguml {
namespace t20029 {
std::string encode_b64(std::string &&content) { return std::move(content); }

template <typename T> class Encoder : public T {
public:
    bool send(std::string &&msg)
    {
        return T::send(std::move(
            // Encode the message using Base64 encoding and pass it to the next
            // layer
            encode(std::move(msg))));
    }

protected:
    std::string encode(std::string &&msg) { return encode_b64(std::move(msg)); }
};

template <typename T> class Retrier : public T {
public:
    bool send(std::string &&msg)
    {
        std::string buffer{std::move(msg)};

        int retryCount = 5;

        // Repeat until send() succeeds or retry count is exceeded
        while (retryCount--) {
            if (T::send(buffer))
                return true;
        }

        return false;
    }
};

class ConnectionPool {
public:
    void connect()
    {
        if (!is_connected_.load())
            connect_impl();
    }

    bool send(const std::string &msg) { return true; }

private:
    void connect_impl() { is_connected_ = true; }

    std::atomic<bool> is_connected_;
};

int tmain()
{
    auto pool = std::make_shared<Encoder<Retrier<ConnectionPool>>>();

    // Establish connection to the remote server synchronously
    pool->connect();

    // Repeat for each line in the input stream
    for (std::string line; std::getline(std::cin, line);) {
        if (!pool->send(std::move(line)))
            break;
    }

    return 0;
}
}
}

results in the following diagram (via PlantUML):

sequence_diagram_example

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 {
};
}
}
}

results in the following diagram (via PlantUML):

package_diagram_example

Include diagrams

In case you're looking for a simpler tool to visualize and analyze include graphs check out my other tool - clang-include-graph

Example

The following C++ code structure:

tests/t40001
├── include
│   ├── lib1
│   │   └── lib1.h
│   └── t40001_include1.h
└── src
    └── t40001.cc

results in the following diagram (via PlantUML) based on include directives in the code:

package_diagram_example

Default mappings

UML PlantUML MermaidJS
Inheritance extension extension
Association association association
Dependency dependency dependency
Aggregation aggregation aggregation
Composition composition composition
Template specialization/instantiation specialization specialization
Nesting (inner class/enum) nesting nesting
Include (local) association association
Include (system) dependency dependency

Diagram content filtering

For typical code bases, a single diagram generated from an entire code or even a single namespace can be too big to be useful, e.g. as part of documentation. clang-uml allows specifying content to be included and excluded from each diagram using simple YAML configuration:

include:
  # Include only elements from these namespaces
  namespaces:
    - clanguml::common
    - clanguml::config
  # Include all subclasses of ClassA (including ClassA)
  subclasses:
    - clanguml::common::ClassA
  # and specializations of template Class<T> (including Class<T>)
  specializations:
    - clanguml::common::ClassT<T>
  # and all classes depending on Class D
  dependants:
    - clanguml::common::ClassD
  # and all dependencies of ClassE
  dependencies:
    - clanguml::common::ClassE
  # and classes in direct relation to ClassB (including ClassB)
  context:
    - clanguml::common::ClassB
  # Include only inheritance relationships
  relationships:
    - inheritance
exclude:
  # Exclude all elements from detail namespace
  namespaces:
    - clanguml::common::detail
  # and also exclude ClassF
  elements:
    - clanguml::common::ClassF

More details on this can be found in the diagram filters documentation section.

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:

Contributing

If you would like to contribute to the project, please check out contributing guidelines.

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.