1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
========
Features
========
-------
Markup
-------
``cmake-format`` is 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 2
**enumerations**: 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-format`` will renumber your items and align their
labels for you::
# This is an enumeration
#
# 1. item
# 2. item
# 3. item
**fences**: 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 of *comment 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-literal`` configuration option will exactly preserve
the first comment in the file. This is intended to preserve copyright or
other formatted header comments.
* The ``--literal-comment-pattern`` configuration option allows for a more
generic way to identify comments which should be preserved literally. This
configuration takes a regular expression pattern.
* The ``--enable-markup`` configuration 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 Locally
--------------------------
You can locally disable and enable code formatting by using the special
comments ``# cmake-format: off`` and ``# cmake-format: on``.
-------------------
Sort Argument Lists
-------------------
Starting with version `0.5.0`, ``cmake-format`` can sort your argument lists
for you. If the configuration includes ``autosort=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_library``
* ``add_executable``
For most other cmake commands, you can use an annotation comment to hint to
``cmake-format`` that 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 Comment | long | ``# cmake-format: <tag>`` |
+-----------------+-------+------------------------------+
| Line Comment | short | ``# cmf: <tag>`` |
+-----------------+-------+------------------------------+
| Bracket Comment | long | ``#[[cmake-format: <tag>]]`` |
+-----------------+-------+------------------------------+
| Bracket Comment | short | ``#[[cmf: <tag>]]`` |
+-----------------+-------+------------------------------+
In order to annotate a positional argument list as sortable, the acceptable
tags are: ``sortable`` or ``sort``. For the commands listed above where
the positinal argument lists are inherently sortable, you can locally disable
sorting by annotating them with ``unsortable`` or ``unsort``. 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 enabled ``autosort``,
and you can globally disable sorting by making setting this configuration to
``False``.
---------------
Custom Commands
---------------
Due to the fact that cmake is a macro language, `cmake-format` is, by
necessity, a *semantic* source 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-format` can
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 the
`additional_commands` configuration variables, e.g.:
.. code::
# 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)
to `argument specifications`__. For the example specification above, the
custom command would look something like this:
.. code::
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)
.. __: https://cmake-format.rtfd.io/en/latest/custom_parsers.html
|
