1CTAGS-LANG-ASM(7) Universal Ctags CTAGS-LANG-ASM(7)
2
6 ctags-lang-asm - Random notes about tagging Assembly language source
7 code with Universal Ctags
8
10 ctags ... --languages=+Asm ...
11 ctags ... --language-force=Asm ...
12 ctags ... --map-Asm=+.asm ...
13 ctags ... --map-Asm=+.ASM ...
14 ctags ... --map-Asm=+.s ...
15 ctags ... --map-Asm=+.S ...
16
19 This man page gathers random notes about tagging assembly language
20 source code.
21 The parser of Universal Ctags has been extended to support the source
23 code to be processed with GNU assembler (Gas).
24
26 The Asm parser has some parameters for adapting it to different assem‐
27 bler implementations.
28 Writing a parser for assembly language source code is not easy because
30 the syntax for the language differ depending on the implementations of
31 assemblers and target CPU architectures. For example, in NASM, ; is a
32 starter of a line comment. On the other hand, in Gas for i386, ; is a
33 line separator. The parameters explained this man page are for mitigat‐
34 ing the gaps of syntax.
35 Use --param-Asm.{parameter}={value} option for adjusting the value for
37 a parameter. For example:
38 $ ctags ... --param-Asm.runCPreProcessor=false ...
40 This command line sets false to runCPreProcessor parameter.
42 --list-params=Asm lists available parameters available in the Asm
44 parser.
45 runCPreProcessor: running C preprocessor
47 By default, the CPreProcessor parser processes the assembly language
48 source code before the Asm parser does.
49 The main effects of running the CPreProcessor parser;
51 • lines started from // are stripped as comments,
53 • areas surrounded by the pair of /* and */ are started as comments,
55 and
56 • macros defined with #define are extracted as tags.
58 Set runCPreProcessor to false for disabling the CPreProcessor parser
60 running before the Asm parser.
61 commentCharsAtBOL: adjusting line comment starter at the beginning of line
63 By default, the Asm parser ignores lines starting from ;, *, or @ as
64 comments. // is also ignored if runCPreProcessor is true.
65 commentCharsAtBOL is for changing the characters for line comments.
67 BOL is acronym standing for "the beginning of line." The characters act
68 as comment starters only if they are at the beginning of lines.
69 The next example if for assembler input using ! and > as the comment
71 starter:
72 $ ctags ... --param-Asm.commentCharsAtBOL='!>' ...
74 commentCharsInMOL: adjusting line comment starter in the middle of line
76 Some dialects of assemblers support comments starting from the middle
77 of line. A ; character starts a comment anywhere on the line in Gas
78 for CRIS for example.
79 commentCharsInMOL is for specifying the character for line comments.
81 MOL is acronym standing for "the middle of line." Unlike characters
82 specified with commentCharsAtBOL, the characters specified with com‐
83 mentCharsInMOL act as comment starts even if they are in the middle of
84 lines.
85 By default, the Asm parser has no commentCharsInMOL characters.
87 extraLinesepChars: adding line separators
89 The Asm parser processes its input line-oriented way. By default, the
90 parser recognizes n as a line separator. extraLinesepChars is for
91 adding more line separators.
92 In Gas for AArch64, the ; character can be used as line separators.
94 The next example for adjusting the Asm parser to the extra line separa‐
95 tor:
96 $ ctags ... --param-Asm.extraLinesepChars=';' ...
98
100 The Asm parser has the ability to expand C preprocessor macros before
101 parsing.
102 NOTE:
104 Don't confuse C preprocessor macros and assembler implementation
105 specific macros. The Asm parser expands only C preprocessor macros.
106 Specifying following options are must for expansion:
108 --param-Asm.runCPreProcessor=true
110 --fields=+{signature}
111 --fields-CPreProcessor=+{macrodef}
112 With the above options, the parser expands macros defined in command
114 line with -D option. See ctags(1) about the way to define a macro with
115 the -D option.
116 With --param-CPreProcessor._expand=1 option, the parser expands macros
118 defined in the current input file in addition to macros defined with
119 the -D option.
120 Though the parser expands macros, the parser doesn't extract language
122 objects like labels as you expect. You must adjust the parser specific
123 parameters to utilize the macro expansion feature effectively. See
124 An example of macro expansion
126 "input.S"
127 #define ENTRY(LABEL) .global LABEL ;\
129 LABEL
130 ENTRY(main):
132 nop
133 "output.tags" with "--options=NONE -o - --param-Asm.useCPreProcessor=1
135 --param-CPreProcessor._expand=1 --fields=+{signature} --fields-CPrePro‐
136 cessor=+{macrodef} --param-Asm.extraLinesepChars=; --fields-CPreProces‐
137 sor=+{macrodef} input.S"
138 ENTRY input.S /^#define ENTRY(/;" d file: signature:(LABEL) macrodef:.global LABEL ;LABEL
140 main input.S /^ENTRY(main):$/;" l
141 The definition of ENTRY assumes ; is a line separator in the host as‐
143 sembly language. --param-Asm.extraLinesepChars=; is for satisfying the
144 assumption in ctags side.
145 Known limitations
147 The parser has no ability to expand the macros defined outside of the
148 current input file. The parser doesn't consider #undef when expanding.
149
151 ctags(1), Info entries for GNU assembler
1526.0.0 CTAGS-LANG-ASM(7)