mirror of
https://github.com/bkryza/clang-uml.git
synced 2025-05-16 18:52:49 +08:00
Updated README
This commit is contained in:
Bartek Kryza
parent
524cf36ecd
commit
f9bc218d90
@ -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'
|
||||
@ -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"
|
||||
@ -1,61 +1,39 @@
|
||||
glob:
|
||||
- src/*.cc
|
||||
compilation_database_dir: build
|
||||
output_directory: puml
|
||||
diagrams:
|
||||
communication:
|
||||
myproject_class:
|
||||
type: class
|
||||
glob:
|
||||
- src/communication/*.cc
|
||||
- src/communication/codec/*.cc
|
||||
- src/communication/layers/*.cc
|
||||
using_namespace: one::communication
|
||||
namespaces:
|
||||
- one::communication
|
||||
- one::communication::layers
|
||||
- one::communication::codec
|
||||
classes:
|
||||
- ConnectionPool
|
||||
- Communicator
|
||||
- layers::AsyncResponder
|
||||
- layers::BinaryTranslator
|
||||
- layers::Inbox
|
||||
- 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:
|
||||
- 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.'
|
||||
main_sequence_diagram:
|
||||
type: sequence
|
||||
begin:
|
||||
class: aaa
|
||||
method: bbb
|
||||
end:
|
||||
class: ccc
|
||||
method: ddd
|
||||
|
||||
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"
|
||||
|
||||
229
README.md
229
README.md
@ -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.
|
||||
|
||||
|
||||
## 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  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):
|
||||
|
||||
|
||||
|
||||
#### 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
|
||||
|
||||
|
||||
#### 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)
|
||||
|
||||
|
||||
25
docs/configuration_file.md
Normal file
25
docs/configuration_file.md
Normal 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
|
||||
Loading…
x
Reference in New Issue
Block a user