Package: cmake-format
Thecmake-formatproject provides Quality Assurance (QA) tools
forcmake:cmake-annotatecan generate pretty HTML from your listfilescmake-formatcan format your listfiles nicely so that they don’t
look like crap.cmake-lintcan check your listfiles for problemsctest-tocan parse a ctest output tree and translate it into a
more structured format (either JSON or XML).InstallationInstall frompypiusingpip:pip install cmakelangOr see theonline documentationfor additional options.IntegrationsThere is an officialvscode extensionSomeone also created asublime pluginYou can addcmake-formatto yourpre-commitconfigurationUsageusage:
cmake-format [-h]
             [--dump-config {yaml,json,python} | -i | -o OUTFILE_PATH]
             [-c CONFIG_FILE]
             infilepath [infilepath ...]

Parse cmake listfiles and format them nicely.

Formatting is configurable by providing a configuration file. The configuration
file can be in json, yaml, or python format. If no configuration file is
specified on the command line, cmake-format will attempt to find a suitable
configuration for each ``inputpath`` by checking recursively checking it's
parent directory up to the root of the filesystem. It will return the first
file it finds with a filename that matches '\.?cmake-format(.yaml|.json|.py)'.

cmake-format can spit out the default configuration for you as starting point
for customization. Run with `--dump-config [yaml|json|python]`.

positional arguments:
  infilepaths

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -l {error,warning,info,debug}, --log-level {error,warning,info,debug}
  --dump-config [{yaml,json,python}]
                        If specified, print the default configuration to
                        stdout and exit
  --dump {lex,parse,parsedb,layout,markup}
  --no-help             When used with --dump-config, will omit helptext
                        comments in the output
  --no-default          When used with --dump-config, will omit any unmodified
                        configuration value.
  -i, --in-place
  --check               Exit with status code 0 if formatting would not change
                        file contents, or status code 1 if it would
  -o OUTFILE_PATH, --outfile-path OUTFILE_PATH
                        Where to write the formatted file. Default is stdout.
  -c CONFIG_FILES [CONFIG_FILES ...], --config-files CONFIG_FILES [CONFIG_FILES ...]
                        path to configuration file(s)usage:
cmake-lint [-h]
           [--dump-config {yaml,json,python} | -o OUTFILE_PATH]
           [-c CONFIG_FILE]
           infilepath [infilepath ...]

Check cmake listfile for lint

positional arguments:
  infilepaths

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -l {error,warning,info,debug}, --log-level {error,warning,info,debug}
  --dump-config [{yaml,json,python}]
                        If specified, print the default configuration to
                        stdout and exit
  -o OUTFILE_PATH, --outfile-path OUTFILE_PATH
                        Write errors to this file. Default is stdout.
  --no-help             When used with --dump-config, will omit helptext
                        comments in the output
  --no-default          When used with --dump-config, will omit any unmodified
                        configuration value.
  --suppress-decorations
                        Suppress the file title decoration and summary
                        statistics
  -c CONFIG_FILES [CONFIG_FILES ...], --config-files CONFIG_FILES [CONFIG_FILES ...]
                        path to configuration file(s)Configurationcmake-formataccepts configuration files in yaml, json, or python format.
An example configuration file is givenin the online documentation.
Providing the structure of your custom commands will helpcmake-formatto
break them up in a pleasant way, and will helpcmake-lintdetect improper
usages of them.An example short configuration file in python format is:# -----------------------------# Options effecting formatting.# -----------------------------withsection("format"):# How wide to allow formatted cmake filesline_width=80# How many spaces to tab for indenttab_size=2# If true, separate flow control names from their parentheses with a spaceseparate_ctrl_name_with_space=False# If true, separate function names from parentheses with a spaceseparate_fn_name_with_space=False# If a statement is wrapped to more than one line, than dangle the closing# parenthesis on its own line.dangle_parens=FalseYou may specify a path to one or more configuration files with the--config-filecommand line option. Otherwise,cmake-formatwill search
the ancestry of eachinfilepathlooking for a configuration file to use.
If no configuration file is found it will use sensible defaults.A automatically detected configuration files may have any name that matches\.?cmake-format(.yaml|.json|.py).If you’d like to create a new configuration file,cmake-formatcan help
by dumping out the default configuration in your preferred format. You can runcmake-format--dump-config[yaml|json|python]to print the default
configurationstdoutand use that as a starting point.Markupcmake-formatis for the exceptionally lazy. It will even format your
comments for you. It will reflow your comment text to within the configured
line width. It also understands a very limited markup format for a couple of
common bits.rulers: A ruler is a line which starts with and ends with three or more
non-alphanum or space characters:# ---- This is a Ruler ----
# cmake-format will know to keep the ruler separated from the
# paragraphs around it. So it wont try to reflow this text as
# a single paragraph.
# ---- This is also a Ruler ---list: A list is started on the first encountered list item, which starts
with a bullet character (*) followed by a space followed by some text.
Subsequent lines will be included in the list item until the next list item
is encountered (the bullet must be at the same indentation level). The list
must be surrounded by a pair of empty lines. Nested lists will be formatted in
nested text:# here are some lists:
#
# * item 1
# * item 2
#
#   * subitem 1
#   * subitem 2
#
# * second list item 1
# * second list item 2enumerations: An enumeration is similar to a list but the bullet character
is some integers followed by a period. New enumeration items are detected as
long as either the first digit or the punctuation lines up in the same column
as the previous item.cmake-formatwill renumber your items and align their
labels for you:# This is an enumeration
#
#   1. item
#   2. item
#   3. itemfences: If you have any text which you do not want to be formatted you can
guard it with a pair of fences. Fences are three or more tilde characters:# ~~~
# This comment is fenced
#   and will not be formatted
# ~~~Note that comment fences guard reflow ofcomment text, and not cmake code.
If you wish to prevent formatting of cmake, code, see below. In addition to
fenced-literals, there are three other ways to preserve comment text from
markup and/or reflow processing:The--first-comment-is-literalconfiguration option will exactly preserve
the first comment in the file. This is intended to preserve copyright or
other formatted header comments.The--literal-comment-patternconfiguration option allows for a more
generic way to identify comments which should be preserved literally. This
configuration takes a regular expression pattern.The--enable-markupconfiguration option globally enables comment markup
processing. It defaults to true so set it to false if you wish to globally
disable comment markup processing. Note that trailing whitespace is still
chomped from comments.Disable Formatting LocallyYou can locally disable and enable code formatting by using the special
comments#cmake-format:offand#cmake-format:on.Sort Argument ListsStarting with version0.5.0,cmake-formatcan sort your argument lists
for you. If the configuration includesautosort=True(the default), it
will replace:add_library(foobar STATIC EXCLUDE_FROM_ALL
            sourcefile_06.cc
            sourcefile_03.cc
            sourcefile_02.cc
            sourcefile_04.cc
            sourcefile_07.cc
            sourcefile_01.cc
            sourcefile_05.cc)with:add_library(foobar STATIC EXCLUDE_FROM_ALL
            sourcefile_01.cc
            sourcefile_02.cc
            sourcefile_03.cc
            sourcefile_04.cc
            sourcefile_05.cc
            sourcefile_06.cc
            sourcefile_07.cc)This is implemented for any argument lists which the parser knows are
inherently sortable. This includes the following cmake commands:add_libraryadd_executableFor most other cmake commands, you can use an annotation comment to hint tocmake-formatthat the argument list is sortable. For instance:set(SOURCES
    # cmake-format: sortable
    bar.cc
    baz.cc
    foo.cc)Annotations can be given in a line-comment or a bracket comment. There is a
long-form and a short-form for each. The acceptable formats are:Line Commentlong#cmake-format:<tag>Line Commentshort# cmf: <tag>Bracket Commentlong#[[cmake-format:<tag>]]Bracket Commentshort#[[cmf:<tag>]]In order to annotate a positional argument list as sortable, the acceptable
tags are:sortableorsort. For the commands listed above where
the positinal argument lists are inherently sortable, you can locally disable
sorting by annotating them withunsortableorunsort. For example:add_library(foobar STATIC
            # cmake-format: unsort
            sourcefile_03.cc
            sourcefile_01.cc
            sourcefile_02.cc)Note that this is only needed if your configuration has enabledautosort,
and you can globally disable sorting by making setting this configuration toFalse.Custom CommandsDue to the fact that cmake is a macro language,cmake-formatis, by
necessity, asemanticsource code formatter. In general it tries to make
smart formatting decisions based on the meaning of arguments in an otherwise
unstructured list of arguments in a cmake statement.cmake-formatcan
intelligently format your custom commands, but you will need to tell it how
to interpret your arguments.Currently, you can do this by adding your command specifications to theadditional_commandsconfiguration variables, e.g.:# Additional FLAGS and KWARGS for custom commands
additional_commands = {
  "foo": {
    "pargs": 2,
    "flags": ["BAR", "BAZ"],
    "kwargs": {
      "HEADERS": '*',
      "SOURCES": '*',
      "DEPENDS": '*',
    }
  }
}The format is a nested dictionary mapping statement names (dictionary keys)
toargument specifications. For the example specification above, the
custom command would look something like this:foo(hello world
    HEADERS a.h b.h c.h d.h
    SOURCES a.cc b.cc c.cc d.cc
    DEPENDS flub buzz bizz
    BAR BAZ)Reporting Issues and Getting HelpIf you encounter any bugs or regressions or ifcmake-formatdoesn’t behave
in the way that you expect, please post an issue on thegithub issue tracker. It is especially helpful if you can provide cmake
listfile snippets that demonstrate any issues you encounter.You can also join the#cmake-formatchannel on ourdiscord server.DevelopersIf you want to hack oncmake-format, please see thedocumentationfor
contribution rules and guidelines.ExampleWill turn this:# The following multiple newlines should be collapsed into a single newlinecmake_minimum_required(VERSION2.8.11)project(cmakelang_test)# This multiline-comment should be reflowed
# into a single comment
# on one line# This comment should remain right before the command call.
# Furthermore, the command call should be formatted
# to a single line.add_subdirectories(foobarbazfoo2bar2baz2)# This very long command should be wrappedset(HEADERSvery_long_header_name_a.hvery_long_header_name_b.hvery_long_header_name_c.h)# This command should be split into one line per entry because it has a long argument list.set(SOURCESsource_a.ccsource_b.ccsource_d.ccsource_e.ccsource_f.ccsource_g.ccsource_h.cc)# The string in this command should not be splitset_target_properties(foobarbazPROPERTIESCOMPILE_FLAGS"-std=c++11 -Wall -Wextra")# This command has a very long argument and can't be aligned with the command
# end, so it should be moved to a new line with block indent + 1.some_long_command_name("Some very long argument that really needs to be on the next line.")# This situation is similar but the argument to a KWARG needs to be on a
# newline instead.set(CMAKE_CXX_FLAGS"-std=c++11 -Wall -Wno-sign-compare -Wno-unused-parameter -xx")set(HEADERSheader_a.hheader_b.h# This comment should# be preserved, moreover it should be split# across two lines.header_c.hheader_d.h)# This part of the comment should
# be formatted
# but...
# cmake-format: off
# This bunny should remain untouched:
# . 　 ＿　∩
# 　　ﾚﾍヽ| |
# 　　　 (・ｘ・)
# 　　 c( uu}
# cmake-format: on
#          while this part should
#          be formatted again# This is a paragraph
#
# This is a second paragraph
#
# This is a third paragraph# This is a comment
# that should be joined but
# TODO(josh): This todo should not be joined with the previous line.
# NOTE(josh): Also this should not be joined with the todo.if(foo)if(sbar)# This comment is in-scope.add_library(foo_bar_bazfoo.ccbar.cc# this is a comment for arg2# this is more comment for arg2, it should be joined with the first.baz.cc)# This comment is part of add_libraryother_command(some_long_argumentsome_long_argument)# this comment is very long and gets split across some linesother_command(some_long_argumentsome_long_argumentsome_long_argument)# this comment is even longer and wouldn't make sense to pack at the end of the command so it gets it's own linesendif()endif()# This very long command should be broken up along keyword argumentsfoo(nonkwarg_anonkwarg_bHEADERSa.hb.hc.hd.he.hf.hSOURCESa.ccb.ccd.ccDEPENDSfoobarbaz)# This command uses a string with escaped quote charsfoo(some_argsome_arg"This is a \"string\" within a string")# This command uses an empty stringfoo(some_argsome_arg"")# This command uses a multiline stringfoo(some_argsome_arg"
    This string is on multiple lines
")# No, I really want this to look ugly
# cmake-format: offadd_library(ab.ccc.ccd.cce.cc)# cmake-format: oninto this:# The following multiple newlines should be collapsed into a single newlinecmake_minimum_required(VERSION2.8.11)project(cmakelang_test)# This multiline-comment should be reflowed into a single comment on one line# This comment should remain right before the command call. Furthermore, the
# command call should be formatted to a single line.add_subdirectories(foobarbazfoo2bar2baz2)# This very long command should be wrappedset(HEADERSvery_long_header_name_a.hvery_long_header_name_b.hvery_long_header_name_c.h)# This command should be split into one line per entry because it has a long
# argument list.set(SOURCESsource_a.ccsource_b.ccsource_d.ccsource_e.ccsource_f.ccsource_g.ccsource_h.cc)# The string in this command should not be splitset_target_properties(foobarbazPROPERTIESCOMPILE_FLAGS"-std=c++11 -Wall -Wextra")# This command has a very long argument and can't be aligned with the command
# end, so it should be moved to a new line with block indent + 1.some_long_command_name("Some very long argument that really needs to be on the next line.")# This situation is similar but the argument to a KWARG needs to be on a newline
# instead.set(CMAKE_CXX_FLAGS"-std=c++11 -Wall -Wno-sign-compare -Wno-unused-parameter -xx")set(HEADERSheader_a.hheader_b.h# This comment should be preserved, moreover it should# be split across two lines.header_c.hheader_d.h)# This part of the comment should be formatted but...
# cmake-format: off
# This bunny should remain untouched:
# . 　 ＿　∩
# 　　ﾚﾍヽ| |
# 　　　 (・ｘ・)
# 　　 c( uu}
# cmake-format: on
# while this part should be formatted again# This is a paragraph
#
# This is a second paragraph
#
# This is a third paragraph# This is a comment that should be joined but
# TODO(josh): This todo should not be joined with the previous line.
# NOTE(josh): Also this should not be joined with the todo.if(foo)if(sbar)# This comment is in-scope.add_library(foo_bar_bazfoo.ccbar.cc# this is a comment for arg2 this is more comment for arg2,# it should be joined with the first.baz.cc)# This comment is part of add_libraryother_command(some_long_argumentsome_long_argument)# this comment is very long and# gets split across some linesother_command(some_long_argumentsome_long_argumentsome_long_argument)# this comment# is even longer# and wouldn't# make sense to# pack at the# end of the# command so it# gets it's own# linesendif()endif()# This very long command should be broken up along keyword argumentsfoo(nonkwarg_anonkwarg_bHEADERSa.hb.hc.hd.he.hf.hSOURCESa.ccb.ccd.ccDEPENDSfoobarbaz)# This command uses a string with escaped quote charsfoo(some_argsome_arg"This is a \"string\" within a string")# This command uses an empty stringfoo(some_argsome_arg"")# This command uses a multiline stringfoo(some_argsome_arg"
    This string is on multiple lines
")# No, I really want this to look ugly
# cmake-format: offadd_library(ab.ccc.ccd.cce.cc)# cmake-format: on