-
Notifications
You must be signed in to change notification settings - Fork 629
/
ctags-lang-asm.7.rst.in
188 lines (139 loc) · 6.51 KB
/
ctags-lang-asm.7.rst.in
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
.. _ctags-lang-asm(7):
==============================================================
ctags-lang-asm
==============================================================
-----------------------------------------------------------------------------
Random notes about tagging Assembly language source code with Universal Ctags
-----------------------------------------------------------------------------
:Version: @VERSION@
:Manual group: Universal Ctags
:Manual section: 7
SYNOPSIS
--------
| **@CTAGS_NAME_EXECUTABLE@** ... --languages=+Asm ...
| **@CTAGS_NAME_EXECUTABLE@** ... --language-force=Asm ...
| **@CTAGS_NAME_EXECUTABLE@** ... --map-Asm=+.asm ...
| **@CTAGS_NAME_EXECUTABLE@** ... --map-Asm=+.ASM ...
| **@CTAGS_NAME_EXECUTABLE@** ... --map-Asm=+.s ...
| **@CTAGS_NAME_EXECUTABLE@** ... --map-Asm=+.S ...
DESCRIPTION
-----------
This man page gathers random notes about tagging assembly language
source code.
The parser of Universal Ctags has been extended to support the source
code to be processed with *GNU assembler* (*Gas*).
PARAMETERS
----------
The Asm parser has some parameters for adapting it to different
assembler implementations.
Writing a parser for assembly language source code is not easy because
the syntax for the language differ depending on the implementations of
assemblers and target CPU architectures. For example, in *NASM*, `;`
is a starter of a line comment. On the other hand, in Gas for i386,
`;` is a line separator. The parameters explained this man page are
for mitigating the gaps of syntax.
Use ``--param-Asm.{parameter}={value}`` option for adjusting the value
for a parameter. For example:
.. code-block:: console
$ @CTAGS_NAME_EXECUTABLE@ ... --param-Asm.runCPreProcessor=false ...
This command line sets ``false`` to ``runCPreProcessor`` parameter.
``--list-params=Asm`` lists available parameters available in the
Asm parser.
``runCPreProcessor``: running C preprocessor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the CPreProcessor parser processes the assembly language
source code before the Asm parser does.
The main effects of running the CPreProcessor parser;
* lines started from `//` are stripped as comments,
* areas surrounded by the pair of `/*` and `*/` are
stripped as comments, and
* macros defined with `#define` are extracted as tags.
Set ``runCPreProcessor`` to ``false`` for disabling the CPreProcessor
parser running before the Asm parser.
``commentCharsAtBOL``: adjusting line comment starter at the beginning of line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, the Asm parser ignores lines starting from `;`, `*`, or
`@` as comments. `//` is also ignored if `runCPreProcessor` is `true`.
``commentCharsAtBOL`` is for changing the characters for line comments.
`BOL` is acronym standing for "the beginning of line." The characters
act as comment starters only if they are at the beginning
of lines.
The next example if for assembler input using `!` and `>` as the comment starter:
.. code-block:: console
$ @CTAGS_NAME_EXECUTABLE@ ... --param-Asm.commentCharsAtBOL='!>' ...
``commentCharsInMOL``: adjusting line comment starter in the middle of line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some dialects of assemblers support comments starting from the middle of line.
A `;` character starts a comment anywhere on the line in Gas for CRIS for example.
``commentCharsInMOL`` is for specifying the character for line comments.
`MOL` is acronym standing for "the middle of line." Unlike characters
specified with ``commentCharsAtBOL``, the characters specified with
``commentCharsInMOL`` act as comment starts even if they are in the
middle of lines.
By default, the Asm parser has no ``commentCharsInMOL`` characters.
``extraLinesepChars``: adding line separators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Asm parser processes its input line-oriented way. By default, the
parser recognizes `\n` as a line separator. ``extraLinesepChars`` is
for adding more line separators.
In Gas for AArch64, the `;` character can be used as line separators.
The next example for adjusting the Asm parser to the extra line
separator:
.. code-block:: console
$ @CTAGS_NAME_EXECUTABLE@ ... --param-Asm.extraLinesepChars=';' ...
EXPANDING C PREPROCESSOR MACROS
-------------------------------
The Asm parser has the ability to expand **C preprocessor macros**
before parsing.
.. note::
Don't confuse C preprocessor macros and assembler implementation
specific macros. The Asm parser expands only C preprocessor macros.
Specifying following options are must for expansion::
--param-Asm.runCPreProcessor=true
--fields=+{signature}
--fields-CPreProcessor=+{macrodef}
With the above options, the parser expands macros defined in command
line with ``-D`` option. See ctags(1) about the way to define a macro
with the ``-D`` option.
With ``--param-CPreProcessor._expand=1`` option, the parser expands
macros defined in the current input file in addition to macros defined
with the ``-D`` option.
Though the parser expands macros, the parser doesn't extract language
objects like labels as you expect. You must adjust the parser specific
parameters to utilize the macro expansion feature effectively. See
An example of macro expansion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"input.S"
.. code-block::
#define ENTRY(LABEL) .global LABEL ;\
LABEL
ENTRY(main):
nop
"output.tags"
with "--options=NONE -o - --param-Asm.useCPreProcessor=1 --param-CPreProcessor._expand=1 --fields=+{signature} --fields-CPreProcessor=+{macrodef} --param-Asm.extraLinesepChars=; --fields-CPreProcessor=+{macrodef} input.S"
.. code-block:: tags
ENTRY input.S /^#define ENTRY(/;" d file: signature:(LABEL) macrodef:.global LABEL ;LABEL
main input.S /^ENTRY(main):$/;" l
main input.S /^ENTRY(main):$/;" s
The definition of `ENTRY` assumes `;` is a line separator in the host assembly language.
``--param-Asm.extraLinesepChars=;`` is for satisfying the assumption in ctags side.
Known limitations
~~~~~~~~~~~~~~~~~
The parser has no ability to expand the macros defined outside of the
current input file. The parser doesn't consider `#undef` when
expanding.
VERSIONS
--------
Change since "0.0"
~~~~~~~~~~~~~~~~~~
* The kind ``section`` is deleted.
The section specified with `.section` directive as tagged as
``placement`` role of ``section`` kind of ``Asm`` language.
These kind and role are deleted.
Instead, it is tagged as ``destination`` role of ``inputSection``
kind of ``LdScript`` language.
SEE ALSO
--------
ctags(1),
ctags-lang-asm(7),
Info entries for GNU assembler