<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/00-test.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/02-puml-to-png.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/01-test-and-coverage.yml)
[](https://github.com/fischerjooo/c2puml/actions/workflows/03-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/c5/99/8fb27f2889b72ecdc654803014db86ed47c58efbb7de0bca28fd72b92470/c2puml-2025.9.14.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">c2puml - C to PlantUML Converter</h1>\n<p align=\"center\">\n <img src=\"docs/c2puml.jpg\" alt=\"C 2 Puml\" width=\"128\"/>\n</p>\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.\n\n## Status\n[](https://github.com/fischerjooo/c2puml/actions/workflows/00-test.yml)\n[](https://github.com/fischerjooo/c2puml/actions/workflows/02-puml-to-png.yml)\n[](https://github.com/fischerjooo/c2puml/actions/workflows/01-test-and-coverage.yml)\n[](https://github.com/fischerjooo/c2puml/actions/workflows/03-deploy-website.yml)\n\n## Reports\n\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\n- [\ud83d\udcdd Test Summary](https://fischerjooo.github.io/c2puml/artifacts/test_reports/test_summary.html) - Test execution summary and statistics\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\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\n\n## Documentation\n\n- [\ud83d\udcd6 Specification](https://github.com/fischerjooo/c2puml/blob/main/docs/specification.md) - Complete technical specification and architecture documentation\n- [\ud83c\udfa8 PlantUML Template](https://github.com/fischerjooo/c2puml/blob/main/docs/puml_template.md) - PlantUML formatting template and diagram structure rules\n- [\u2699\ufe0f Configuration Guide](https://github.com/fischerjooo/c2puml/blob/main/docs/configuration.md) - Detailed config.json reference and examples\n\n## Releases\n\n- [\ud83d\udce6 Download ZIP](https://github.com/fischerjooo/c2puml/archive/refs/heads/release.zip) - Download the latest release as ZIP archive\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\n\n## Features\n\n- **C/C++ Parsing**: Comprehensive tokenization-based parsing with preprocessor handling and conditional compilation support\n- **Project Analysis**: Analyzes entire C/C++ projects with recursive directory scanning and configurable include depth processing\n- **PlantUML Generation**: Creates organized PlantUML diagrams with proper UML notation and relationship visualization\n- **Configuration System**: Flexible filtering and transformation capabilities with file-specific settings\n- **Enhanced UML Stereotypes**: Uses specific stereotypes for different typedef types (<<enumeration>>, <<struct>>, <<union>>, <<typedef>>)\n- **Smart Visibility Detection**: Automatically determines public/private visibility based on header file declarations\n\n## Installation\n\n### Option 1: Install as Python Package (Recommended)\n\n```bash\ngit clone https://github.com/fischerjooo/c2puml.git\ncd c2puml\npython3 -m pip install -e .\n```\n\n### Option 2: Use Standalone Script (No Installation Required)\n\nIf you prefer not to install the package, you can use the standalone script directly:\n\n```bash\ngit clone https://github.com/fischerjooo/c2puml.git\ncd c2puml\n# No installation needed - just run the script directly\npython3 main.py --config tests/example/config.json\n```\n\n**Prerequisites for standalone usage:**\n- Python 3.7 or later\n- The complete c2puml source code (including the `src/` directory)\n\n## Quick Start\n\n### Basic Usage\n\n#### Using Installed Package\n\n```bash\n# Full workflow: Parse \u2192 Transform \u2192 Generate diagrams\nc2puml --config tests/example/config.json\n\n# Using current directory configuration (merges all .json files)\nc2puml\n\n# Individual steps\nc2puml --config tests/example/config.json parse # Step 1: Parse only\nc2puml --config tests/example/config.json transform # Step 2: Transform only\nc2puml --config tests/example/config.json generate # Step 3: Generate only\n\n# With verbose output for debugging\nc2puml --config tests/example/config.json --verbose\n\n# Alternative module syntax\npython3 -m c2puml.main --config tests/example/config.json\n```\n\n#### Using Standalone Script (No Installation)\n\n```bash\n# Full workflow: Parse \u2192 Transform \u2192 Generate diagrams\npython3 main.py --config tests/example/config.json\n\n# Using current directory configuration (merges all .json files)\npython3 main.py\n\n# Individual steps\npython3 main.py --config tests/example/config.json parse # Step 1: Parse only\npython3 main.py --config tests/example/config.json transform # Step 2: Transform only\npython3 main.py --config tests/example/config.json generate # Step 3: Generate only\n\n# With verbose output for debugging\npython3 main.py --config tests/example/config.json --verbose\n```\n\n**Note**: Both methods provide identical functionality. Choose the one that best fits your workflow.\n\n\n### Generate PNG Images\n\n```bash\n# Linux/macOS\n./picgen.sh\n\n# Windows\npicgen.bat\n```\n\nThe scripts automatically:\n- Download PlantUML.jar if needed\n- Install Graphviz (required for PNG generation)\n- Test the setup before conversion\n- Convert all .puml files to PNG images\n\n**Note**: The script automatically handles Graphviz installation and testing to resolve the \"Dot executable does not exist\" error.\n\n## Configuration\n\nCreate a `config.json` to customize analysis and output. Minimal example:\n\n```json\n{\n \"project_name\": \"my_project\",\n \"source_folders\": [\"./src\"],\n \"output_dir\": \"./output\"\n}\n```\n\nRun with a config file:\n\n```bash\nc2puml --config config.json\n# or (merges all .json files in the current directory)\nc2puml\n```\n\nFor full examples (file-specific include filters, include depth, formatting, and the transformation system), see the Configuration Guide: [docs/configuration.md](docs/configuration.md).\n\n## Generated Output\n\nThe tool creates PlantUML diagrams showing:\n- Source files with functions, structs, enums, unions\n- Header files with declarations\n- Include relationships between files\n- Typedef relationships with enhanced UML stereotypes\n- Color-coded elements (source, headers, typedefs)\n- Dynamic visibility detection (public/private based on header presence)\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Command 'c2puml' not found\"**\n- **Solution**: Install the package with `pip install -e .`\n- **Alternative**: Use the standalone script: `python3 main.py --config config.json`\n\n**\"Module 'c2puml' not found\"**\n- **Solution**: Ensure you're in the project root directory and the `src/` folder exists\n- **Alternative**: Use the standalone script which handles path setup automatically\n\n**\"Permission denied\" errors**\n- **Solution**: Use the standalone script which doesn't require installation: `python3 main.py`\n\n**\"Dot executable does not exist\" (PlantUML PNG generation)**\n- **Solution**: Install Graphviz or use the provided scripts: `./scripts/picgen.sh` or `scripts/picgen.bat`\n\n### Getting Help\n\n- **Quick Test**: Try the standalone script first: `python3 main.py --config tests/example/config.json`\n- **Development**: Use the debug script: `python scripts/debug.py`\n- **Examples**: Run the example workflow: `./scripts/run_example.sh` or `scripts/run_example.bat`\n\n## License\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert C/C++ code to PlantUML diagrams with advanced filtering and transformation capabilities",
"version": "2025.9.14.2",
"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": "9e30593d0af7113856b79cdd985277a9c09c48fac1616a1f440fbcd661503f70",
"md5": "8dc15551e989cf4dbd8a0ab9707e6fc5",
"sha256": "80b51cc14caabbbab97ff91e02110fae4eaf5fafd04a84f3fb3932b2789654f1"
},
"downloads": -1,
"filename": "c2puml-2025.9.14.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8dc15551e989cf4dbd8a0ab9707e6fc5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 77327,
"upload_time": "2025-09-14T18:30:02",
"upload_time_iso_8601": "2025-09-14T18:30:02.531739Z",
"url": "https://files.pythonhosted.org/packages/9e/30/593d0af7113856b79cdd985277a9c09c48fac1616a1f440fbcd661503f70/c2puml-2025.9.14.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5998fb27f2889b72ecdc654803014db86ed47c58efbb7de0bca28fd72b92470",
"md5": "0ec7854ab93df5e33c996c9bae8482f4",
"sha256": "24652031b99811e76b5ef3de55d2d1626be53c8e3356b824e632d139a256e97a"
},
"downloads": -1,
"filename": "c2puml-2025.9.14.2.tar.gz",
"has_sig": false,
"md5_digest": "0ec7854ab93df5e33c996c9bae8482f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 75123,
"upload_time": "2025-09-14T18:30:03",
"upload_time_iso_8601": "2025-09-14T18:30:03.593683Z",
"url": "https://files.pythonhosted.org/packages/c5/99/8fb27f2889b72ecdc654803014db86ed47c58efbb7de0bca28fd72b92470/c2puml-2025.9.14.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 18:30:03",
"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
