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

Fixed issues in docs

Browse Source
This commit is contained in:
Bartek Kryza
2024-03-05 17:36:48 +01:00
parent ba9e435786
commit 812979779b
10 changed files with 87 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/class_diagrams.md
View File

@@ -90,8 +90,10 @@ type of relationship generated in the class diagrams.
By default, a member from which a relationship has been added to the diagram By default, a member from which a relationship has been added to the diagram
between 2 classes will also be rendered inside the class. This behaviour can be between 2 classes will also be rendered inside as a property inside the class
however disabled by adding the following option to the diagram definition: box. This behaviour can be however disabled by adding the following option to
the diagram definition:
```yaml ```yaml
include_relations_also_as_members: false include_relations_also_as_members: false
``` ```
@@ -158,7 +160,7 @@ which results in the following diagram:
![t00036_class](test_cases/t00036_class.svg) ![t00036_class](test_cases/t00036_class.svg)
### Directory packages ### Directory packages
In case the code base is structured based on subdirectory instead of namespaces In case the code base is structured based on subdirectories instead of namespaces
(or this is a C project, where namespaces are not available), packages can be (or this is a C project, where namespaces are not available), packages can be
generated based on the location of a given declaration in the filesystem tree, generated based on the location of a given declaration in the filesystem tree,
by adding also the following option: by adding also the following option:
@@ -176,7 +178,9 @@ which results in the following diagram:
> denote the root path against which all relative paths in the config file are > denote the root path against which all relative paths in the config file are
> calculated. > calculated.
### Module packages ### Module packages
Finally, to generate UML packages in the diagram based on C++20 modules, use Finally, to generate UML packages in the diagram based on C++20 modules, use
the following option: the following option:
@@ -213,7 +217,7 @@ this can be easily achieved using `context` inclusion filter:
``` ```
By default, the diagram will include only elements in direct relationship to By default, the diagram will include only elements in direct relationship to
`ns1::MyClass`, but an addition option called `radius` can be added to this `ns1::MyClass`, but an additional option called `radius` can be added to this
filter, which will extend the context to elements related to `ns1::MyClass` filter, which will extend the context to elements related to `ns1::MyClass`
through at most N relationships, e.g: through at most N relationships, e.g:

55
docs/common_options.md
View File

@@ -15,30 +15,34 @@
<!-- tocstop --> <!-- tocstop -->
## Overall configuration file structure ## Overall configuration file structure
By default, `clang-uml` will look for file `.clang-uml` in the project's directory and read all diagrams definitions By default, `clang-uml` will look for file `.clang-uml` in the project's
configuration from it. The file must be specified in YAML and it's overall structure is as follows: directory and read all diagram definitions configuration from it. The file must
be specified in YAML and it's overall structure is as follows:
```yaml ```yaml
# common options for all diagrams # Common options for all diagrams
... # ...
# Diagram definitions
diagrams: diagrams:
first_diagram_name: first_diagram_name:
type: class|sequence|package|include type: class|sequence|package|include
# diagram specific options # Diagram specific options
... # ...
second_diagram_name: second_diagram_name:
type: class|sequence|package|include type: class|sequence|package|include
# diagram specific options # Diagram specific options
... # ...
... # More diagrams
# ...
``` ```
The top level common options are inherited by specific diagrams, if the option is applicable to them and they themselves The top level common options are inherited by specific diagrams, if the option
do not override this option. is applicable to them and they themselves do not override this option.
For detailed reference of all configuration options see [here](./configuration_file.md). For detailed reference of all configuration options see [here](./configuration_file.md).
Effective configuration, including default values can be printed out in YAML format using the following option: Effective configuration, including default values can be printed out in YAML
format using the following option:
```bash ```bash
clang-uml --dump-config clang-uml --dump-config
@@ -56,10 +60,11 @@ diagrams:
``` ```
## Translation unit glob patterns ## Translation unit glob patterns
One of the key options of the diagram configuration is the list of translation units, which should be parsed to One of the key options of the diagram configuration is the list of translation
get all necessary information for a diagram. units, which should be parsed to get all necessary information for a diagram.
The syntax is simple and based on glob patterns, which can be added to the configuration file as follows: The syntax is simple and based on glob patterns, which can be added to the
configuration file as follows:
```yaml ```yaml
glob: glob:
@@ -67,13 +72,17 @@ The syntax is simple and based on glob patterns, which can be added to the confi
- src/dir3/*.cc - src/dir3/*.cc
``` ```
The glob patterns only need to match the translation units, which are also in the `compile_commands.json` file, i.e. The glob patterns only need to match the translation units, which are also in
any files that match the glob patterns, but are not in `compile_commands.json` will be ignored. In case the `glob` the `compile_commands.json` file, i.e. any files that match the glob patterns,
pattern set does not match any translation units an error will be printed on the standard output. but are not in `compile_commands.json` will be ignored. In case the `glob`
pattern set does not match any translation units an error will be printed on
the standard output.
For small projects, the `glob` property can be omitted, which will result in `clang-uml` parsing all translation units For small projects, the `glob` property can be omitted, which will result in
from `compile_commands.json` for the diagram. However, for large projects, constraining the number of translation units `clang-uml` parsing all translation units from `compile_commands.json` for
for each diagram to absolute minimum will significantly decrease the diagram generation times. the diagram. However, for large projects, constraining the number of translation
units for each diagram to minimum necessary to discover all necessary diagram
elements will significantly decrease the diagram generation times.
## Custom directives ## Custom directives
In case it's necessary to add some custom PlantUML or MermaidJS declarations In case it's necessary to add some custom PlantUML or MermaidJS declarations
@@ -122,13 +131,13 @@ the generated PlantUML diagram will contain comments before each line containing
the source location of the specific diagram element. the source location of the specific diagram element.
## Resolving include path and compiler flags issues ## Resolving include path and compiler flags issues
Due to the fact, that your project can be compiled with different compilers Due to the fact, that a project can be compiled with different compilers
and toolchains, the system paths and compilation flags detected by the Clang and toolchains, the system paths and compilation flags detected by the Clang
version linked to your `clang-uml` installation might differ from the ones version linked to your `clang-uml` installation might differ from the ones
actually used to compile your project. actually used to compile your project.
> This is often an issue on macOS, when `clang-uml` uses Homebrew version of LLVM > This is often an issue on macOS, when `clang-uml` uses Homebrew version of LLVM
> and your project was built using system Apple Clang > and a project was built using system Apple Clang.
Typically, this results in error messages on the console during diagram Typically, this results in error messages on the console during diagram
generation, such as: generation, such as:

6
docs/diagram_filters.md
View File

@@ -40,7 +40,7 @@ to your diagram configuration:
``` ```
Some filters accept either specified exact values, some support regular Some filters accept either specified exact values, some support regular
expressions while some except glob patterns. expressions while some accept glob patterns.
For filters which accept regular expressions, the regular expression has to For filters which accept regular expressions, the regular expression has to
be provided as a map ```r: 'pattern'``` due to the fact the pointer (```*```) otherwise be provided as a map ```r: 'pattern'``` due to the fact the pointer (```*```) otherwise
@@ -54,8 +54,6 @@ exclude:
- r: '.*test.*' - r: '.*test.*'
``` ```
`paths` filter is currently the only filter which accepts `glob` like patterns.
The following table specifies the values allowed in each filter: The following table specifies the values allowed in each filter:
| Filter name | Possible values | Example values | | Filter name | Possible values | Example values |
@@ -64,7 +62,7 @@ The following table specifies the values allowed in each filter:
| `modules` | Qualified name or regex | ```mod1.mod2:par1```, ```r: '.*impl.*'``` | | `modules` | Qualified name or regex | ```mod1.mod2:par1```, ```r: '.*impl.*'``` |
| `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` | | `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` | | `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` |
| `paths` | File or dir path or glob pattern | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` | | `paths` | File or dir path | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` |
| `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` | | `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` |
| `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |

20
docs/generator_types.md
View File

@@ -51,6 +51,20 @@ instance:
cmd: "/usr/bin/plantuml -tsvg \"diagrams/{}.puml\"" cmd: "/usr/bin/plantuml -tsvg \"diagrams/{}.puml\""
``` ```
Furthermore, `plantuml` generator accepts basic styling options for customizing
diagram look and layout, e.g.:
```yaml
plantuml:
style:
# Apply this style to all classes in the diagram
class: "#aliceblue;line:blue;line.dotted;text:blue"
# Apply this style to all packages in the diagram
package: "#back:grey"
# Make all template instantiation relations point upwards and draw them
# as green and dotted lines
instantiation: "up[#green,dotted]"
```
An example PlantUML diagram is presented below: An example PlantUML diagram is presented below:
```plantuml ```plantuml
@@ -121,9 +135,9 @@ example:
- 'note for {{ alias("config") }} "General options not used by diagrams."' - 'note for {{ alias("config") }} "General options not used by diagrams."'
``` ```
will add before the diagram contents (right after diagram type, will add a diagram direction hint before the diagram contents (right after
e.g. `classDiagram`) diagram direction hint, and after each diagram contents diagram type, e.g. `classDiagram`), and after each diagram contents
2 notes attached to elements. 2 notes attached to classes `inheritable_diagram_options` and `config`.
This generator also accepts a `cmd` parameter to specify a command to execute This generator also accepts a `cmd` parameter to specify a command to execute
on the generated MermaidJS source file to generate actual diagram image, for on the generated MermaidJS source file to generate actual diagram image, for

2
docs/include_diagrams.md
View File

@@ -56,5 +56,5 @@ source files (matched by `glob`) and not their dependencies, for example:
![t40001_include](./test_cases/t40001_include.svg) ![t40001_include](./test_cases/t40001_include.svg)
Please note that generating include diagram, which contains third party and Please note that generating include diagram, which contains third party and
system library headers will result in a huge diagram that will be unlikely to system library headers will result in a huge diagram that is unlikely to
be useful. be useful.

18
docs/installation.md
View File

@@ -23,7 +23,7 @@
#### Ubuntu #### Ubuntu
```bash ```bash
# Currently supported Ubuntu versions are Focal, Jammy, Lunar and Mantic # Currently supported Ubuntu versions are Focal, Jammy and Mantic
sudo add-apt-repository ppa:bkryza/clang-uml sudo add-apt-repository ppa:bkryza/clang-uml
sudo apt update sudo apt update
sudo apt install clang-uml sudo apt install clang-uml
@@ -33,16 +33,16 @@ sudo apt install clang-uml
```bash ```bash
# Fedora 37 # Fedora 37
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc37.x86_64.rpm wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc37.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc37.x86_64.rpm sudo dnf install ./clang-uml-0.5.1-1.fc37.x86_64.rpm
# Fedora 38 # Fedora 38
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc38.x86_64.rpm wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc38.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc38.x86_64.rpm sudo dnf install ./clang-uml-0.5.1-1.fc38.x86_64.rpm
# Fedora 39 # Fedora 39
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc39.x86_64.rpm wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc39.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc39.x86_64.rpm sudo dnf install ./clang-uml-0.5.1-1.fc39.x86_64.rpm
``` ```
#### Conda #### Conda
@@ -79,7 +79,7 @@ release/src/clang-uml --help
# To build using a specific installed version of LLVM use: # To build using a specific installed version of LLVM use:
LLVM_VERSION=16 make release LLVM_VERSION=16 make release
# or specify path to a specific llvm-config binary, e.g.: # or specify a path to a specific llvm-config binary, e.g.:
LLVM_CONFIG_PATH=/usr/bin/llvm-config-16 make release LLVM_CONFIG_PATH=/usr/bin/llvm-config-16 make release
# or directly specify the path where LLVMConfig.cmake can be found on your system, e.g.: # or directly specify the path where LLVMConfig.cmake can be found on your system, e.g.:
CMAKE_PREFIX=/usr/lib/llvm-16/lib/cmake/llvm make release CMAKE_PREFIX=/usr/lib/llvm-16/lib/cmake/llvm make release
@@ -111,7 +111,7 @@ CMAKE_PREFIX=/usr/local/opt/llvm/lib/cmake/llvm make release
##### Visual Studio native build ##### Visual Studio native build
These steps present how to build and use `clang-uml` natively using Visual Studio only. These steps present how to build and use `clang-uml` natively using Microsoft Visual Studio only.
First, install the following dependencies manually: First, install the following dependencies manually:

12
docs/package_diagrams.md
View File

@@ -7,8 +7,8 @@
<!-- tocstop --> <!-- tocstop -->
Package diagrams are simple diagrams, which can be useful to visualize a high Package diagrams are simple diagrams, which can be useful to visualize a high
level structure of a C++ project, by rendering project's namespaces or level structure of a C++ project, by rendering project's namespaces,
subdirectories as UML packages and their interdependencies. subdirectories or modules as UML packages and their interdependencies.
The minimal config required to generate a package diagram is presented below: The minimal config required to generate a package diagram is presented below:
```yaml ```yaml
@@ -163,7 +163,8 @@ the configuration file:
package_type: directory package_type: directory
``` ```
for example check out this diagram for example check out this diagram (you can click on package names to see the
corresponding source directory):
![t30011_package](./test_cases/t30011_package.svg) ![t30011_package](./test_cases/t30011_package.svg)
Module based packages can be enabled using the following option: Module based packages can be enabled using the following option:
@@ -172,8 +173,9 @@ Module based packages can be enabled using the following option:
package_type: module package_type: module
``` ```
for example check out this diagram for example check out this diagram (you can click on package names to see the
![t30014_package](./test_cases/t30011_package.svg) corresponding module source):
![t30014_package](./test_cases/t30012_package.svg)
Diagrams can be rendered relative to a specific module using `using_module` Diagrams can be rendered relative to a specific module using `using_module`
option: option:

4
docs/quick_start.md
View File

@@ -52,9 +52,9 @@ To add an initial class diagram to your project, follow these steps:
mmdc -i diagrams/some_class_diagram.mmd -o diagrams/some_class_diagram.svg mmdc -i diagrams/some_class_diagram.mmd -o diagrams/some_class_diagram.svg
``` ```
Steps 3 and 4 can be combined into one step like follows: Steps 3 and 4 can be combined into one step:
``` ```
clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="plantuml -tsvg diagrams/{}.puml" clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="/usr/bin/plantuml -tsvg diagrams/{}.puml"
``` ```
where `-r` enables diagram rendering and `--plantuml-cmd` specifies command where `-r` enables diagram rendering and `--plantuml-cmd` specifies command
to execute on each generated diagram. to execute on each generated diagram.

14
docs/sequence_diagrams.md
View File

@@ -74,7 +74,7 @@ there are 3 types of constraints:
locations locations
Currently, the constraints can be a method or a free function, both specified Currently, the constraints can be a method or a free function, both specified
using the full signature of the function, e.g. using the full signature of the function, e.g.:
```yaml ```yaml
from: from:
@@ -97,8 +97,8 @@ and `to` locations as follows:
function: "clanguml::t20034::A::a2()"] function: "clanguml::t20034::A::a2()"]
``` ```
To find the exact function signature which, can be used as a `from` location, To find the exact function signature, which can be used as a `from` location,
run `clang-uml` as follows: run `clang-uml` as follows (assuming the function of interest is called `main`):
```bash ```bash
clang-uml --print-from -n main_sequence | grep main clang-uml --print-from -n main_sequence | grep main
@@ -112,7 +112,7 @@ clang-uml --print-to -n main_sequence | grep main
Command line flags `--print-from` and `--print-to` will print on stdout all Command line flags `--print-from` and `--print-to` will print on stdout all
functions and methods available in the diagram model, and each line of this functions and methods available in the diagram model, and each line of this
output can be directly used as a value of `start_from`, `from_to` or `to` output can be directly used as a value of `from`, `from_to` or `to`
properties in the config file. properties in the config file.
Since that list can be quite large, it's best to filter the output to limit Since that list can be quite large, it's best to filter the output to limit
@@ -141,7 +141,7 @@ tentative support, which follows the following rules:
* If lambda expression is passed to some function or method, which is outside * If lambda expression is passed to some function or method, which is outside
the scope of the diagram (e.g. used in `std::transform` call) the call will the scope of the diagram (e.g. used in `std::transform` call) the call will
not be generated not be generated
* If the lambda is passed as template parameter in instantiation it will not * If the lambda is passed as template argument in instantiation it will not
be generated be generated
Another issue is the naming of lambda participants. Currently, each lambda is Another issue is the naming of lambda participants. Currently, each lambda is
@@ -257,7 +257,7 @@ The default participant order in the sequence diagram can be suboptimal in the
sense that consecutive calls can go right, then left, then right again sense that consecutive calls can go right, then left, then right again
depending on the specific call chain in the code. It is however possible to depending on the specific call chain in the code. It is however possible to
override this order in the diagram definition using `participants_order` override this order in the diagram definition using `participants_order`
property, for instance like this test case: property, for instance like this:
```yaml ```yaml
diagrams: diagrams:
@@ -372,5 +372,5 @@ for each sequence diagram, which should include these comments.
In case only selected messages should have some specific comments, instead In case only selected messages should have some specific comments, instead
of enabling the `generate_message_comments` option, it is possible to use of enabling the `generate_message_comments` option, it is possible to use
`\uml{note TEXT}` directive in the comment above the expression, see `\\uml{note TEXT}` directive in the comment above the expression, see
[t20001](test_cases/t20001_sequence.svg). [t20001](test_cases/t20001_sequence.svg).

4
docs/troubleshooting.md
View File

@@ -22,7 +22,7 @@
## General issues ## General issues
### clang-uml crashes when generating diagram ### clang-uml crashes when generating a diagram
If `clang-uml` crashes with a segmentation fault, it is possible to trace the If `clang-uml` crashes with a segmentation fault, it is possible to trace the
exact stack trace of the fault using the following steps: exact stack trace of the fault using the following steps:
@@ -346,7 +346,7 @@ the exact string representation of the function signature as seen by `clang-uml`
To find the exact function signature run `clang-uml` as follows: To find the exact function signature run `clang-uml` as follows:
```bash ```bash
clang-uml -n my_sequence_diagram --print-start-from | grep foo clang-uml -n my_sequence_diagram --print-from | grep foo
``` ```
Command line flag `--print-from` will print on stdout all functions Command line flag `--print-from` will print on stdout all functions