6.9 KiB
Common diagram generation options
- Overall configuration file structure
- Translation unit glob patterns
- PlantUML custom directives
- Adding debug information in the generated diagrams
- Resolving include path and compiler flags issues
Overall configuration file structure
By default, clang-uml will look for file .clang-uml in the projects directory and read all diagrams definitions
from it. The file must be specified in YAML and it's overall structure is as follows:
# common options for all diagrams
...
diagrams:
first_diagram_name:
type: class|sequence|package|include
# diagram specific options
...
second_diagram_name:
type: class|sequence|package|include
# diagram specific options
...
...
The top level common options are inherited by specific diagrams, if the option is applicable to them and they themselves do not override this option.
For detailed reference of all configuration options see here.
Effective configuration, including default values can be printed out in YAML format using the following option:
clang-uml --dump-config
Translation unit glob patterns
One of the key options of the diagram configuration is the list of translation 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:
glob:
- src/dir1/*.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.
any files that match the glob patterns but are not in compile_commands.json will be ignored. In case the glob
pattern set does not much 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
from compile_commands.json for the diagram. However for large projects, constraining the number of translation units
for each diagram to absolute minimum will significantly decrease the diagram generation times.
PlantUML custom directives
In case it's necessary to add some custom PlantUML declarations before or after the generated diagram content,
it can be achieved simply using the plantuml configuration properties, for instance:
plantuml:
before:
- left to right direction
after:
- note left of {{ alias("ns1::ns2::MyClass") }} This is my class.
These directive are useful for instance for adding notes to elements in the diagrams or customizing diagram layout or style.
Please note that when referring to diagram elements in the PlantUML directives, they must be added using Jinja
templates alias command as in the example above.
More options can be found in the official PlantUML documentation.
Adding debug information in the generated diagrams
Sometimes it is useful for debugging issues with the diagrams to have information on the exact source location, from which given declaration or call expression was derived. By adding option:
debug_mode: true
the generated PlantUML diagram will contain comments before each line containing the source location of the specific diagram element.
Resolving include path and compiler flags issues
Due to the fact, that your project can be compiled with different compilers
and toolchains than the Clang version, which clang-uml uses on your platform,
include paths specified in the generated compile_commands.json can be incorrect.
This is often an issue on macOS, when
clang-umluses Homebrew version of LLVM and your project was built using system Apple Clang
Typically, this results in ugly error messages on the screen during diagram generation, such as:
... fatal: 'stddef.h' file not found
or
... warning: implicit conversion from 'int' to 'float' changes value from 2147483647 to 2147483648 [-Wimplicit-const-int-float-conversion]
These errors can be overcome, by ensuring that the Clang parser has the correct
include paths to analyse your code base on the given platform. clang-uml
provides several mechanisms to resolve this issue:
Use '--query-driver' command line option
This option is not available on Windows.
Providing this option on the clang-uml command line will result in clang-uml
executing the specified compiler with the following command, e.g.:
/usr/bin/c++ -E -v -x c /dev/null 2>&1
and extracting from the output the target and system include paths, which are
then injected to each entry of the compilation database. For instance, on my
system, when generating diagrams for an embedded project and providing
arm-none-eabi-gcc as driver:
clang-uml --query-driver arm-none-eabi-gcc
the following options are appended to each command line after argv[0] of the
command:
--target=arm-none-eabi -isystem /usr/lib/gcc/arm-none-eabi/10.3.1/include -isystem /usr/lib/gcc/arm-none-eabi/10.3.1/include-fixed -isystem /usr/lib/gcc/arm-none-eabi/10.3.1/../../../arm-none-eabi/include
If you want to include the system headers reported by the compiler specified
already as argv[0] in your compile_commands.json, you can simply invoke
clang-uml as:
clang-uml --query-driver .
however please make sure that the compile_commands.json contain a command,
which is safe to execute.
Manually add and remove compile flags from the compilation database
If the system paths extracted from the compiler are not sufficient to resolve
include paths issues, it is possible to manually adjust the compilation
flags providing add_compile_flags and remove_compile_flags in the
configuration file, or providing --add-compile-flag and --remove-compile-flag
in the clang-uml command line.
For instance:
add_compile_flags:
- -I/opt/my_toolchain/include
remove_compile_flags:
- -I/usr/include
These options can be also passed on the command line, for instance:
clang-uml --add-compile-flag -I/opt/my_toolchain/include \
--remove-compile-flag -I/usr/include ...
Using 'CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES'
Yet another option, for CMake based projects, is to use the following CMake option:
set(CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})