matthias/clang-uml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated README

Browse Source
This commit is contained in:
Bartek Kryza
2021-07-24 11:27:03 +02:00
parent 524cf36ecd
commit f9bc218d90
6 changed files with 266 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
README.md
View File

@@ -1,15 +1,49 @@
# clang-uml - UML diagram generator based on Clang and PlantUML
clang-uml is an automatic PlantUML class and sequence 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. The configuration file or
files for clang-uml define the type and scope of each diagram.
![linux build](https://github.com/bkryza/clang-uml/actions/workflows/build.yml/badge.svg)
## Rationale
`clang-uml` is an automatic !(PlantUML)[https://plantuml.com/] class and sequence
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 diagram.
## Features
Main features supported so far include:
* Class diagram generation
* Basic class properties and methods including visibility
* Class relationships including associations, aggregations and friendship
* Template instantiation relationship
* Relationship inference from C++ containers and smart pointers
* Namespace based content filtering
* Sequence diagram generation
* Generation of sequence diagram from one code location to another
## Installation
TODO
### Building from source
Currently the only method to install `clang-uml` is from source. First make sure
that you have the following dependencies installed (example for Ubuntu):
```bash
apt install ccache cmake libyaml-cpp-dev libfmt-dev libspdlog-dev clang-12 libclang-12-dev libclang-cpp12-dev
```
```bash
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
# Optionally
make install
# or
export PATH=$PATH:$PWD/release
```
## Usage
@@ -24,41 +58,184 @@ Nowadays, this file can be generated rather easily using multiple methods:
* For Boost-based projects try [commands_to_compilation_database](https://github.com/tee3/commands_to_compilation_database)
### Invocation
By default, `config-uml` will assume that the configuration file `.clanguml`
and compilation database `compilation_database.json` files are in the
current directory, so if they are in the top level directory of a project,
simply run:
```bash
clang-uml
```
The output path for diagrams, as well as alternative location of
compilation database can be specified in `.clanguml` configuration file.
For other options checkout help:
```bash
clang-uml --help
```
### Configuration file format and examples
Configuration files are written in YAML, and provide a list of diagrams
which sould be generated by `clang-uml`. Basic example is as follows:
```yaml
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 @A(MyProjectMain) : Main class of myproject library.'
```
See ![here](docs/configuration_file.md) for detailed configuration file reference guide.
### Class diagrams
#### Example
Source code:
```cpp
#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):
![class_diagram_example](docs/test_cases/t00009_class.png)
#### 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
| 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
#### Inline directives
## Building
TODO
### Ubuntu
To build under Ubuntu follow the following steps:
```bash
sudo apt-get install cmake build-essential libyaml-cpp-dev libspdlog-dev libclang-11-dev libclang-cpp11-dev
git clone https://github.com/bkryza/clang-uml
cd clang-uml
make release # or make debug for debug builds
### Sequence diagrams
#### Example
The following C++ code:
```cpp
#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);
}
}
}
```
## Documentation
generates the following diagram (via PlantUML):
### Examples
![sequence_diagram_example](docs/test_cases/t20001_sequence.png)
#### Test cases
### Test cases
The build-in test cases used for unit testing of the clang-uml, can be browsed [here](./docs/test_cases.md)