0
# Command Line Interface
1

2
Complete command-line interface with extensive options for format selection, threshold configuration, theming, and output control. The CLI provides access to all gprof2dot functionality through a comprehensive set of command-line arguments.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
Primary command-line interface function that orchestrates the entire profiling workflow from input parsing to DOT output generation.
9

10
```python { .api }
11
def main(argv=sys.argv[1:]):
12
    """
13
    Main entry point for command-line interface.
14
    
15
    Args:
16
        argv (list): Command line arguments (defaults to sys.argv[1:])
17
        
18
    Returns:
19
        int: Exit code (0 for success, non-zero for failure)
20
    """
21
```
22

23
### Command Line Options
24

25
The CLI supports the following command-line options:
26

27
#### Input/Output Options
28

29
```bash
30
# Specify input file(s)
31
gprof2dot [file1] [file2] ...
32

33
# Specify output file (default: stdout)
34
gprof2dot -o output.dot input_profile
35
gprof2dot --output=output.dot input_profile
36
```
37

38
#### Format Selection
39

40
```bash
41
# Specify input format (default: prof)
42
gprof2dot -f FORMAT input_profile
43
gprof2dot --format=FORMAT input_profile
44

45
# Supported formats:
46
# axe, callgrind, collapse, dtrace, hprof, json,
47
# oprofile, perf, prof, pstats, sleepy, sysprof, xperf
48
```
49

50
#### Threshold Configuration
51

52
```bash
53
# Set node threshold (eliminate nodes below percentage, default: 0.5)
54
gprof2dot -n PERCENTAGE input_profile
55
gprof2dot --node-thres=PERCENTAGE input_profile
56

57
# Set edge threshold (eliminate edges below percentage, default: 0.1)  
58
gprof2dot -e PERCENTAGE input_profile
59
gprof2dot --edge-thres=PERCENTAGE input_profile
60
```
61

62
#### Visualization Options
63

64
```bash
65
# Select color theme (default: color)
66
gprof2dot -c THEME input_profile
67
gprof2dot --colormap=THEME input_profile
68

69
# Available themes: color, pink, gray, bw, print
70

71
# Strip function parameters and template arguments from C++ names
72
gprof2dot -s input_profile
73
gprof2dot --strip input_profile
74
```
75

76
#### Advanced Options
77

78
```bash
79
# Set total time calculation method (for perf format)
80
gprof2dot --total=METHOD input_profile
81

82
# Methods: callratios (default), callstacks
83

84
# Control function name stripping
85
gprof2dot --strip input_profile
86

87
# Wrap long lines in labels
88
gprof2dot -w input_profile
89
gprof2dot --wrap input_profile
90

91
# Specify node labeling
92
gprof2dot -l LABELS input_profile  
93
gprof2dot --labels=LABELS input_profile
94
```
95

96
#### Help and Information
97

98
```bash
99
# Show help message
100
gprof2dot -h
101
gprof2dot --help
102

103
# Show version information
104
gprof2dot --version
105
```
106

107
## Command Line Usage Examples
108

109
### Basic Usage
110

111
```bash
112
# Parse Python pstats and output DOT to stdout
113
gprof2dot -f pstats profile.stats
114

115
# Parse Valgrind callgrind output
116
gprof2dot -f callgrind callgrind.out.1234
117

118
# Parse and save to file
119
gprof2dot -f perf -o profile.dot perf_output.txt
120
```
121

122
### Complete Pipeline Examples
123

124
```bash
125
# Python profiling pipeline
126
python -m cProfile -o profile.stats my_script.py
127
gprof2dot -f pstats profile.stats | dot -Tpng -o profile.png
128

129
# Valgrind callgrind pipeline  
130
valgrind --tool=callgrind ./my_program
131
gprof2dot -f callgrind callgrind.out.* | dot -Tsvg -o profile.svg
132

133
# Linux perf pipeline
134
perf record -g ./my_program
135
perf script | gprof2dot -f perf | dot -Tpdf -o profile.pdf
136
```
137

138
### Threshold and Filtering
139

140
```bash
141
# Show only significant nodes and edges
142
gprof2dot -f pstats -n 2.0 -e 1.0 profile.stats
143

144
# Very detailed view (low thresholds)
145
gprof2dot -f callgrind -n 0.1 -e 0.05 callgrind.out
146

147
# High-level overview (high thresholds)  
148
gprof2dot -f perf -n 5.0 -e 2.0 perf.out
149
```
150

151
### Theme and Visualization Options
152

153
```bash
154
# Use different color themes
155
gprof2dot -f pstats -c pink profile.stats
156
gprof2dot -f pstats -c gray profile.stats  
157
gprof2dot -f pstats -c bw profile.stats
158
gprof2dot -f pstats -c print profile.stats
159

160
# Strip function name decorations
161
gprof2dot -f pstats -s profile.stats      # Strip C++ decorations
162
```
163

164
### Advanced Processing
165

166
```bash
167
# Perf with callstacks method
168
gprof2dot -f perf --total=callstacks perf.out
169

170
# Custom labeling
171
gprof2dot -f pstats -l "name,total_time" profile.stats
172

173
# Wrap long function names  
174
gprof2dot -f callgrind -w callgrind.out
175

176
# Strip common prefixes from function names
177
gprof2dot -f hprof --strip java_profile.hprof
178
```
179

180
### Multiple Input Files
181

182
```bash
183
# Process multiple profile files
184
gprof2dot -f pstats profile1.stats profile2.stats profile3.stats
185

186
# Combine different profiler outputs (if compatible)
187
gprof2dot -f json profile1.json profile2.json
188
```
189

190
### Output Format Integration
191

192
```bash
193
# Generate PNG with custom DPI
194
gprof2dot -f pstats profile.stats | dot -Tpng -Gdpi=300 -o profile.png
195

196
# Generate interactive SVG
197
gprof2dot -f callgrind callgrind.out | dot -Tsvg -o profile.svg
198

199
# Generate PostScript for printing
200
gprof2dot -f perf -c print perf.out | dot -Tps -o profile.ps
201

202
# Generate PDF with specific page size
203
gprof2dot -f pstats profile.stats | dot -Tpdf -Gsize="11,8.5" -o profile.pdf
204
```
205

206
## Integration Examples
207

208
### Shell Script Integration
209

210
```bash
211
#!/bin/bash
212
# Profile analysis script
213

214
PROFILE_FILE="$1"
215
FORMAT="$2"
216
OUTPUT_DIR="${3:-./profiles}"
217

218
mkdir -p "$OUTPUT_DIR"
219

220
# Generate multiple formats
221
gprof2dot -f "$FORMAT" "$PROFILE_FILE" | dot -Tpng -o "$OUTPUT_DIR/profile.png"
222
gprof2dot -f "$FORMAT" "$PROFILE_FILE" | dot -Tsvg -o "$OUTPUT_DIR/profile.svg"  
223
gprof2dot -f "$FORMAT" -c print "$PROFILE_FILE" | dot -Tpdf -o "$OUTPUT_DIR/profile.pdf"
224

225
echo "Profiles generated in $OUTPUT_DIR"
226
```
227

228
### Python Script Integration
229

230
```python
231
#!/usr/bin/env python3
232
import subprocess
233
import sys
234
import os
235

236
def generate_profile_visualization(input_file, format_type, output_base):
237
    """Generate profile visualization using gprof2dot."""
238
    
239
    # Generate DOT
240
    cmd = ['gprof2dot', '-f', format_type, input_file]
241
    dot_output = subprocess.check_output(cmd, text=True)
242
    
243
    # Save DOT file
244
    with open(f"{output_base}.dot", 'w') as f:
245
        f.write(dot_output)
246
    
247
    # Generate PNG
248
    subprocess.run([
249
        'dot', '-Tpng', '-o', f"{output_base}.png", f"{output_base}.dot"
250
    ])
251
    
252
    print(f"Generated {output_base}.png and {output_base}.dot")
253

254
if __name__ == "__main__":
255
    if len(sys.argv) != 4:
256
        print("Usage: script.py <input_file> <format> <output_base>")
257
        sys.exit(1)
258
    
259
    generate_profile_visualization(sys.argv[1], sys.argv[2], sys.argv[3])
260
```
261

262
### Makefile Integration
263

264
```makefile
265
# Profile visualization targets
266
PROFILE_FORMATS = png svg pdf
267
GPROF2DOT_OPTS = -n 1.0 -e 0.5
268

269
profile.dot: profile.stats  
270
	gprof2dot -f pstats $(GPROF2DOT_OPTS) $< > $@
271

272
%.png: %.dot
273
	dot -Tpng -o $@ $<
274

275
%.svg: %.dot  
276
	dot -Tsvg -o $@ $<
277

278
%.pdf: %.dot
279
	dot -Tpdf -o $@ $<
280

281
profile-all: $(addprefix profile., $(PROFILE_FORMATS))
282

283
clean-profiles:
284
	rm -f profile.dot profile.png profile.svg profile.pdf
285

286
.PHONY: profile-all clean-profiles
287
```