cmake-format使用教程

1. 安装

cmake-format是python项目，用pip来安装。

$ pip install cmake-format

2. 基础示例用法

# 1. 格式化input_file，输出到标准输出流
$ cmake-format <input_file>

# 2. 格式化input_file，输出到文件output_file
$ cmake-format <input_file> [-o <output_file>]

# 3. 格式化input_file，对intput_file进行修改
$ cmake-format <input_file> -i
## 或
$ cmake-format <input_file> --in-place

# 4. 格式化input_file，根据配置文件
$ cmake-format <input_file> [-c <config>]

3. 配置文件

默认会对配置文件进行搜索。
例如：~/.cmake-format.json。

用下面的命令打印 一份json格式的配置文件模板，基于它进行修改即可

$ cmake-format --dump-config json

4. 部分配置项说明

1. tab_size
   • tab所占空格数
2. line_width
   • 最大长度
3. enable_markup
   • 是否重新排列注释。
4. dangle_paren
   • 结尾括号单独成行（当一行放不下时）

5. 配置文件示例

{
    "_help_parse": "Options affecting listfile parsing",
    "parse": {
        "_help_additional_commands": [
            "Specify structure for custom cmake functions"
        ],
        "additional_commands": {
            "foo": {
                "flags": [
                    "BAR",
                    "BAZ"
                ],
                "kwargs": {
                    "HEADERS": "*",
                    "SOURCES": "*",
                    "DEPENDS": "*"
                }
            }
        },
        "_help_override_spec": [
            "Override configurations per-command where available"
        ],
        "override_spec": {},
        "_help_vartags": [
            "Specify variable tags."
        ],
        "vartags": [],
        "_help_proptags": [
            "Specify property tags."
        ],
        "proptags": []
    },
    "_help_format": "Options affecting formatting.",
    "format": {
        "_help_disable": [
            "Disable formatting entirely, making cmake-format a no-op"
        ],
        "disable": false,
        "_help_line_width": [
            "How wide to allow formatted cmake files"
        ],
        "line_width": 100,
        "_help_tab_size": [
            "How many spaces to tab for indent"
        ],
        "tab_size": 4,
        "_help_use_tabchars": [
            "If true, lines are indented using tab characters (utf-8",
            "0x09) instead of  space characters (utf-8 0x20).",
            "In cases where the layout would require a fractional tab",
            "character, the behavior of the  fractional indentation is",
            "governed by "
        ],
        "use_tabchars": false,
        "_help_fractional_tab_policy": [
            "If  is True, then the value of this variable",
            "indicates how fractional indentions are handled during",
            "whitespace replacement. If set to 'use-space', fractional",
            "indentation is left as spaces (utf-8 0x20). If set to",
            "`round-up` fractional indentation is replaced with a single",
            "tab character (utf-8 0x09) effectively shifting the column",
            "to the next tabstop"
        ],
        "fractional_tab_policy": "use-space",
        "_help_max_subgroups_hwrap": [
            "If an argument group contains more than this many sub-groups",
            "(parg or kwarg groups) then force it to a vertical layout."
        ],
        "max_subgroups_hwrap": 2,
        "_help_max_pargs_hwrap": [
            "If a positional argument group contains more than this many",
            "arguments, then force it to a vertical layout."
        ],
        "max_pargs_hwrap": 6,
        "_help_max_rows_cmdline": [
            "If a cmdline positional group consumes more than this many",
            "lines without nesting, then invalidate the layout (and nest)"
        ],
        "max_rows_cmdline": 2,
        "_help_separate_ctrl_name_with_space": [
            "If true, separate flow control names from their parentheses",
            "with a space"
        ],
        "separate_ctrl_name_with_space": false,
        "_help_separate_fn_name_with_space": [
            "If true, separate function names from parentheses with a",
            "space"
        ],
        "separate_fn_name_with_space": false,
        "_help_dangle_parens": [
            "If a statement is wrapped to more than one line, than dangle",
            "the closing parenthesis on its own line."
        ],
        "dangle_parens": true,
        "_help_dangle_align": [
            "If the trailing parenthesis must be 'dangled' on its on",
            "line, then align it to this reference: `prefix`: the start",
            "of the statement,  `prefix-indent`: the start of the",
            "statement, plus one indentation  level, `child`: align to",
            "the column of the arguments"
        ],
        "dangle_align": "prefix",
        "_help_min_prefix_chars": [
            "If the statement spelling length (including space and",
            "parenthesis) is smaller than this amount, then force reject",
            "nested layouts."
        ],
        "min_prefix_chars": 4,
        "_help_max_prefix_chars": [
            "If the statement spelling length (including space and",
            "parenthesis) is larger than the tab width by more than this",
            "amount, then force reject un-nested layouts."
        ],
        "max_prefix_chars": 10,
        "_help_max_lines_hwrap": [
            "If a candidate layout is wrapped horizontally but it exceeds",
            "this many lines, then reject the layout."
        ],
        "max_lines_hwrap": 2,
        "_help_line_ending": [
            "What style line endings to use in the output."
        ],
        "line_ending": "unix",
        "_help_command_case": [
            "Format command names consistently as 'lower' or 'upper' case"
        ],
        "command_case": "canonical",
        "_help_keyword_case": [
            "Format keywords consistently as 'lower' or 'upper' case"
        ],
        "keyword_case": "unchanged",
        "_help_always_wrap": [
            "A list of command names which should always be wrapped"
        ],
        "always_wrap": [],
        "_help_enable_sort": [
            "If true, the argument lists which are known to be sortable",
            "will be sorted lexicographicall"
        ],
        "enable_sort": true,
        "_help_autosort": [
            "If true, the parsers may infer whether or not an argument",
            "list is sortable (without annotation)."
        ],
        "autosort": false,
        "_help_require_valid_layout": [
            "By default, if cmake-format cannot successfully fit",
            "everything into the desired linewidth it will apply the",
            "last, most aggressive attempt that it made. If this flag is",
            "True, however, cmake-format will print error, exit with non-",
            "zero status code, and write-out nothing"
        ],
        "require_valid_layout": false,
        "_help_layout_passes": [
            "A dictionary mapping layout nodes to a list of wrap",
            "decisions. See the documentation for more information."
        ],
        "layout_passes": {}
    },
    "_help_markup": "Options affecting comment reflow and formatting.",
    "markup": {
        "_help_bullet_char": [
            "What character to use for bulleted lists"
        ],
        "bullet_char": "*",
        "_help_enum_char": [
            "What character to use as punctuation after numerals in an",
            "enumerated list"
        ],
        "enum_char": ".",
        "_help_first_comment_is_literal": [
            "If comment markup is enabled, don't reflow the first comment",
            "block in each listfile. Use this to preserve formatting of",
            "your copyright/license statements."
        ],
        "first_comment_is_literal": false,
        "_help_literal_comment_pattern": [
            "If comment markup is enabled, don't reflow any comment block",
            "which matches this (regex) pattern. Default is `None`",
            "(disabled)."
        ],
        "literal_comment_pattern": null,
        "_help_fence_pattern": [
            "Regular expression to match preformat fences in comments",
            "default= ``r'^\\s*([`~]{3}[`~]*)(.*)$'``"
        ],
        "fence_pattern": "^\\s*([`~]{3}[`~]*)(.*)$",
        "_help_ruler_pattern": [
            "Regular expression to match rulers in comments default=",
            "``r'^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$'``"
        ],
        "ruler_pattern": "^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$",
        "_help_explicit_trailing_pattern": [
            "If a comment line matches starts with this pattern then it",
            "is explicitly a trailing comment for the preceding argument.",
            "Default is '#<'"
        ],
        "explicit_trailing_pattern": "#<",
        "_help_hashruler_min_length": [
            "If a comment line starts with at least this many consecutive",
            "hash characters, then don't lstrip() them off. This allows",
            "for lazy hash rulers where the first hash char is not",
            "separated by space"
        ],
        "hashruler_min_length": 10,
        "_help_canonicalize_hashrulers": [
            "If true, then insert a space between the first hash char and",
            "remaining hash chars in a hash ruler, and normalize its",
            "length to fill the column"
        ],
        "canonicalize_hashrulers": true,
        "_help_enable_markup": [
            "enable comment markup parsing and reflow"
        ],
        "enable_markup": false
    },
    "_help_lint": "Options affecting the linter",
    "lint": {
        "_help_disabled_codes": [
            "a list of lint codes to disable"
        ],
        "disabled_codes": [],
        "_help_function_pattern": [
            "regular expression pattern describing valid function names"
        ],
        "function_pattern": "[0-9a-z_]+",
        "_help_macro_pattern": [
            "regular expression pattern describing valid macro names"
        ],
        "macro_pattern": "[0-9A-Z_]+",
        "_help_global_var_pattern": [
            "regular expression pattern describing valid names for",
            "variables with global (cache) scope"
        ],
        "global_var_pattern": "[A-Z][0-9A-Z_]+",
        "_help_internal_var_pattern": [
            "regular expression pattern describing valid names for",
            "variables with global scope (but internal semantic)"
        ],
        "internal_var_pattern": "_[A-Z][0-9A-Z_]+",
        "_help_local_var_pattern": [
            "regular expression pattern describing valid names for",
            "variables with local scope"
        ],
        "local_var_pattern": "[a-z][a-z0-9_]+",
        "_help_private_var_pattern": [
            "regular expression pattern describing valid names for",
            "privatedirectory variables"
        ],
        "private_var_pattern": "_[0-9a-z_]+",
        "_help_public_var_pattern": [
            "regular expression pattern describing valid names for public",
            "directory variables"
        ],
        "public_var_pattern": "[A-Z][0-9A-Z_]+",
        "_help_argument_var_pattern": [
            "regular expression pattern describing valid names for",
            "function/macro arguments and loop variables."
        ],
        "argument_var_pattern": "[a-z][a-z0-9_]+",
        "_help_keyword_pattern": [
            "regular expression pattern describing valid names for",
            "keywords used in functions or macros"
        ],
        "keyword_pattern": "[A-Z][0-9A-Z_]+",
        "_help_max_conditionals_custom_parser": [
            "In the heuristic for C0201, how many conditionals to match",
            "within a loop in before considering the loop a parser."
        ],
        "max_conditionals_custom_parser": 2,
        "_help_min_statement_spacing": [
            "Require at least this many newlines between statements"
        ],
        "min_statement_spacing": 1,
        "_help_max_statement_spacing": [
            "Require no more than this many newlines between statements"
        ],
        "max_statement_spacing": 2,
        "max_returns": 6,
        "max_branches": 12,
        "max_arguments": 5,
        "max_localvars": 15,
        "max_statements": 50
    },
    "_help_encode": "Options affecting file encoding",
    "encode": {
        "_help_emit_byteorder_mark": [
            "If true, emit the unicode byte-order mark (BOM) at the start",
            "of the file"
        ],
        "emit_byteorder_mark": false,
        "_help_input_encoding": [
            "Specify the encoding of the input file. Defaults to utf-8"
        ],
        "input_encoding": "utf-8",
        "_help_output_encoding": [
            "Specify the encoding of the output file. Defaults to utf-8.",
            "Note that cmake only claims to support utf-8 so be careful",
            "when using anything else"
        ],
        "output_encoding": "utf-8"
    },
    "_help_misc": "Miscellaneous configurations options.",
    "misc": {
        "_help_per_command": [
            "A dictionary containing any per-command configuration",
            "overrides. Currently only `command_case` is supported."
        ],
        "per_command": {}
    }
}

6. 配置文件chatgpt翻译结果

{
    "_help_parse": "影响列表文件解析的选项",
    "parse": {
        "_help_additional_commands": [
            "指定自定义CMake函数的结构"
        ],
        "additional_commands": {
            "foo": {
                "flags": [
                    "BAR",
                    "BAZ"
                ],
                "kwargs": {
                    "HEADERS": "*",
                    "SOURCES": "*",
                    "DEPENDS": "*"
                }
            }
        },
        "_help_override_spec": [
            "在可用时覆盖每个命令的配置"
        ],
        "override_spec": {},
        "_help_vartags": [
            "指定变量标签"
        ],
        "vartags": [],
        "_help_proptags": [
            "指定属性标签"
        ],
        "proptags": []
    },
    "_help_format": "影响格式化的选项",
    "format": {
        "_help_disable": [
            "完全禁用格式化，使CMake-Format成为一个无操作工具"
        ],
        "disable": false,
        "_help_line_width": [
            "允许格式化的CMake文件的行宽"
        ],
        "line_width": 100,
        "_help_tab_size": [
            "用于缩进的空格数量"
        ],
        "tab_size": 4,
        "_help_use_tabchars": [
            "如果为true，则使用制表符（utf-8 0x09）而不是个空格字符（utf-8 0x20）进行缩进。在需要分数制表符的情况下，分数制表符的行为由确定"
        ],
        "use_tabchars": false,
        "_help_fractional_tab_policy": [
            "如果为True，则此变量的值指示如何处理空格替换中的分数缩进。如果设置为'use-space'，则分数缩进将保留为空格（utf-8 0x20）。如果设置为'round-up'，则分数缩进将替换为一个制表符字符（utf-8 0x09），有效地将列移到下一个制表符停止位"
        ],
        "fractional_tab_policy": "use-space",
        "_help_max_subgroups_hwrap": [
            "如果一个参数组包含多于此数量的子组（parg或kwarg组），则强制将其排列为垂直布局"
        ],
        "max_subgroups_hwrap": 2,
        "_help_max_pargs_hwrap": [
            "如果一个位置参数组包含多于此数量的参数，则强制将其排列为垂直布局"
        ],
        "max_pargs_hwrap": 6,
        "_help_max_rows_cmdline": [
            "如果一个命令行位置组消耗了超过此数量的行且没有嵌套，则使布局无效（并嵌套）"
        ],
        "max_rows_cmdline": 2,
        "_help_separate_ctrl_name_with_space": [
            "如果为true，则使用空格将流程控制名称与括号分开"
        ],
        "separate_ctrl_name_with_space": false,
        "_help_separate_fn_name_with_space": [
            "如果为true，则使用空格将函数名称与括号分开"
        ],
        "separate_fn_name_with_space": false,
        "_help_dangle_parens": [
            "如果语句被包装到多于一行，则将括号悬挂在自己的行上"
        ],
        "dangle_parens": false,
        "_help_dangle_align": [
            "如果必须在其单独的行上'悬挂'括号，那么将其与此参考对齐：'prefix'：语句的开头，'prefix-indent'：语句的开头，加上一个缩进级别，'child'：与参数的列对齐"
        ],
        "dangle_align": "prefix",
        "_help_min_prefix_chars": [
            "如果语句的拼写长度（包括空格和括号）小于此金额，则强制拒绝嵌套布局"
        ],
        "min_prefix_chars": 4,
        "_help_max_prefix_chars": [
            "如果语句的拼写长度（包括空格和括号）大于制表符宽度多于此金额，则强制拒绝非嵌套布局"
        ],
        "max_prefix_chars": 10,
        "_help_max_lines_hwrap": [
            "如果候选布局水平包装但超过此数量的行，则拒绝布局"
        ],
        "max_lines_hwrap": 2,
        "_help_line_ending": [
            "在输出中使用的行尾的样式"
        ],
        "line_ending": "unix",
        "_help_command_case": [
            "一致地格式化命令名称为'lower'或'upper' case"
        ],
        "command_case": "canonical",
        "_help_keyword_case": [
            "一致地格式化关键字为'lower'或'upper' case"
        ],
        "keyword_case": "unchanged",
        "_help_always_wrap": [
            "应始终包装的命令名称列表"
        ],
        "always_wrap": [],
        "_help_enable_sort": [
            "如果为true，将按字典顺序对已知可排序的参数列表进行排序"
        ],
        "enable_sort": true,
        "_help_autosort": [
            "如果为true，解析器可以推断参数列表是否可排序（无需注释）"
        ],
        "autosort": false,
        "_help_require_valid_layout": [
            "默认情况下，如果CMake-Format不能成功地将所有内容放入所需的行宽内，它将应用它所做的最后一个、最激进的尝试。但如果此标志设置为True，则CMake-Format将打印错误，退出并返回非零状态代码，并不写任何内容"
        ],
        "require_valid_layout": false,
        "_help_layout_passes": [
            "将布局节点映射到包装决策列表的字典。有关更多信息，请参阅文档。"
        ],
        "layout_passes": {}
    },
    "_help_markup": "影响注释的换行和格式化的选项",
    "markup": {
        "_help_bullet_char": [
            "用于项目符号列表的字符"
        ],
        "bullet_char": "*",
        "_help_enum_char": [
            "在枚举列表中数字后使用的标点符号字符"
        ],
        "enum_char": ".",
        "_help_first_comment_is_literal": [
            "如果启用注释标记（markup），则不要重新格式化每个列表文件中的第一个注释块。使用此选项保留版权或许可证声明等注释的格式"
        ],
        "first_comment_is_literal": false,
        "_help_literal_comment_pattern": [
            "如果启用注释标记（markup），则不要重新格式化与此（正则表达式）模式匹配的任何注释块。默认值为'None'（禁用）"
        ],
        "literal_comment_pattern": null,
        "_help_fence_pattern": [
            "匹配注释中的预格式化边界的正则表达式，默认值=`r'^\\s*([`~]{3}[`~]*)(.*)$'`"
        ],
        "fence_pattern": "^\\s*([`~]{3}[`~]*)(.*)$",
        "_help_ruler_pattern": [
            "匹配注释中的标尺的正则表达式，默认值=`r'^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$'`"
        ],
        "ruler_pattern": "^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$",
        "_help_explicit_trailing_pattern": [
            "如果注释行以此模式开头，那么它明确是前一个参数的尾部注释。默认值为'#<'"
        ],
        "explicit_trailing_pattern": "#<",
        "_help_hashruler_min_length": [
            "如果注释行以至少这么多连续的井字符开头，则不要将它们删除。这允许懒惰的井号标尺，其中第一个井号字符不由空格分隔"
        ],
        "hashruler_min_length": 10,
        "_help_canonicalize_hashrulers": [
            "如果为true，则在井号标尺的第一个井号字符和剩余井号字符之间插入一个空格，并将其长度规范化以填满列"
        ],
        "canonicalize_hashrulers": true,
        "_help_enable_markup": [
            "启用注释标记解析和换行"
        ],
        "enable_markup": true
    },
    "_help_lint": "影响代码审查的选项",
    "lint": {
        "_help_disabled_codes": [
            "要禁用的代码审查代码列表"
        ],
        "disabled_codes": [],
        "_help_function_pattern": [
            "描述有效函数名称的正则表达式模式"
        ],
        "function_pattern": "[0-9a-z_]+",
        "_help_macro_pattern": [
            "描述有效宏名称的正则表达式模式"
        ],
        "macro_pattern": "[0-9A-Z_]+",
        "_help_global_var_pattern": [
            "描述具有全局（缓存）范围的变量的有效名称的正则表达式模式"
        ],
        "global_var_pattern": "[A-Z][0-9A-Z_]+",
        "_help_internal_var_pattern": [
            "描述具有全局范围（但具有内部语义）的变量的有效名称的正则表达式模式"
        ],
        "internal_var_pattern": "_[A-Z][0-9A-Z_]+",
        "_help_local_var_pattern": [
            "描述具有局部范围的变量的有效名称的正则表达式模式"
        ],
        "local_var_pattern": "[a-z][a-z0-9_]+",
        "_help_private_var_pattern": [
            "描述私有目录变量的有效名称的正则表达式模式"
        ],
        "private_var_pattern": "_[0-9a-z_]+",
        "_help_public_var_pattern": [
            "描述公共目录变量的有效名称的正则表达式模式"
        ],
        "public_var_pattern": "[A-Z][0-9A-Z_]+",
        "_help_argument_var_pattern": [
            "描述函数/宏参数和循环变量的有效名称的正则表达式模式"
        ],
        "argument_var_pattern": "[a-z][a-z0-9_]+",
        "_help_keyword_pattern": [
            "描述函数或宏中使用的关键字的有效名称的正则表达式模式"
        ],
        "keyword_pattern": "[A-Z][0-9A-Z_]+",
        "_help_max_conditionals_custom_parser": [
            "在C0201的启发式方法中，在考虑将循环视为解析器之前，要匹配的条件数"
        ],
        "max_conditionals_custom_parser": 2,
        "_help_min_statement_spacing": [
            "要求语句之间至少有这么多个换行符"
        ],
        "min_statement_spacing": 1,
        "_help_max_statement_spacing": [
            "要求语句之间不超过这么多个换行符"
        ],
        "max_statement_spacing": 2,
        "max_returns": 6,
        "max_branches": 12,
        "max_arguments": 5,
        "max_localvars": 15,
        "max_statements": 50
    },
    "_help_encode": "影响文件编码的选项",
    "encode": {
        "_help_emit_byteorder_mark": [
            "如果为true，则在文件开头发出Unicode字节顺序标记（BOM）"
        ],
        "emit_byteorder_mark": false,
        "_help_input_encoding": [
            "指定输入文件的编码。默认为utf-8"
        ],
        "input_encoding": "utf-8",
        "_help_output_encoding": [
            "指定输出文件的编码。默认为utf-8。请注意，CMake仅支持utf-8，因此在使用其他编码时要小心"
        ],
        "output_encoding": "utf-8"
    },
    "_help_misc": "其他配置选项",
    "misc": {
        "_help_per_command": [
            "包含每个命令的配置覆盖的字典。目前只支持command_case。"
        ],
        "per_command": {}
    }
}