<h1 align="center">c2puml - C to PlantUML Converter</h1>
<p align="center">
<img src="docs/c2puml.jpg" alt="C 2 Puml" width="128"/>
</p>
A Python tool for converting C/C++ source code to PlantUML diagrams. Analyzes C/C++ projects and generates comprehensive PlantUML class diagrams showing structs, enums, unions, functions, global variables, macros, typedefs, and include relationships.
## Status
[](https://github.com/fischerjooo/c2puml/actions/workflows/test.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/puml2png.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/test-coverage.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/deploy-website.yml)
## Reports
- [📊 Combined Coverage Report](https://fischerjooo.github.io/c2puml/artifacts/coverage/htmlcov/index.html) - Comprehensive coverage report with summary and detailed per-file analysis
- [📝 Test Summary](https://fischerjooo.github.io/c2puml/artifacts/test_reports/test_summary.html) - Test execution summary and statistics
- [📊 Example Diagrams](https://fischerjooo.github.io/c2puml/artifacts/output_example/diagram_index.html) - Quick view of all generated PlantUML diagrams and PNG images
- [📋 Example Source Code](https://github.com/fischerjooo/c2puml/tree/main/tests/example) - Browse the example C/C++ source files used for testing and demonstration
## Documentation
- [📖 Specification](https://github.com/fischerjooo/c2puml/blob/main/docs/specification.md) - Complete technical specification and architecture documentation
- [🎨 PlantUML Template](https://github.com/fischerjooo/c2puml/blob/main/docs/puml_template.md) - PlantUML formatting template and diagram structure rules
- [⚙️ Configuration Guide](https://github.com/fischerjooo/c2puml/blob/main/docs/configuration.md) - Detailed config.json reference and examples
## Releases
- [📦 Download ZIP](https://github.com/fischerjooo/c2puml/archive/refs/heads/release.zip) - Download the latest release as ZIP archive
- [📦 Download TAR.GZ](https://github.com/fischerjooo/c2puml/archive/refs/heads/release.tar.gz) - Download the latest release as TAR.GZ archive
## Features
- **C/C++ Parsing**: Comprehensive tokenization-based parsing with preprocessor handling and conditional compilation support
- **Project Analysis**: Analyzes entire C/C++ projects with recursive directory scanning and configurable include depth processing
- **PlantUML Generation**: Creates organized PlantUML diagrams with proper UML notation and relationship visualization
- **Configuration System**: Flexible filtering and transformation capabilities with file-specific settings
- **Enhanced UML Stereotypes**: Uses specific stereotypes for different typedef types (<<enumeration>>, <<struct>>, <<union>>, <<typedef>>)
- **Smart Visibility Detection**: Automatically determines public/private visibility based on header file declarations
## Installation
### Option 1: Install as Python Package (Recommended)
```bash
git clone https://github.com/fischerjooo/c2puml.git
cd c2puml
python3 -m pip install -e .
```
### Option 2: Use Standalone Script (No Installation Required)
If you prefer not to install the package, you can use the standalone script directly:
```bash
git clone https://github.com/fischerjooo/c2puml.git
cd c2puml
# No installation needed - just run the script directly
python3 main.py --config tests/example/config.json
```
**Prerequisites for standalone usage:**
- Python 3.7 or later
- The complete c2puml source code (including the `src/` directory)
## Quick Start
### Basic Usage
#### Using Installed Package
```bash
# Full workflow: Parse → Transform → Generate diagrams
c2puml --config tests/example/config.json
# Using current directory configuration (merges all .json files)
c2puml
# Individual steps
c2puml --config tests/example/config.json parse # Step 1: Parse only
c2puml --config tests/example/config.json transform # Step 2: Transform only
c2puml --config tests/example/config.json generate # Step 3: Generate only
# With verbose output for debugging
c2puml --config tests/example/config.json --verbose
# Alternative module syntax
python3 -m c2puml.main --config tests/example/config.json
```
#### Using Standalone Script (No Installation)
```bash
# Full workflow: Parse → Transform → Generate diagrams
python3 main.py --config tests/example/config.json
# Using current directory configuration (merges all .json files)
python3 main.py
# Individual steps
python3 main.py --config tests/example/config.json parse # Step 1: Parse only
python3 main.py --config tests/example/config.json transform # Step 2: Transform only
python3 main.py --config tests/example/config.json generate # Step 3: Generate only
# With verbose output for debugging
python3 main.py --config tests/example/config.json --verbose
```
**Note**: Both methods provide identical functionality. Choose the one that best fits your workflow.
### Generate PNG Images
```bash
# Linux/macOS
./picgen.sh
# Windows
picgen.bat
```
The scripts automatically:
- Download PlantUML.jar if needed
- Install Graphviz (required for PNG generation)
- Test the setup before conversion
- Convert all .puml files to PNG images
**Note**: The script automatically handles Graphviz installation and testing to resolve the "Dot executable does not exist" error.
## Configuration
Create a `config.json` to customize analysis and output. Minimal example:
```json
{
"project_name": "my_project",
"source_folders": ["./src"],
"output_dir": "./output"
}
```
Run with a config file:
```bash
c2puml --config config.json
# or (merges all .json files in the current directory)
c2puml
```
For full examples (file-specific include filters, include depth, formatting, and the transformation system), see the Configuration Guide: [docs/configuration.md](docs/configuration.md).
## Generated Output
The tool creates PlantUML diagrams showing:
- Source files with functions, structs, enums, unions
- Header files with declarations
- Include relationships between files
- Typedef relationships with enhanced UML stereotypes
- Color-coded elements (source, headers, typedefs)
- Dynamic visibility detection (public/private based on header presence)
## Troubleshooting
### Common Issues
**"Command 'c2puml' not found"**
- **Solution**: Install the package with `pip install -e .`
- **Alternative**: Use the standalone script: `python3 main.py --config config.json`
**"Module 'c2puml' not found"**
- **Solution**: Ensure you're in the project root directory and the `src/` folder exists
- **Alternative**: Use the standalone script which handles path setup automatically
**"Permission denied" errors**
- **Solution**: Use the standalone script which doesn't require installation: `python3 main.py`
**"Dot executable does not exist" (PlantUML PNG generation)**
- **Solution**: Install Graphviz or use the provided scripts: `./scripts/picgen.sh` or `scripts/picgen.bat`
### Getting Help
- **Quick Test**: Try the standalone script first: `python3 main.py --config tests/example/config.json`
- **Development**: Use the debug script: `python scripts/debug.py`
- **Examples**: Run the example workflow: `./scripts/run_example.sh` or `scripts/run_example.bat`
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "c2puml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "c, cpp, plantuml, uml, diagram, code-generation, documentation",
"author": null,
"author_email": "C to PlantUML Team <fischerjooo@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/15/a28ebe68af4113e835973b40c6e664bef265e7f640f00059457be5c5be46/c2puml-2025.9.9.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">c2puml - C to PlantUML Converter</h1>\r\n<p align=\"center\">\r\n <img src=\"docs/c2puml.jpg\" alt=\"C 2 Puml\" width=\"128\"/>\r\n</p>\r\nA Python tool for converting C/C++ source code to PlantUML diagrams. Analyzes C/C++ projects and generates comprehensive PlantUML class diagrams showing structs, enums, unions, functions, global variables, macros, typedefs, and include relationships.\r\n\r\n## Status\r\n[](https://github.com/fischerjooo/c2puml/actions/workflows/test.yml)\r\n[](https://github.com/fischerjooo/c2puml/actions/workflows/puml2png.yml)\r\n[](https://github.com/fischerjooo/c2puml/actions/workflows/test-coverage.yml)\r\n[](https://github.com/fischerjooo/c2puml/actions/workflows/deploy-website.yml)\r\n\r\n## Reports\r\n\r\n- [\ud83d\udcca Combined Coverage Report](https://fischerjooo.github.io/c2puml/artifacts/coverage/htmlcov/index.html) - Comprehensive coverage report with summary and detailed per-file analysis\r\n- [\ud83d\udcdd Test Summary](https://fischerjooo.github.io/c2puml/artifacts/test_reports/test_summary.html) - Test execution summary and statistics\r\n- [\ud83d\udcca Example Diagrams](https://fischerjooo.github.io/c2puml/artifacts/output_example/diagram_index.html) - Quick view of all generated PlantUML diagrams and PNG images\r\n- [\ud83d\udccb Example Source Code](https://github.com/fischerjooo/c2puml/tree/main/tests/example) - Browse the example C/C++ source files used for testing and demonstration\r\n\r\n## Documentation\r\n\r\n- [\ud83d\udcd6 Specification](https://github.com/fischerjooo/c2puml/blob/main/docs/specification.md) - Complete technical specification and architecture documentation\r\n- [\ud83c\udfa8 PlantUML Template](https://github.com/fischerjooo/c2puml/blob/main/docs/puml_template.md) - PlantUML formatting template and diagram structure rules\r\n- [\u2699\ufe0f Configuration Guide](https://github.com/fischerjooo/c2puml/blob/main/docs/configuration.md) - Detailed config.json reference and examples\r\n\r\n## Releases\r\n\r\n- [\ud83d\udce6 Download ZIP](https://github.com/fischerjooo/c2puml/archive/refs/heads/release.zip) - Download the latest release as ZIP archive\r\n- [\ud83d\udce6 Download TAR.GZ](https://github.com/fischerjooo/c2puml/archive/refs/heads/release.tar.gz) - Download the latest release as TAR.GZ archive\r\n\r\n## Features\r\n\r\n- **C/C++ Parsing**: Comprehensive tokenization-based parsing with preprocessor handling and conditional compilation support\r\n- **Project Analysis**: Analyzes entire C/C++ projects with recursive directory scanning and configurable include depth processing\r\n- **PlantUML Generation**: Creates organized PlantUML diagrams with proper UML notation and relationship visualization\r\n- **Configuration System**: Flexible filtering and transformation capabilities with file-specific settings\r\n- **Enhanced UML Stereotypes**: Uses specific stereotypes for different typedef types (<<enumeration>>, <<struct>>, <<union>>, <<typedef>>)\r\n- **Smart Visibility Detection**: Automatically determines public/private visibility based on header file declarations\r\n\r\n## Installation\r\n\r\n### Option 1: Install as Python Package (Recommended)\r\n\r\n```bash\r\ngit clone https://github.com/fischerjooo/c2puml.git\r\ncd c2puml\r\npython3 -m pip install -e .\r\n```\r\n\r\n### Option 2: Use Standalone Script (No Installation Required)\r\n\r\nIf you prefer not to install the package, you can use the standalone script directly:\r\n\r\n```bash\r\ngit clone https://github.com/fischerjooo/c2puml.git\r\ncd c2puml\r\n# No installation needed - just run the script directly\r\npython3 main.py --config tests/example/config.json\r\n```\r\n\r\n**Prerequisites for standalone usage:**\r\n- Python 3.7 or later\r\n- The complete c2puml source code (including the `src/` directory)\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n#### Using Installed Package\r\n\r\n```bash\r\n# Full workflow: Parse \u2192 Transform \u2192 Generate diagrams\r\nc2puml --config tests/example/config.json\r\n\r\n# Using current directory configuration (merges all .json files)\r\nc2puml\r\n\r\n# Individual steps\r\nc2puml --config tests/example/config.json parse # Step 1: Parse only\r\nc2puml --config tests/example/config.json transform # Step 2: Transform only\r\nc2puml --config tests/example/config.json generate # Step 3: Generate only\r\n\r\n# With verbose output for debugging\r\nc2puml --config tests/example/config.json --verbose\r\n\r\n# Alternative module syntax\r\npython3 -m c2puml.main --config tests/example/config.json\r\n```\r\n\r\n#### Using Standalone Script (No Installation)\r\n\r\n```bash\r\n# Full workflow: Parse \u2192 Transform \u2192 Generate diagrams\r\npython3 main.py --config tests/example/config.json\r\n\r\n# Using current directory configuration (merges all .json files)\r\npython3 main.py\r\n\r\n# Individual steps\r\npython3 main.py --config tests/example/config.json parse # Step 1: Parse only\r\npython3 main.py --config tests/example/config.json transform # Step 2: Transform only\r\npython3 main.py --config tests/example/config.json generate # Step 3: Generate only\r\n\r\n# With verbose output for debugging\r\npython3 main.py --config tests/example/config.json --verbose\r\n```\r\n\r\n**Note**: Both methods provide identical functionality. Choose the one that best fits your workflow.\r\n\r\n\r\n### Generate PNG Images\r\n\r\n```bash\r\n# Linux/macOS\r\n./picgen.sh\r\n\r\n# Windows\r\npicgen.bat\r\n```\r\n\r\nThe scripts automatically:\r\n- Download PlantUML.jar if needed\r\n- Install Graphviz (required for PNG generation)\r\n- Test the setup before conversion\r\n- Convert all .puml files to PNG images\r\n\r\n**Note**: The script automatically handles Graphviz installation and testing to resolve the \"Dot executable does not exist\" error.\r\n\r\n## Configuration\r\n\r\nCreate a `config.json` to customize analysis and output. Minimal example:\r\n\r\n```json\r\n{\r\n \"project_name\": \"my_project\",\r\n \"source_folders\": [\"./src\"],\r\n \"output_dir\": \"./output\"\r\n}\r\n```\r\n\r\nRun with a config file:\r\n\r\n```bash\r\nc2puml --config config.json\r\n# or (merges all .json files in the current directory)\r\nc2puml\r\n```\r\n\r\nFor full examples (file-specific include filters, include depth, formatting, and the transformation system), see the Configuration Guide: [docs/configuration.md](docs/configuration.md).\r\n\r\n## Generated Output\r\n\r\nThe tool creates PlantUML diagrams showing:\r\n- Source files with functions, structs, enums, unions\r\n- Header files with declarations\r\n- Include relationships between files\r\n- Typedef relationships with enhanced UML stereotypes\r\n- Color-coded elements (source, headers, typedefs)\r\n- Dynamic visibility detection (public/private based on header presence)\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**\"Command 'c2puml' not found\"**\r\n- **Solution**: Install the package with `pip install -e .`\r\n- **Alternative**: Use the standalone script: `python3 main.py --config config.json`\r\n\r\n**\"Module 'c2puml' not found\"**\r\n- **Solution**: Ensure you're in the project root directory and the `src/` folder exists\r\n- **Alternative**: Use the standalone script which handles path setup automatically\r\n\r\n**\"Permission denied\" errors**\r\n- **Solution**: Use the standalone script which doesn't require installation: `python3 main.py`\r\n\r\n**\"Dot executable does not exist\" (PlantUML PNG generation)**\r\n- **Solution**: Install Graphviz or use the provided scripts: `./scripts/picgen.sh` or `scripts/picgen.bat`\r\n\r\n### Getting Help\r\n\r\n- **Quick Test**: Try the standalone script first: `python3 main.py --config tests/example/config.json`\r\n- **Development**: Use the debug script: `python scripts/debug.py`\r\n- **Examples**: Run the example workflow: `./scripts/run_example.sh` or `scripts/run_example.bat`\r\n\r\n## License\r\n\r\nMIT License\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert C/C++ code to PlantUML diagrams with advanced filtering and transformation capabilities",
"version": "2025.9.9",
"project_urls": {
"Documentation": "https://fischerjooo.github.io/c2puml",
"Download TAR.GZ": "https://github.com/fischerjooo/c2puml/archive/refs/heads/release.tar.gz",
"Download ZIP": "https://github.com/fischerjooo/c2puml/archive/refs/heads/release.zip",
"Homepage": "https://github.com/fischerjooo/c2puml",
"Issues": "https://github.com/fischerjooo/c2puml/issues",
"Repository": "https://github.com/fischerjooo/c2puml"
},
"split_keywords": [
"c",
" cpp",
" plantuml",
" uml",
" diagram",
" code-generation",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "509fcaa72e673d32c22c6199430c8b9f90f78d33f903a870ae6e802fa1752cf0",
"md5": "c9a05727c7df589086e344efc1f1fe99",
"sha256": "f3428f34e783e75c0beda5b7fee3a241c731769468c9059777b400282ba79f54"
},
"downloads": -1,
"filename": "c2puml-2025.9.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9a05727c7df589086e344efc1f1fe99",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 74972,
"upload_time": "2025-09-10T11:37:07",
"upload_time_iso_8601": "2025-09-10T11:37:07.003127Z",
"url": "https://files.pythonhosted.org/packages/50/9f/caa72e673d32c22c6199430c8b9f90f78d33f903a870ae6e802fa1752cf0/c2puml-2025.9.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3f15a28ebe68af4113e835973b40c6e664bef265e7f640f00059457be5c5be46",
"md5": "7cbb8c0d4c28d554d87d79dd070b4c3a",
"sha256": "18339134207b9e21091764107e29def54c27b5fd96b722e3aa2befb3612065fb"
},
"downloads": -1,
"filename": "c2puml-2025.9.9.tar.gz",
"has_sig": false,
"md5_digest": "7cbb8c0d4c28d554d87d79dd070b4c3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 70297,
"upload_time": "2025-09-10T11:37:08",
"upload_time_iso_8601": "2025-09-10T11:37:08.572974Z",
"url": "https://files.pythonhosted.org/packages/3f/15/a28ebe68af4113e835973b40c6e664bef265e7f640f00059457be5c5be46/c2puml-2025.9.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 11:37:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fischerjooo",
"github_project": "c2puml",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "c2puml"
}
JSON
