googol/clang-uml
1
0
Fork 0
mirror of https://github.com/bkryza/clang-uml.git synced 2025-05-17 11:12:20 +08:00
Code Issues 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
.clanguml-class.example
View File

@ -1,58 +0,0 @@
glob:
- src/config/*.cc
compilation_database_dir: build
output_directory: puml
containers:
vector:
- std::vector
map:
- std::map
diagrams:
config_class_diagram:
type: class
glob:
- src/config/*.cc
- src/config/*.h
using_namespace: clanguml::config
namespaces:
- clanguml::config
classes:
- config
- diagram
- class_diagram
methods:
- public
- protected
- private
members:
- public
puml:
- 'note top of diagram: Aggregate template'
class_diagram_model_class_diagram:
type: class
glob:
- src/uml/class_diagram_model.h
using_namespace: clanguml::model::class_diagram
namespaces:
- clanguml::model::class_diagram
classes:
- diagram
- element
- class_member
- class_element
- method_argument
- class_method
- class_parent
- class_relationship
- class_
- enum_
- scope_t
- relationship_t
methods:
- public
- protected
- private
members:
- public
puml:
- 'note top of diagram: Aggregate template'

23
.clanguml-sequence.example
View File

@ -1,23 +0,0 @@
compilation_database_dir: build
output_directory: puml
diagrams:
main_sequence_diagram:
type: sequence
glob:
- src/main.cc
using_namespace:
- ""
start_from:
- usr: "c:@F@main#I#**1C#"
include:
namespaces:
- clanguml
exclude:
namespaces:
- std
- CLI
plantuml:
before:
- "' main test sequence diagram"
after:
- "' end"

90
.clanguml.example
View File

@ -1,61 +1,39 @@
glob:
- src/*.cc
compilation_database_dir: build compilation_database_dir: build
output_directory: puml
diagrams: diagrams:
communication: myproject_class:
type: class type: class
glob: glob:
- src/communication/*.cc - src/**.h
- src/communication/codec/*.cc - src/**.cc
- src/communication/layers/*.cc using_namespace:
using_namespace: one::communication - myproject
namespaces: include:
- one::communication namespaces:
- one::communication::layers - myproject
- one::communication::codec exclude:
classes: namespaces:
- ConnectionPool - myproject::detail
- Communicator plantuml:
- layers::AsyncResponder after:
- layers::BinaryTranslator - 'note left of @A(MyProjectMain) : Main class of myproject library.'
- layers::Inbox main_sequence_diagram:
- layers::Replier
- layers::Retrier
- layers::Sequencer
- layers::Translator
- codec::PacketLogger
- codec::PacketEncoder
- codec::PacketDecoder
methods:
- public
- private
members:
- public
puml:
- 'note top of Communicator : Aggregate template'
http_helper:
type: class
glob:
- src/httpHelper.cc
- src/httpHelperParams.cc
classes:
- FsLogic
args:
- '-I./src'
- '-I./include'
storage_helper:
type: class
classes:
- FileHandle
- StorageHelper
- KeyValueAdapter
- KeyValueHelper
storage_detection:
type: sequence type: sequence
begin: glob:
class: aaa - src/main.cc
method: bbb using_namespace:
end: - ""
class: ccc start_from:
method: ddd - usr: "c:@F@main#I#**1C#"
include:
namespaces:
- clanguml
exclude:
namespaces:
- std
- CLI
plantuml:
before:
- "' main test sequence diagram"
after:
- "' end"

8
LICENSE.md
View File

@ -1,7 +1,7 @@
Apache License Apache License
============== ==============
_Version 2.0, January 2004_ _Version 2.0, January 2004_
_&lt;<http://www.apache.org/licenses/>&gt;_ _&lt;<http://www.apache.org/licenses/>&gt;_
### Terms and Conditions for use, reproduction, and distribution ### Terms and Conditions for use, reproduction, and distribution
@ -180,13 +180,13 @@ the same “printed page” as the copyright notice for easier identification wi
third-party archives. third-party archives.
Copyright [yyyy] [name of copyright owner] Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License"); Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. you may not use this file except in compliance with the License.
You may obtain a copy of the License at You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

229
README.md
View File

@ -1,15 +1,49 @@
# clang-uml - UML diagram generator based on Clang and PlantUML # clang-uml - UML diagram generator based on Clang and PlantUML
clang-uml is an automatic PlantUML class and sequence diagram generator, driven by ![linux build](https://github.com/bkryza/clang-uml/actions/workflows/build.yml/badge.svg)
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.
## 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 ## 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 ## 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) * For Boost-based projects try [commands_to_compilation_database](https://github.com/tee3/commands_to_compilation_database)
### Invocation ### 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 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 ### 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 #### Default mappings
| UML | C++ | | UML | C++ |
| ---- | --- | | ---- | --- |
| Inheritance (A is kind of B) | Public, protected or private inheritance | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | 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 #### Inline directives
## Building TODO
### Ubuntu ### Sequence diagrams
To build under Ubuntu follow the following steps:
```bash #### Example
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 The following C++ code:
cd clang-uml
make release # or make debug for debug builds ```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) The build-in test cases used for unit testing of the clang-uml, can be browsed [here](./docs/test_cases.md)

25
docs/configuration_file.md Normal file
View File

@ -0,0 +1,25 @@
# Configuration file reference
## Top level options
* `compilation_database_dir` - path to the directory containing `compile_commands.json`
* `output_directory` - path to the directory where PlantUML diagrams will be generated
* `diagrams` - the map of diagrams to be generated, each diagram name is provided as
the key of the diagram YAML node
### Diagram options
* `type` - type of diagram, one of [`class`, `sequence`]
* `glob` - list of glob patterns to match source code files for analysis
* `using_namespace` - similar to C++ `using namespace`, a `A::B` value here will render a class `A::B::C::MyClass` in the diagram as `C::MyClass`
* `include` - definition of inclusion patterns:
* `namespaces` - list of namespaces to include
* `relationships` - list of relationships to include
* `entity_types` - list of entity types to include (e.g. `class`, `enum`)
* `scopes` - list of visibility scopes to include (e.g. `private`)
* `exclude` - definition of exclusion patterns:
* `namespaces` - list of namespaces to exclude
* `relationships` - list of relationships to exclude
* `entity_types` - list of entity types to exclude (e.g. `class`, `enum`)
* `scopes` - list of visibility scopes to exclude (e.g. `private`)
* `plantuml` - verbatim PlantUML directives which should be added to a diagram
* `before` - list of directives which will be added before the generated diagram
* `after` - list of directives which will be added after the generated diagram