diff --git a/.clanguml-class.example b/.clanguml-class.example deleted file mode 100644 index 3851374a..00000000 --- a/.clanguml-class.example +++ /dev/null @@ -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' diff --git a/.clanguml-sequence.example b/.clanguml-sequence.example deleted file mode 100644 index 0ec4ba89..00000000 --- a/.clanguml-sequence.example +++ /dev/null @@ -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" diff --git a/.clanguml.example b/.clanguml.example index 4cfab82a..b77bdd97 100644 --- a/.clanguml.example +++ b/.clanguml.example @@ -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" diff --git a/LICENSE.md b/LICENSE.md index f5f4b8b5..84a5a44c 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,7 +1,7 @@ Apache License ============== -_Version 2.0, January 2004_ +_Version 2.0, January 2004_ _<>_ ### 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. Copyright [yyyy] [name of copyright owner] - + 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. diff --git a/README.md b/README.md index 3fccd41c..d51a3582 100644 --- a/README.md +++ b/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. +![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 +#include + +namespace clanguml { +namespace t00009 { + +template class A { +public: + T value; +}; + +class B { +public: + A aint; + A *astring; + A> &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 +#include +#include + +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 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) diff --git a/docs/configuration_file.md b/docs/configuration_file.md new file mode 100644 index 00000000..b1d7ae11 --- /dev/null +++ b/docs/configuration_file.md @@ -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