llvm-project

1
#!/usr/bin/env python3
2
# A tool to parse the output of `llvm-bolt --help-hidden` and update the
3
# documentation in CommandLineArgumentReference.md automatically.
4
# Run from the directory in which this file is located to update the docs.
5

6
import subprocess
7
from textwrap import wrap
8

9
LINE_LIMIT = 80
10

11

12
def wrap_text(text, indent, limit=LINE_LIMIT):
13
    wrapped_lines = wrap(text, width=limit - len(indent))
14
    wrapped_text = ("\n" + indent).join(wrapped_lines)
15
    return wrapped_text
16

17

18
def add_info(sections, section, option, description):
19
    indent = "  "
20
    wrapped_description = "\n".join(
21
        [
22
            wrap_text(line, indent) if len(line) > LINE_LIMIT else line
23
            for line in description
24
        ]
25
    )
26
    sections[section].append((option, indent + wrapped_description))
27

28

29
def parse_bolt_options(output):
30
    section_headers = [
31
        "Generic options:",
32
        "Output options:",
33
        "BOLT generic options:",
34
        "BOLT optimization options:",
35
        "BOLT options in relocation mode:",
36
        "BOLT instrumentation options:",
37
        "BOLT printing options:",
38
    ]
39

40
    sections = {key: [] for key in section_headers}
41
    current_section, prev_section = None, None
42
    option, description = None, []
43

44
    for line in output.split("\n"):
45
        cleaned_line = line.strip()
46

47
        if cleaned_line.casefold() in map(str.casefold, section_headers):
48
            if prev_section != None:  # Save last option from prev section
49
                add_info(sections, current_section, option, description)
50
                option, description = None, []
51

52
            cleaned_line = cleaned_line.split()
53
            # Apply lowercase to all words except the first one
54
            cleaned_line = [cleaned_line[0]] + [
55
                word.lower() for word in cleaned_line[1:]
56
            ]
57
            # Join the words back together into a string
58
            cleaned_line = " ".join(cleaned_line)
59

60
            current_section = cleaned_line
61
            prev_section = current_section
62
            continue
63

64
        if cleaned_line.startswith("-"):
65
            if option and description:
66
                # Join description lines, adding an extra newline for
67
                # sub-options that start with '='
68
                add_info(sections, current_section, option, description)
69
                option, description = None, []
70

71
            parts = cleaned_line.split("  ", 1)
72
            if len(parts) > 1:
73
                option = parts[0].strip()
74
                descr = parts[1].strip()
75
                descr = descr[2].upper() + descr[3:]
76
                description = [descr]
77
                if option.startswith("--print") or option.startswith("--time"):
78
                    current_section = "BOLT printing options:"
79
                elif prev_section != None:
80
                    current_section = prev_section
81
            continue
82

83
        if cleaned_line.startswith("="):
84
            parts = cleaned_line.split(maxsplit=1)
85
            # Split into two parts: sub-option and description
86
            if len(parts) == 2:
87
                # Rejoin with a single space
88
                cleaned_line = parts[0] + " " + parts[1].rstrip()
89
            description.append(cleaned_line)
90
        elif cleaned_line:  # Multiline description continuation
91
            description.append(cleaned_line)
92

93
    add_info(sections, current_section, option, description)
94
    return sections
95

96

97
def generate_markdown(sections):
98
    markdown_lines = [
99
        "# BOLT - a post-link optimizer developed to speed up large applications\n",
100
        "## SYNOPSIS\n",
101
        "`llvm-bolt <executable> [-o outputfile] <executable>.bolt "
102
        "[-data=perf.fdata] [options]`\n",
103
        "## OPTIONS",
104
    ]
105

106
    for section, options in sections.items():
107
        markdown_lines.append(f"\n### {section}")
108
        if section == "BOLT instrumentation options:":
109
            markdown_lines.append(
110
                f"\n`llvm-bolt <executable> -instrument"
111
                " [-o outputfile] <instrumented-executable>`"
112
            )
113
        for option, desc in options:
114
            markdown_lines.append(f"\n- `{option}`\n")
115
            # Split description into lines to handle sub-options
116
            desc_lines = desc.split("\n")
117
            for line in desc_lines:
118
                if line.startswith("="):
119
                    # Sub-option: correct formatting with bullet
120
                    sub_option, sub_desc = line[1:].split(" ", 1)
121
                    markdown_lines.append(f"  - `{sub_option}`: {sub_desc[4:]}")
122
                else:
123
                    # Regular line of description
124
                    if line[2:].startswith("<"):
125
                        line = line.replace("<", "").replace(">", "")
126
                    markdown_lines.append(f"{line}")
127

128
    return "\n".join(markdown_lines)
129

130

131
def main():
132
    try:
133
        help_output = subprocess.run(
134
            ["llvm-bolt", "--help-hidden"], capture_output=True, text=True, check=True
135
        ).stdout
136
    except subprocess.CalledProcessError as e:
137
        print("Failed to execute llvm-bolt --help:")
138
        print(e)
139
        return
140

141
    sections = parse_bolt_options(help_output)
142
    markdown = generate_markdown(sections)
143

144
    with open("CommandLineArgumentReference.md", "w") as md_file:
145
        md_file.write(markdown)
146

147

148
if __name__ == "__main__":
149
    main()
150