{"id":13619930,"url":"https://github.com/bkryza/clang-uml","last_synced_at":"2025-05-14T20:02:17.246Z","repository":{"id":37893229,"uuid":"338918763","full_name":"bkryza/clang-uml","owner":"bkryza","description":"Customizable automatic UML diagram generator for C++ based on Clang.","archived":false,"fork":false,"pushed_at":"2025-03-29T13:51:39.000Z","size":92936,"stargazers_count":734,"open_issues_count":15,"forks_count":50,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-06T15:02:53.692Z","etag":null,"topics":["clang","cplusplus","cpp","cpp17","libclang","mermaidjs","plantuml","uml"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkryza.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-14T22:51:47.000Z","updated_at":"2025-04-01T13:06:12.000Z","dependencies_parsed_at":"2023-10-13T04:49:28.055Z","dependency_job_id":"e94856da-9043-443f-aa87-acd770839104","html_url":"https://github.com/bkryza/clang-uml","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkryza%2Fclang-uml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkryza%2Fclang-uml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkryza%2Fclang-uml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkryza%2Fclang-uml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkryza","download_url":"https://codeload.github.com/bkryza/clang-uml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248751851,"owners_count":21155969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clang","cplusplus","cpp","cpp17","libclang","mermaidjs","plantuml","uml"],"created_at":"2024-08-01T21:00:50.285Z","updated_at":"2025-04-13T17:27:40.388Z","avatar_url":"https://github.com/bkryza.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"[\u003cdiv align=\"center\"\u003e\u003cimg width=\"600\" src=\"https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/img/clang-uml-logo.svg?sanitize=true\"\u003e\u003c/div\u003e](https://github.com/bkryza/clang-uml/releases)\n\n# C++ UML diagram generator based on Clang\n\n[![Linux build status](https://github.com/bkryza/clang-uml/actions/workflows/build.yml/badge.svg)](https://github.com/bkryza/clang-uml/actions)\n[![macos build status](https://github.com/bkryza/clang-uml/actions/workflows/macos.yml/badge.svg)](https://github.com/bkryza/clang-uml/actions)\n[![Coverage](https://codecov.io/gh/bkryza/clang-uml/branch/master/graph/badge.svg)](https://codecov.io/gh/bkryza/clang-uml)\n[![Version](https://img.shields.io/badge/version-0.6.1-blue)](https://github.com/bkryza/clang-uml/releases)\n[![Version](https://img.shields.io/badge/LLVM-12,13,14,15,16,17,18,19,20-orange)](https://github.com/bkryza/clang-uml/releases)\n[![Doxygen](https://img.shields.io/badge/Docs-Doxygen-gainsboro)](https://clang-uml.github.io)\n\n`clang-uml` is an automatic C++ to UML class, sequence, package and include diagram generator, driven by\nYAML configuration files. The main idea behind the\nproject is to easily maintain up-to-date diagrams within a code-base or document\nlegacy code. The configuration file or files for `clang-uml` define the\ntypes and contents of each generated diagram.\n\nThe diagrams can be generated in the following formats:\n* [PlantUML](https://plantuml.com)\n* [MermaidJS](https://mermaid.js.org/)\n* [GraphML](http://graphml.graphdrawing.org/)\n* JSON\n\n`clang-uml` currently supports C++ up to version 20, as well as C and Objective-C.\n\nFull documentation can be found at [clang-uml.github.io](https://clang-uml.github.io).\n\nTo see what `clang-uml` can do, check out the diagrams generated for unit\ntest cases [here](./docs/test_cases.md), examples in\n[clang-uml-examples](https://github.com/bkryza/clang-uml-examples) repository\nor my [blog](https://blog.bkryza.com/posts/generating-uml-diagrams-from-moderncpp-using-clang).\n\n## Features\n\nMain features supported so far include:\n\n* **Class diagram generation**\n    * Class properties and methods including access scope - [_example_](docs/test_cases/t00003.md)\n    * Class inheritance - [_example_](docs/test_cases/t00002.md)\n    * Other class relationships including associations, aggregations, dependencies and friendship - [_example_](docs/test_cases/t00006.md)\n    * Template instantiation relationships - [_example_](docs/test_cases/t00014.md)\n    * Template specialization and instantiation based on deduced context - [_example_](docs/test_cases/t00062.md)\n    * Relationship inference from C++ containers and smart pointers - [_example_](docs/test_cases/t00007.md)\n    * Diagram content filtering based on namespaces, elements and relationships - [_example_](docs/test_cases/t00040.md)\n    * Optional package generation from namespaces (only PlantUML) - [_example_](docs/test_cases/t00036.md)\n    * Optional package generation from subdirectories (only PlantUML) - [_example_](docs/test_cases/t00065.md)\n    * Optional package generation from C++20 modules (only PlantUML) - [_example_](docs/test_cases/t00071.md)\n    * Interactive links to online code or docs for classes, methods and class fields in SVG diagrams - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00002_class.svg)\n    * Support for plain C99/C11 code (struct, units and their relationships) - [_example_](docs/test_cases/t00057.md)\n    * C++20 concept constraints - [_example_](docs/test_cases/t00059.md)\n    * C++20 coroutines - [_example_](docs/test_cases/t00069.md)\n    * Diagram content filtering based on C++20 modules - [_example_](docs/test_cases/t00070.md)\n    * Objective-C class diagrams - [_example_](docs/test_cases/t00084.md)\n* **Sequence diagram generation**\n    * Generation of sequence diagram from specific method or function - [_example_](docs/test_cases/t20001.md)\n    * Generation of loop and conditional statements - [_example_](docs/test_cases/t20021.md)\n    * Generation of switch statements - [_example_](docs/test_cases/t20024.md)\n    * Generation of try/catch blocks - [_example_](docs/test_cases/t20023.md)\n    * Handling of template code including constexpr conditionals - [_example_](docs/test_cases/t20018.md)\n    * Handling of lambda expressions - [_example_](docs/test_cases/t20012.md)\n    * Interactive links to online code to classes and call expressions - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t20021_sequence.svg)\n    * Support for CUDA Kernel and CUDA Device function calls - [_example_](docs/test_cases/t20050.md)\n    * Objective-C sequence diagrams - [_example_](docs/test_cases/t20058.md)\n    * C++20 coroutines support - [_example_](docs/test_cases/t20070.md)\n* **Package diagram generation**\n    * Generation of package diagram based on C++ namespaces - [_example_](docs/test_cases/t30001.md)\n    * Generation of package diagram based on subdirectories - [_example_](docs/test_cases/t30010.md)\n    * Generation of package diagram based on C++20 modules - [_example_](docs/test_cases/t30014.md)\n    * Dependencies between packages based on symbols used in the code - [_example_](docs/test_cases/t30002.md)\n    * Interactive links to online code to packages - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t30002_package.svg)\n    * Objective-C package diagrams based on subdirectories - [_example_](docs/test_cases/t30016.md)\n* **Include graph diagram generation**\n    * Show include graph for selected files - [_example_](docs/test_cases/t40001.md)\n\nMore comprehensive documentation can be at [clang-uml.github.io](https://clang-uml.github.io).\n\n## Installation\n\nInstallation instructions for `Linux`, `macos` and `Windows` can be found\n[here](./docs/installation.md).\n\n## Usage\n\n### Generating compile commands database\n\n`clang-uml` requires an up-to-date\n[compile_commands.json](https://clang.llvm.org/docs/JSONCompilationDatabase.html)\nfile, containing the list of commands used for compiling the source code\nor alternatively a list of compilation flags in a file called\n`compile_flags.txt`\n(see [here](https://clang.llvm.org/docs/JSONCompilationDatabase.html#alternatives).\n\nSee also [here](https://blog.bkryza.com/posts/compile-commands-json-gallery/)\nfor instructions on how to generate `compile_commands.json` using some of the\nexisting C++ build systems.\n\n### Invocation\n\nBy default, `clang-uml` will assume that the configuration file `.clang-uml`\nand compilation database `compile_commands.json` files are in the\ncurrent directory, so if they are in the top level directory of a project,\nsimply run:\n\n```bash\nclang-uml\n```\n\nThe output path for diagrams, as well as alternative location of\ncompilation database can be specified in `.clang-uml` configuration file or\nthrough command line parameters.\n\nFor other options see help:\n\n```bash\nclang-uml --help\n```\n\n### Configuration file format and examples\n\nConfiguration files are written in YAML, and provide definition of diagrams\nwhich should be generated by `clang-uml`. Basic example is as follows:\n\n```yaml\ncompilation_database_dir: .\noutput_directory: diagrams\ndiagrams:\n  myproject_class:\n    type: class\n    glob:\n      - src/*.cc\n    using_namespace: myproject\n    include:\n      namespaces:\n        - myproject\n    exclude:\n      namespaces:\n        - myproject::detail\n    plantuml:\n      after:\n        - 'note left of {{ alias(\"MyProjectMain\") }}: Main class of myproject library.'\n```\n\nSee [here](docs/configuration_file.md) for detailed configuration file reference guide.\n\n## Examples\n\nTo see what `clang-uml` can do, browse the test cases documentation [here](./docs/test_cases.md).\n\nIn order to see diagrams for the `clang-uml` itself, based on its own [config](.clang-uml) run\nthe following:\n\n```bash\nmake clanguml_diagrams\n```\n\nand open the SVG diagrams in `docs/diagrams` folder.\n\n### Class diagrams\n\n#### Example\n\nThe following C++ code:\n\n```cpp\ntemplate \u003ctypename T, typename P\u003e struct A {\n    T t;\n    P p;\n};\n\nstruct B {\n    std::string value;\n};\n\ntemplate \u003ctypename T\u003e using AString = A\u003cT, std::string\u003e;\ntemplate \u003ctypename T\u003e using AStringPtr = A\u003cT, std::unique_ptr\u003cstd::string\u003e\u003e;\n\ntemplate \u003ctypename T\u003e\nusing PairPairBA = std::pair\u003cstd::pair\u003cB, A\u003clong, T\u003e\u003e, long\u003e;\n\ntemplate \u003cclass T\u003e using VectorPtr = std::unique_ptr\u003cstd::vector\u003cT\u003e\u003e;\ntemplate \u003cclass T\u003e using APtr = std::unique_ptr\u003cA\u003cdouble, T\u003e\u003e;\ntemplate \u003cclass T\u003e using ASharedPtr = std::shared_ptr\u003cA\u003cdouble, T\u003e\u003e;\n\ntemplate \u003cclass T, class U\u003e\nusing AAPtr = std::unique_ptr\u003cstd::pair\u003cA\u003cdouble, T\u003e, A\u003clong, U\u003e\u003e\u003e;\n\ntemplate \u003ctypename T\u003e using SimpleCallback = std::function\u003cvoid(T, int)\u003e;\ntemplate \u003ctypename... T\u003e using GenericCallback = std::function\u003cvoid(T..., int)\u003e;\nusing VoidCallback = GenericCallback\u003cvoid *\u003e;\n\nusing BVector = std::vector\u003cB\u003e;\nusing BVector2 = BVector;\n\nusing AIntString = AString\u003cint\u003e;\nusing ACharString = AString\u003cchar\u003e;\n\nusing AStringString = AString\u003cstd::string\u003e;\nusing BStringString = AStringString;\n\ntemplate \u003ctypename T\u003e class R {\n    using AWCharString = AString\u003cwchar_t\u003e;\n\n    PairPairBA\u003cbool\u003e bapair;\n\n    APtr\u003cbool\u003e abool;\n    AAPtr\u003cbool, float\u003e aboolfloat;\n    ASharedPtr\u003cfloat\u003e afloat;\n    A\u003cbool, std::string\u003e boolstring;\n    AStringPtr\u003cfloat\u003e floatstring;\n    AIntString intstring;\n    AStringString stringstring;\n    BStringString bstringstring;\n    AAPtr\u003cT, float\u003e atfloat;\n\nprotected:\n    BVector bs;\n\npublic:\n    BVector2 bs2;\n    SimpleCallback\u003cACharString\u003e cb;\n    GenericCallback\u003cAWCharString\u003e gcb;\n    VoidCallback vcb;\n    VectorPtr\u003cB\u003e vps;\n};\n```\n\nresults in the following diagram (via PlantUML):\n\n![class_diagram_example](docs/test_cases/t00014_class.svg)\n\n### Sequence diagrams\n\n#### Example\n\nThe following C++ code:\n\n```cpp\n#include \u003catomic\u003e\n#include \u003cfunctional\u003e\n#include \u003ciostream\u003e\n#include \u003cmemory\u003e\n#include \u003cstring\u003e\n\nnamespace clanguml {\nnamespace t20029 {\nstd::string encode_b64(std::string \u0026\u0026content) { return std::move(content); }\n\ntemplate \u003ctypename T\u003e class Encoder : public T {\npublic:\n    bool send(std::string \u0026\u0026msg)\n    {\n        return T::send(std::move(\n            // Encode the message using Base64 encoding and pass it to the next\n            // layer\n            encode(std::move(msg))));\n    }\n\nprotected:\n    std::string encode(std::string \u0026\u0026msg) { return encode_b64(std::move(msg)); }\n};\n\ntemplate \u003ctypename T\u003e class Retrier : public T {\npublic:\n    bool send(std::string \u0026\u0026msg)\n    {\n        std::string buffer{std::move(msg)};\n\n        int retryCount = 5;\n\n        // Repeat until send() succeeds or retry count is exceeded\n        while (retryCount--) {\n            if (T::send(buffer))\n                return true;\n        }\n\n        return false;\n    }\n};\n\nclass ConnectionPool {\npublic:\n    void connect()\n    {\n        if (!is_connected_.load())\n            connect_impl();\n    }\n\n    bool send(const std::string \u0026msg) { return true; }\n\nprivate:\n    void connect_impl() { is_connected_ = true; }\n\n    std::atomic\u003cbool\u003e is_connected_;\n};\n\nint tmain()\n{\n    auto pool = std::make_shared\u003cEncoder\u003cRetrier\u003cConnectionPool\u003e\u003e\u003e();\n\n    // Establish connection to the remote server synchronously\n    pool-\u003econnect();\n\n    // Repeat for each line in the input stream\n    for (std::string line; std::getline(std::cin, line);) {\n        if (!pool-\u003esend(std::move(line)))\n            break;\n    }\n\n    return 0;\n}\n}\n}\n```\n\nresults in the following diagram (via PlantUML):\n\n![sequence_diagram_example](docs/test_cases/t20029_sequence.svg)\n\n\u003e Open the raw image [here](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t20029_sequence.svg),\n\u003e and check out the hover tooltips and hyperlinks to participants and methods.\n\n### Package diagrams\n\n#### Example\n\nThe following C++ code:\n\n```cpp\nnamespace clanguml {\nnamespace t30003 {\n\nnamespace ns1 {\nnamespace ns2_v1_0_0 {\nclass A {\n};\n}\n\nnamespace [[deprecated]] ns2_v0_9_0 {\nclass A {\n};\n}\n\nnamespace {\nclass Anon final {\n};\n}\n}\n\nnamespace [[deprecated]] ns3 {\n\nnamespace ns1::ns2 {\nclass Anon : public t30003::ns1::ns2_v1_0_0::A {\n};\n}\n\nclass B : public ns1::ns2::Anon {\n};\n}\n}\n}\n```\n\nresults in the following diagram (via PlantUML):\n\n![package_diagram_example](docs/test_cases/t30003_package.svg)\n\n### Include diagrams\n\n\u003e In case you're looking for a simpler tool to visualize and analyze include graphs\n\u003e check out my other tool - [clang-include-graph](https://github.com/bkryza/clang-include-graph)\n\n#### Example\n\nThe following C++ code structure:\n\n```\ntests/t40001\n├── include\n│   ├── lib1\n│   │   └── lib1.h\n│   └── t40001_include1.h\n└── src\n    └── t40001.cc\n\n```\n\nresults in the following diagram (via PlantUML) based on include directives in the code:\n\n![package_diagram_example](docs/test_cases/t40001_include.svg)\n\n### Default mappings\n\n| UML                                    | PlantUML   | MermaidJS                                      |\n| ----                                   | ---        |------------------------------------------------|\n| Inheritance                            | ![extension](docs/img/puml_inheritance.png) | ![extension](docs/img/mermaid_inheritance.png) |\n| Association                            | ![association](docs/img/puml_association.png) | ![association](docs/img/mermaid_association.png) |\n| Dependency                             | ![dependency](docs/img/puml_dependency.png) | ![dependency](docs/img/mermaid_dependency.png) |\n| Aggregation                            | ![aggregation](docs/img/puml_aggregation.png) | ![aggregation](docs/img/mermaid_aggregation.png) |\n| Composition                            | ![composition](docs/img/puml_composition.png) | ![composition](docs/img/mermaid_composition.png) |\n| Template specialization/instantiation  | ![specialization](docs/img/puml_instantiation.png) | ![specialization](docs/img/mermaid_instantiation.png) |\n| Nesting (inner class/enum)             | ![nesting](docs/img/puml_nested.png) | ![nesting](docs/img/mermaid_nested.png) |\n| Include (local)                        | ![association](docs/img/puml_association.png) | ![association](docs/img/mermaid_association.png) |\n| Include (system)                       | ![dependency](docs/img/puml_dependency.png) | ![dependency](docs/img/mermaid_dependency.png) |\n\n### Diagram content filtering\n\nFor typical code bases, a single diagram generated from an entire code or even a single namespace can be too big to\nbe useful, e.g. as part of documentation. `clang-uml` allows specifying content to be included and excluded from\neach diagram using simple YAML configuration:\n\n```yaml\ninclude:\n  # Include only elements from these namespaces\n  namespaces:\n    - clanguml::common\n    - clanguml::config\n  # Include all subclasses of ClassA (including ClassA)\n  subclasses:\n    - clanguml::common::ClassA\n  # and specializations of template Class\u003cT\u003e (including Class\u003cT\u003e)\n  specializations:\n    - clanguml::common::ClassT\u003cT\u003e\n  # and all classes depending on Class D\n  dependants:\n    - clanguml::common::ClassD\n  # and all dependencies of ClassE\n  dependencies:\n    - clanguml::common::ClassE\n  # and classes in direct relation to ClassB (including ClassB)\n  context:\n    - clanguml::common::ClassB\n  # Include only inheritance relationships\n  relationships:\n    - inheritance\nexclude:\n  # Exclude all elements from detail namespace\n  namespaces:\n    - clanguml::common::detail\n  # and also exclude ClassF\n  elements:\n    - clanguml::common::ClassF\n```\n\nMore details on this can be found in the [diagram filters](./docs/diagram_filters.md) documentation section.\n\n### Test cases\n\nThe build-in test cases used for unit testing of the `clang-uml`, can be browsed [here](./docs/test_cases.md).\n\n## Acknowledgements\n\nThis project relies on the following great tools:\n\n* [Clang LibTooling](https://clang.llvm.org/docs/LibTooling.html) - a C++ library for creating tools based on Clang\n* [PlantUML](https://plantuml.com/) - language and diagram for generating UML diagrams\n* [MermaidJS](https://mermaid.js.org/) - JavaScript based diagramming and charting tool\n* [doctest](https://github.com/doctest/doctest) - C++ unit test framework\n* [glob](https://github.com/p-ranav/glob) - Unix style path expansion for C++\n* [indicators](https://github.com/p-ranav/indicators) - Activity indicators for modern C++\n* [CLI11](https://github.com/CLIUtils/CLI11) - command line parser for C++\n* [inja](https://github.com/pantor/inja) - a template engine for modern C++\n* [backward-cpp](https://github.com/bombela/backward-cpp) - stack trace pretty printer for C++\n* [yaml-cpp](https://github.com/jbeder/yaml-cpp) - YAML parser library for C++\n* [spdlog](https://github.com/gabime/spdlog) - Fast C++ logging library\n* [Doxygen](https://www.doxygen.nl/) - C++ documentation generator\n* [Doxygen Awesome](https://jothepro.github.io/doxygen-awesome-css) - Doxygen CSS style\n* [miroir](https://github.com/m6vrm/miroir) - YAML schema validation library for C++\n* [nanobench](https://github.com/martinus/nanobench) - microbenchmarking library for C++\n* [pugixml](https://github.com/zeux/pugixml) - XML parser for C++ with XPath support\n\n## Contributing\n\nIf you would like to contribute to the project, please check out [contributing guidelines](./CONTRIBUTING.md).\n\n## LICENSE\n\n    Copyright 2021-present Bartek Kryza \u003cbkryza@gmail.com\u003e\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkryza%2Fclang-uml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkryza%2Fclang-uml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkryza%2Fclang-uml/lists"}