blob: 61b86567367de9342bb8707c745881d2135fd619 [file] [log] [blame]
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001*quickfix.txt* For Vim version 7.4. Last change: 2016 Jul 02
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7This subject is introduced in section |30.1| of the user manual.
8
91. Using QuickFix commands |quickfix|
102. The error window |quickfix-window|
113. Using more than one list of errors |quickfix-error-lists|
124. Using :make |:make_makeprg|
135. Using :grep |grep|
146. Selecting a compiler |compiler-select|
157. The error format |error-file-format|
168. The directory stack |quickfix-directory-stack|
179. Specific error file formats |errorformats|
18
19{Vi does not have any of these commands}
20
21The quickfix commands are not available when the |+quickfix| feature was
22disabled at compile time.
23
24=============================================================================
251. Using QuickFix commands *quickfix* *Quickfix* *E42*
26
27Vim has a special mode to speedup the edit-compile-edit cycle. This is
28inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
29The idea is to save the error messages from the compiler in a file and use Vim
30to jump to the errors one by one. You can examine each problem and fix it,
31without having to remember all the error messages.
32
Bram Moolenaar05159a02005-02-26 23:04:13 +000033In Vim the quickfix commands are used more generally to find a list of
34positions in files. For example, |:vimgrep| finds pattern matches. You can
Bram Moolenaar2641f772005-03-25 21:58:17 +000035use the positions in a script with the |getqflist()| function. Thus you can
Bram Moolenaar05159a02005-02-26 23:04:13 +000036do a lot more than the edit/compile/fix cycle!
37
Bram Moolenaare18dbe82016-07-02 21:42:23 +020038If you have the error messages in a file you can start Vim with: >
39 vim -q filename
40
41From inside Vim an easy way to run a command and handle the output is with the
42|:make| command (see below).
43
44The 'errorformat' option should be set to match the error messages from your
Bram Moolenaar071d4272004-06-13 20:20:40 +000045compiler (see |errorformat| below).
46
Bram Moolenaard12f5c12006-01-25 22:10:52 +000047 *location-list* *E776*
Bram Moolenaar280f1262006-01-30 00:14:18 +000048A location list is similar to a quickfix list and contains a list of positions
49in files. A location list is associated with a window and each window can
50have a separate location list. A location list can be associated with only
51one window. The location list is independent of the quickfix list.
Bram Moolenaard12f5c12006-01-25 22:10:52 +000052
Bram Moolenaar280f1262006-01-30 00:14:18 +000053When a window with a location list is split, the new window gets a copy of the
Bram Moolenaare18dbe82016-07-02 21:42:23 +020054location list. When there are no longer any references to a location list,
55the location list is destroyed.
Bram Moolenaar280f1262006-01-30 00:14:18 +000056
57The following quickfix commands can be used. The location list commands are
58similar to the quickfix commands, replacing the 'c' prefix in the quickfix
59command with 'l'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
Bram Moolenaare18c0b32016-03-20 21:08:34 +010061 *E924*
62If the current window was closed by an |autocommand| while processing a
63location list command, it will be aborted.
64
Bram Moolenaarffec3c52016-03-23 20:55:42 +010065 *E925* *E926*
66If the current quickfix or location list was changed by an |autocommand| while
67processing a quickfix or location list command, it will be aborted.
68
Bram Moolenaar071d4272004-06-13 20:20:40 +000069 *:cc*
70:cc[!] [nr] Display error [nr]. If [nr] is omitted, the same
71 error is displayed again. Without [!] this doesn't
72 work when jumping to another buffer, the current buffer
73 has been changed, there is the only window for the
74 buffer and both 'hidden' and 'autowrite' are off.
75 When jumping to another buffer with [!] any changes to
76 the current buffer are lost, unless 'hidden' is set or
77 there is another window for this buffer.
78 The 'switchbuf' settings are respected when jumping
79 to a buffer.
80
Bram Moolenaard12f5c12006-01-25 22:10:52 +000081 *:ll*
82:ll[!] [nr] Same as ":cc", except the location list for the
83 current window is used instead of the quickfix list.
84
Bram Moolenaar071d4272004-06-13 20:20:40 +000085 *:cn* *:cnext* *E553*
86:[count]cn[ext][!] Display the [count] next error in the list that
87 includes a file name. If there are no file names at
88 all, go to the [count] next error. See |:cc| for
89 [!] and 'switchbuf'.
90
Bram Moolenaar17c7c012006-01-26 22:25:15 +000091 *:lne* *:lnext*
92:[count]lne[xt][!] Same as ":cnext", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +000093 current window is used instead of the quickfix list.
94
Bram Moolenaar071d4272004-06-13 20:20:40 +000095:[count]cN[ext][!] *:cp* *:cprevious* *:cN* *:cNext*
96:[count]cp[revious][!] Display the [count] previous error in the list that
97 includes a file name. If there are no file names at
98 all, go to the [count] previous error. See |:cc| for
99 [!] and 'switchbuf'.
100
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000101
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000102:[count]lN[ext][!] *:lp* *:lprevious* *:lN* *:lNext*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000103:[count]lp[revious][!] Same as ":cNext" and ":cprevious", except the location
104 list for the current window is used instead of the
105 quickfix list.
106
Bram Moolenaar071d4272004-06-13 20:20:40 +0000107 *:cnf* *:cnfile*
108:[count]cnf[ile][!] Display the first error in the [count] next file in
109 the list that includes a file name. If there are no
110 file names at all or if there is no next file, go to
111 the [count] next error. See |:cc| for [!] and
112 'switchbuf'.
113
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000114 *:lnf* *:lnfile*
115:[count]lnf[ile][!] Same as ":cnfile", except the location list for the
116 current window is used instead of the quickfix list.
117
Bram Moolenaar071d4272004-06-13 20:20:40 +0000118:[count]cNf[ile][!] *:cpf* *:cpfile* *:cNf* *:cNfile*
119:[count]cpf[ile][!] Display the last error in the [count] previous file in
120 the list that includes a file name. If there are no
121 file names at all or if there is no next file, go to
122 the [count] previous error. See |:cc| for [!] and
123 'switchbuf'.
124
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000125
126:[count]lNf[ile][!] *:lpf* *:lpfile* *:lNf* *:lNfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000127:[count]lpf[ile][!] Same as ":cNfile" and ":cpfile", except the location
128 list for the current window is used instead of the
129 quickfix list.
130
Bram Moolenaar071d4272004-06-13 20:20:40 +0000131 *:crewind* *:cr*
132:cr[ewind][!] [nr] Display error [nr]. If [nr] is omitted, the FIRST
133 error is displayed. See |:cc|.
134
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000135 *:lrewind* *:lr*
136:lr[ewind][!] [nr] Same as ":crewind", except the location list for the
137 current window is used instead of the quickfix list.
138
Bram Moolenaar071d4272004-06-13 20:20:40 +0000139 *:cfirst* *:cfir*
140:cfir[st][!] [nr] Same as ":crewind".
141
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000142 *:lfirst* *:lfir*
143:lfir[st][!] [nr] Same as ":lrewind".
144
Bram Moolenaar071d4272004-06-13 20:20:40 +0000145 *:clast* *:cla*
146:cla[st][!] [nr] Display error [nr]. If [nr] is omitted, the LAST
147 error is displayed. See |:cc|.
148
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000149 *:llast* *:lla*
150:lla[st][!] [nr] Same as ":clast", except the location list for the
151 current window is used instead of the quickfix list.
152
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153 *:cq* *:cquit*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000154:cq[uit][!] Quit Vim with an error code, so that the compiler
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155 will not compile the same file again.
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000156 WARNING: All changes in files are lost! Also when the
157 [!] is not used. It works like ":qall!" |:qall|,
158 except that Vim returns a non-zero exit code.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000159
160 *:cf* *:cfile*
161:cf[ile][!] [errorfile] Read the error file and jump to the first error.
162 This is done automatically when Vim is started with
163 the -q option. You can use this command when you
164 keep Vim running while compiling. If you give the
165 name of the errorfile, the 'errorfile' option will
166 be set to [errorfile]. See |:cc| for [!].
167
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000168 *:lf* *:lfile*
169:lf[ile][!] [errorfile] Same as ":cfile", except the location list for the
170 current window is used instead of the quickfix list.
171 You can not use the -q command-line option to set
172 the location list.
173
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000174
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000175:cg[etfile] [errorfile] *:cg* *:cgetfile*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000176 Read the error file. Just like ":cfile" but don't
177 jump to the first error.
178
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000179
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000180:lg[etfile] [errorfile] *:lg* *:lgetfile*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000181 Same as ":cgetfile", except the location list for the
182 current window is used instead of the quickfix list.
183
Bram Moolenaar4770d092006-01-12 23:22:24 +0000184 *:caddf* *:caddfile*
185:caddf[ile] [errorfile] Read the error file and add the errors from the
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000186 errorfile to the current quickfix list. If a quickfix
187 list is not present, then a new list is created.
188
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000189 *:laddf* *:laddfile*
190:laddf[ile] [errorfile] Same as ":caddfile", except the location list for the
191 current window is used instead of the quickfix list.
192
Bram Moolenaar86b68352004-12-27 21:59:20 +0000193 *:cb* *:cbuffer* *E681*
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000194:cb[uffer][!] [bufnr] Read the error list from the current buffer.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000195 When [bufnr] is given it must be the number of a
196 loaded buffer. That buffer will then be used instead
197 of the current buffer.
198 A range can be specified for the lines to be used.
199 Otherwise all lines in the buffer are used.
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000200 See |:cc| for [!].
Bram Moolenaar86b68352004-12-27 21:59:20 +0000201
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000202 *:lb* *:lbuffer*
Bram Moolenaar6cbce9d2007-03-08 10:01:03 +0000203:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000204 current window is used instead of the quickfix list.
205
Bram Moolenaardb552d602006-03-23 22:59:57 +0000206 *:cgetb* *:cgetbuffer*
207:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just
208 like ":cbuffer" but don't jump to the first error.
209
210 *:lgetb* *:lgetbuffer*
211:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for
212 the current window is used instead of the quickfix
213 list.
214
Bram Moolenaara6878372014-03-22 21:02:50 +0100215 *:cad* *:caddbuffer*
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100216:cad[dbuffer] [bufnr] Read the error list from the current buffer and add
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000217 the errors to the current quickfix list. If a
218 quickfix list is not present, then a new list is
219 created. Otherwise, same as ":cbuffer".
220
221 *:laddb* *:laddbuffer*
222:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for
223 the current window is used instead of the quickfix
224 list.
225
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000226 *:cex* *:cexpr* *E777*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000227:cex[pr][!] {expr} Create a quickfix list using the result of {expr} and
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200228 jump to the first error.
229 If {expr} is a String, then each new-line terminated
Bram Moolenaard6357e82016-01-21 21:48:09 +0100230 line in the String is processed using the global value
231 of 'errorformat' and the result is added to the
232 quickfix list.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200233 If {expr} is a List, then each String item in the list
234 is processed and added to the quickfix list. Non
235 String items in the List are ignored.
236 See |:cc| for [!].
Bram Moolenaar87e25fd2005-07-27 21:13:01 +0000237 Examples: >
238 :cexpr system('grep -n xyz *')
239 :cexpr getline(1, '$')
240<
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000241 *:lex* *:lexpr*
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200242:lex[pr][!] {expr} Same as |:cexpr|, except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000243 current window is used instead of the quickfix list.
244
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000245 *:cgete* *:cgetexpr*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000246:cgete[xpr] {expr} Create a quickfix list using the result of {expr}.
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200247 Just like |:cexpr|, but don't jump to the first error.
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000248
249 *:lgete* *:lgetexpr*
Bram Moolenaar20f90cf2011-05-19 12:22:51 +0200250:lgete[xpr] {expr} Same as |:cgetexpr|, except the location list for the
Bram Moolenaar76b92b22006-03-24 22:46:53 +0000251 current window is used instead of the quickfix list.
252
Bram Moolenaara6878372014-03-22 21:02:50 +0100253 *:cadde* *:caddexpr*
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100254:cadde[xpr] {expr} Evaluate {expr} and add the resulting lines to the
Bram Moolenaar4770d092006-01-12 23:22:24 +0000255 current quickfix list. If a quickfix list is not
256 present, then a new list is created. The current
257 cursor position will not be changed. See |:cexpr| for
258 more information.
259 Example: >
260 :g/mypattern/caddexpr expand("%") . ":" . line(".") . ":" . getline(".")
261<
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000262 *:lad* *:laddexpr*
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000263:lad[dexpr] {expr} Same as ":caddexpr", except the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000264 current window is used instead of the quickfix list.
265
Bram Moolenaar071d4272004-06-13 20:20:40 +0000266 *:cl* *:clist*
267:cl[ist] [from] [, [to]]
268 List all errors that are valid |quickfix-valid|.
269 If numbers [from] and/or [to] are given, the respective
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000270 range of errors is listed. A negative number counts
Bram Moolenaar071d4272004-06-13 20:20:40 +0000271 from the last error backwards, -1 being the last error.
272 The 'switchbuf' settings are respected when jumping
273 to a buffer.
274
Bram Moolenaare8fea072016-07-01 14:48:27 +0200275:cl[ist] +{count} List the current and next {count} valid errors. This
276 is similar to ":clist from from+count", where "from"
277 is the current error position.
278
Bram Moolenaar071d4272004-06-13 20:20:40 +0000279:cl[ist]! [from] [, [to]]
280 List all errors.
281
Bram Moolenaare8fea072016-07-01 14:48:27 +0200282:cl[ist]! +{count} List the current and next {count} error lines. This
283 is useful to see unrecognized lines after the current
284 one. For example, if ":clist" shows:
285 8384 testje.java:252: error: cannot find symbol ~
286 Then using ":cl! +3" shows the reason:
287 8384 testje.java:252: error: cannot find symbol ~
288 8385: ZexitCode = Fmainx(); ~
289 8386: ^ ~
290 8387: symbol: method Fmainx() ~
291
292:lli[st] [from] [, [to]] *:lli* *:llist*
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000293 Same as ":clist", except the location list for the
294 current window is used instead of the quickfix list.
295
296:lli[st]! [from] [, [to]]
297 List all the entries in the location list for the
298 current window.
299
Bram Moolenaar071d4272004-06-13 20:20:40 +0000300If you insert or delete lines, mostly the correct error location is still
301found because hidden marks are used. Sometimes, when the mark has been
302deleted for some reason, the message "line changed" is shown to warn you that
303the error location may not be correct. If you quit Vim and start again the
304marks are lost and the error locations may not be correct anymore.
305
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000306If vim is built with |+autocmd| support, two autocommands are available for
307running commands before and after a quickfix command (':make', ':grep' and so
308on) is executed. See |QuickFixCmdPre| and |QuickFixCmdPost| for details.
309
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000310 *QuickFixCmdPost-example*
311When 'encoding' differs from the locale, the error messages may have a
312different encoding from what Vim is using. To convert the messages you can
313use this code: >
314 function QfMakeConv()
315 let qflist = getqflist()
316 for i in qflist
317 let i.text = iconv(i.text, "cp936", "utf-8")
318 endfor
319 call setqflist(qflist)
320 endfunction
321
322 au QuickfixCmdPost make call QfMakeConv()
323
324
Bram Moolenaar12969c02015-09-08 23:36:10 +0200325EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST:
326 *:cdo*
327:cdo[!] {cmd} Execute {cmd} in each valid entry in the quickfix list.
328 It works like doing this: >
329 :cfirst
330 :{cmd}
331 :cnext
332 :{cmd}
333 etc.
334< When the current file can't be |abandon|ed and the [!]
335 is not present, the command fails.
Bram Moolenaare8fea072016-07-01 14:48:27 +0200336 When an error is detected execution stops.
Bram Moolenaar12969c02015-09-08 23:36:10 +0200337 The last buffer (or where an error occurred) becomes
338 the current buffer.
339 {cmd} can contain '|' to concatenate several commands.
340
341 Only valid entries in the quickfix list are used.
342 A range can be used to select entries, e.g.: >
343 :10,$cdo cmd
344< To skip entries 1 to 9.
345
346 Note: While this command is executing, the Syntax
347 autocommand event is disabled by adding it to
348 'eventignore'. This considerably speeds up editing
349 each buffer.
350 {not in Vi} {not available when compiled without the
351 |+listcmds| feature}
352 Also see |:bufdo|, |:tabdo|, |:argdo|, |:windo|,
353 |:ldo|, |:cfdo| and |:lfdo|.
354
355 *:cfdo*
356:cfdo[!] {cmd} Execute {cmd} in each file in the quickfix list.
357 It works like doing this: >
358 :cfirst
359 :{cmd}
360 :cnfile
361 :{cmd}
362 etc.
363< Otherwise it works the same as `:cdo`.
364 {not in Vi} {not available when compiled without the
365 |+listcmds| feature}
366
367 *:ldo*
368:ld[o][!] {cmd} Execute {cmd} in each valid entry in the location list
369 for the current window.
370 It works like doing this: >
371 :lfirst
372 :{cmd}
373 :lnext
374 :{cmd}
375 etc.
376< Only valid entries in the location list are used.
377 Otherwise it works the same as `:cdo`.
378 {not in Vi} {not available when compiled without the
379 |+listcmds| feature}
380
381 *:lfdo*
382:lfdo[!] {cmd} Execute {cmd} in each file in the location list for
383 the current window.
384 It works like doing this: >
385 :lfirst
386 :{cmd}
387 :lnfile
388 :{cmd}
389 etc.
390< Otherwise it works the same as `:ldo`.
391 {not in Vi} {not available when compiled without the
392 |+listcmds| feature}
393
Bram Moolenaar071d4272004-06-13 20:20:40 +0000394=============================================================================
3952. The error window *quickfix-window*
396
Bram Moolenaar7fd73202010-07-25 16:58:46 +0200397 *:cope* *:copen* *w:quickfix_title*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000398:cope[n] [height] Open a window to show the current list of errors.
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100399
Bram Moolenaar071d4272004-06-13 20:20:40 +0000400 When [height] is given, the window becomes that high
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100401 (if there is room). When [height] is omitted the
402 window is made ten lines high.
403
Bram Moolenaar071d4272004-06-13 20:20:40 +0000404 If there already is a quickfix window, it will be made
405 the current window. It is not possible to open a
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +0100406 second quickfix window. If [height] is given the
407 existing window will be resized to it.
408
409 The window will contain a special buffer, with
410 'buftype' equal to "quickfix". Don't change this!
411 The window will have the w:quickfix_title variable set
412 which will indicate the command that produced the
413 quickfix list. This can be used to compose a custom
414 status line if the value of 'statusline' is adjusted
415 properly.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000416
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000417 *:lop* *:lopen*
418:lop[en] [height] Open a window to show the location list for the
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000419 current window. Works only when the location list for
Bram Moolenaar17c7c012006-01-26 22:25:15 +0000420 the current window is present. You can have more than
421 one location window opened at a time. Otherwise, it
Bram Moolenaar280f1262006-01-30 00:14:18 +0000422 acts the same as ":copen".
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000423
Bram Moolenaar071d4272004-06-13 20:20:40 +0000424 *:ccl* *:cclose*
425:ccl[ose] Close the quickfix window.
426
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000427 *:lcl* *:lclose*
428:lcl[ose] Close the window showing the location list for the
429 current window.
430
Bram Moolenaar071d4272004-06-13 20:20:40 +0000431 *:cw* *:cwindow*
432:cw[indow] [height] Open the quickfix window when there are recognized
433 errors. If the window is already open and there are
434 no recognized errors, close the window.
435
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000436 *:lw* *:lwindow*
437:lw[indow] [height] Same as ":cwindow", except use the window showing the
438 location list for the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000439
440Normally the quickfix window is at the bottom of the screen. If there are
441vertical splits, it's at the bottom of the rightmost column of windows. To
442make it always occupy the full width: >
443 :botright cwindow
444You can move the window around with |window-moving| commands.
445For example, to move it to the top: CTRL-W K
446The 'winfixheight' option will be set, which means that the window will mostly
447keep its height, ignoring 'winheight' and 'equalalways'. You can change the
448height manually (e.g., by dragging the status line above it with the mouse).
449
450In the quickfix window, each line is one error. The line number is equal to
451the error number. You can use ":.cc" to jump to the error under the cursor.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000452Hitting the <Enter> key or double-clicking the mouse on a line has the same
Bram Moolenaar071d4272004-06-13 20:20:40 +0000453effect. The file containing the error is opened in the window above the
454quickfix window. If there already is a window for that file, it is used
455instead. If the buffer in the used window has changed, and the error is in
456another file, jumping to the error will fail. You will first have to make
457sure the window contains a buffer which can be abandoned.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000458 *CTRL-W_<Enter>* *CTRL-W_<CR>*
459You can use CTRL-W <Enter> to open a new window and jump to the error there.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000460
461When the quickfix window has been filled, two autocommand events are
462triggered. First the 'filetype' option is set to "qf", which triggers the
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000463FileType event. Then the BufReadPost event is triggered, using "quickfix" for
464the buffer name. This can be used to perform some action on the listed
465errors. Example: >
Bram Moolenaar280f1262006-01-30 00:14:18 +0000466 au BufReadPost quickfix setlocal modifiable
467 \ | silent exe 'g/^/s//\=line(".")." "/'
468 \ | setlocal nomodifiable
Bram Moolenaar071d4272004-06-13 20:20:40 +0000469This prepends the line number to each line. Note the use of "\=" in the
470substitute string of the ":s" command, which is used to evaluate an
471expression.
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000472The BufWinEnter event is also triggered, again using "quickfix" for the buffer
473name.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000474
Bram Moolenaar82af8712016-06-04 20:20:29 +0200475Note: When adding to an existing quickfix list the autocommand are not
476triggered.
477
Bram Moolenaar071d4272004-06-13 20:20:40 +0000478Note: Making changes in the quickfix window has no effect on the list of
479errors. 'modifiable' is off to avoid making changes. If you delete or insert
480lines anyway, the relation between the text and the error number is messed up.
481If you really want to do this, you could write the contents of the quickfix
482window to a file and use ":cfile" to have it parsed and used as the new error
483list.
484
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000485 *location-list-window*
Bram Moolenaar280f1262006-01-30 00:14:18 +0000486The location list window displays the entries in a location list. When you
487open a location list window, it is created below the current window and
488displays the location list for the current window. The location list window
489is similar to the quickfix window, except that you can have more than one
Bram Moolenaar1ef15e32006-02-01 21:56:25 +0000490location list window open at a time. When you use a location list command in
491this window, the displayed location list is used.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000492
Bram Moolenaar280f1262006-01-30 00:14:18 +0000493When you select a file from the location list window, the following steps are
494used to find a window to edit the file:
495
4961. If a window with the location list displayed in the location list window is
497 present, then the file is opened in that window.
4982. If the above step fails and if the file is already opened in another
499 window, then that window is used.
5003. If the above step fails then an existing window showing a buffer with
501 'buftype' not set is used.
5024. If the above step fails, then the file is edited in a new window.
503
504In all of the above cases, if the location list for the selected window is not
505yet set, then it is set to the location list displayed in the location list
506window.
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000507
Bram Moolenaar071d4272004-06-13 20:20:40 +0000508=============================================================================
5093. Using more than one list of errors *quickfix-error-lists*
510
511So far has been assumed that there is only one list of errors. Actually the
512ten last used lists are remembered. When starting a new list, the previous
513ones are automatically kept. Two commands can be used to access older error
514lists. They set one of the existing error lists as the current one.
515
516 *:colder* *:col* *E380*
517:col[der] [count] Go to older error list. When [count] is given, do
518 this [count] times. When already at the oldest error
519 list, an error message is given.
520
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000521 *:lolder* *:lol*
522:lol[der] [count] Same as ":colder", except use the location list for
523 the current window instead of the quickfix list.
524
Bram Moolenaar071d4272004-06-13 20:20:40 +0000525 *:cnewer* *:cnew* *E381*
526:cnew[er] [count] Go to newer error list. When [count] is given, do
527 this [count] times. When already at the newest error
528 list, an error message is given.
529
Bram Moolenaard12f5c12006-01-25 22:10:52 +0000530 *:lnewer* *:lnew*
531:lnew[er] [count] Same as ":cnewer", except use the location list for
532 the current window instead of the quickfix list.
533
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534When adding a new error list, it becomes the current list.
535
536When ":colder" has been used and ":make" or ":grep" is used to add a new error
537list, one newer list is overwritten. This is especially useful if you are
538browsing with ":grep" |grep|. If you want to keep the more recent error
539lists, use ":cnewer 99" first.
540
541=============================================================================
5424. Using :make *:make_makeprg*
543
544 *:mak* *:make*
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000545:mak[e][!] [arguments] 1. If vim was built with |+autocmd|, all relevant
546 |QuickFixCmdPre| autocommands are executed.
547 2. If the 'autowrite' option is on, write any changed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000548 buffers
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000549 3. An errorfile name is made from 'makeef'. If
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550 'makeef' doesn't contain "##", and a file with this
551 name already exists, it is deleted.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000552 4. The program given with the 'makeprg' option is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000553 started (default "make") with the optional
554 [arguments] and the output is saved in the
555 errorfile (for Unix it is also echoed on the
556 screen).
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000557 5. The errorfile is read using 'errorformat'.
Bram Moolenaar6b803a72007-05-06 14:25:46 +0000558 6. If vim was built with |+autocmd|, all relevant
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000559 |QuickFixCmdPost| autocommands are executed.
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000560 See example below.
Bram Moolenaar6b803a72007-05-06 14:25:46 +0000561 7. If [!] is not given the first error is jumped to.
562 8. The errorfile is deleted.
Bram Moolenaarb11bd7e2005-02-07 22:05:52 +0000563 9. You can now move through the errors with commands
Bram Moolenaar071d4272004-06-13 20:20:40 +0000564 like |:cnext| and |:cprevious|, see above.
565 This command does not accept a comment, any "
566 characters are considered part of the arguments.
567
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000568 *:lmak* *:lmake*
569:lmak[e][!] [arguments]
570 Same as ":make", except the location list for the
571 current window is used instead of the quickfix list.
572
Bram Moolenaar071d4272004-06-13 20:20:40 +0000573The ":make" command executes the command given with the 'makeprg' option.
574This is done by passing the command to the shell given with the 'shell'
575option. This works almost like typing
576
577 ":!{makeprg} [arguments] {shellpipe} {errorfile}".
578
579{makeprg} is the string given with the 'makeprg' option. Any command can be
580used, not just "make". Characters '%' and '#' are expanded as usual on a
581command-line. You can use "%<" to insert the current file name without
582extension, or "#<" to insert the alternate file name without extension, for
583example: >
584 :set makeprg=make\ #<.o
585
586[arguments] is anything that is typed after ":make".
587{shellpipe} is the 'shellpipe' option.
588{errorfile} is the 'makeef' option, with ## replaced to make it unique.
589
Bram Moolenaar6dfc28b2010-02-11 14:19:15 +0100590The placeholder "$*" can be used for the argument list in {makeprg} if the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000591command needs some additional characters after its arguments. The $* is
592replaced then by all arguments. Example: >
593 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
594or simpler >
595 :let &mp = 'latex \\nonstopmode \\input\{$*}'
596"$*" can be given multiple times, for example: >
597 :set makeprg=gcc\ -o\ $*\ $*
598
599The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This
600means that the output of the compiler is saved in a file and not shown on the
601screen directly. For Unix "| tee" is used. The compiler output is shown on
602the screen and saved in a file the same time. Depending on the shell used
603"|& tee" or "2>&1| tee" is the default, so stderr output will be included.
604
605If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful
606for compilers that write to an errorfile themselves (e.g., Manx's Amiga C).
607
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000608
609Using QuickFixCmdPost to fix the encoding ~
610
611It may be that 'encoding' is set to an encoding that differs from the messages
612your build program produces. This example shows how to fix this after Vim has
613read the error messages: >
614
615 function QfMakeConv()
616 let qflist = getqflist()
617 for i in qflist
618 let i.text = iconv(i.text, "cp936", "utf-8")
619 endfor
620 call setqflist(qflist)
621 endfunction
622
623 au QuickfixCmdPost make call QfMakeConv()
624
625(Example by Faque Cheng)
626
Bram Moolenaar071d4272004-06-13 20:20:40 +0000627==============================================================================
Bram Moolenaar86b68352004-12-27 21:59:20 +00006285. Using :vimgrep and :grep *grep* *lid*
629
630Vim has two ways to find matches for a pattern: Internal and external. The
631advantage of the internal grep is that it works on all systems and uses the
632powerful Vim search patterns. An external grep program can be used when the
633Vim grep does not do what you want.
634
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000635The internal method will be slower, because files are read into memory. The
636advantages are:
637- Line separators and encoding are automatically recognized, as if a file is
638 being edited.
639- Uses Vim search patterns. Multi-line patterns can be used.
640- When plugins are enabled: compressed and remote files can be searched.
641 |gzip| |netrw|
Bram Moolenaara3227e22006-03-08 21:32:40 +0000642
643To be able to do this Vim loads each file as if it is being edited. When
Bram Moolenaar1056d982006-03-09 22:37:52 +0000644there is no match in the file the associated buffer is wiped out again. The
Bram Moolenaara3227e22006-03-08 21:32:40 +0000645'hidden' option is ignored here to avoid running out of memory or file
646descriptors when searching many files. However, when the |:hide| command
647modifier is used the buffers are kept loaded. This makes following searches
648in the same files a lot faster.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000649
Bram Moolenaar483c5d82010-10-20 18:45:33 +0200650Note that |:copen| (or |:lopen| for |:lgrep|) may be used to open a buffer
651containing the search results in linked form. The |:silent| command may be
Bram Moolenaard58e9292011-02-09 17:07:58 +0100652used to suppress the default full screen grep output. The ":grep!" form of
Bram Moolenaar483c5d82010-10-20 18:45:33 +0200653the |:grep| command doesn't jump to the first match automatically. These
654commands can be combined to create a NewGrep command: >
655
656 command! -nargs=+ NewGrep execute 'silent grep! <args>' | copen 42
657
Bram Moolenaar86b68352004-12-27 21:59:20 +0000658
6595.1 using Vim's internal grep
660
Bram Moolenaare49b69a2005-01-08 16:11:57 +0000661 *:vim* *:vimgrep* *E682* *E683*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000662:vim[grep][!] /{pattern}/[g][j] {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +0000663 Search for {pattern} in the files {file} ... and set
Bram Moolenaar30b65812012-07-12 22:01:11 +0200664 the error list to the matches. Files matching
665 'wildignore' are ignored; files in 'suffixes' are
666 searched last.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000667 Without the 'g' flag each line is added only once.
668 With 'g' every match is added.
669
670 {pattern} is a Vim search pattern. Instead of
671 enclosing it in / any non-ID character (see
672 |'isident'|) can be used, so long as it does not
673 appear in {pattern}.
674 'ignorecase' applies. To overrule it put |/\c| in the
675 pattern to ignore case or |/\C| to match case.
676 'smartcase' is not used.
Bram Moolenaar60abe752013-03-07 16:32:54 +0100677 If {pattern} is empty (e.g. // is specified), the last
678 used search pattern is used. |last-pattern|
Bram Moolenaar05159a02005-02-26 23:04:13 +0000679
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000680 When a number is put before the command this is used
681 as the maximum number of matches to find. Use
682 ":1vimgrep pattern file" to find only the first.
683 Useful if you only want to check if there is a match
684 and quit quickly when it's found.
685
Bram Moolenaar05159a02005-02-26 23:04:13 +0000686 Without the 'j' flag Vim jumps to the first match.
687 With 'j' only the quickfix list is updated.
688 With the [!] any changes in the current buffer are
689 abandoned.
690
Bram Moolenaardcaf10e2005-01-21 11:55:25 +0000691 Every second or so the searched file name is displayed
692 to give you an idea of the progress made.
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000693 Examples: >
694 :vimgrep /an error/ *.c
695 :vimgrep /\<FileName\>/ *.h include/*
Bram Moolenaar231334e2005-07-25 20:46:57 +0000696 :vimgrep /myfunc/ **/*.c
697< For the use of "**" see |starstar-wildcard|.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000698
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000699:vim[grep][!] {pattern} {file} ...
700 Like above, but instead of enclosing the pattern in a
701 non-ID character use a white-separated pattern. The
702 pattern must start with an ID character.
703 Example: >
704 :vimgrep Error *.c
705<
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000706 *:lv* *:lvimgrep*
707:lv[imgrep][!] /{pattern}/[g][j] {file} ...
708:lv[imgrep][!] {pattern} {file} ...
709 Same as ":vimgrep", except the location list for the
710 current window is used instead of the quickfix list.
711
Bram Moolenaar86b68352004-12-27 21:59:20 +0000712 *:vimgrepa* *:vimgrepadd*
Bram Moolenaar05159a02005-02-26 23:04:13 +0000713:vimgrepa[dd][!] /{pattern}/[g][j] {file} ...
714:vimgrepa[dd][!] {pattern} {file} ...
Bram Moolenaar86b68352004-12-27 21:59:20 +0000715 Just like ":vimgrep", but instead of making a new list
716 of errors the matches are appended to the current
717 list.
718
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000719 *:lvimgrepa* *:lvimgrepadd*
720:lvimgrepa[dd][!] /{pattern}/[g][j] {file} ...
721:lvimgrepa[dd][!] {pattern} {file} ...
722 Same as ":vimgrepadd", except the location list for
723 the current window is used instead of the quickfix
724 list.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000725
7265.2 External grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727
728Vim can interface with "grep" and grep-like programs (such as the GNU
729id-utils) in a similar way to its compiler integration (see |:make| above).
730
731[Unix trivia: The name for the Unix "grep" command comes from ":g/re/p", where
732"re" stands for Regular Expression.]
733
734 *:gr* *:grep*
735:gr[ep][!] [arguments] Just like ":make", but use 'grepprg' instead of
736 'makeprg' and 'grepformat' instead of 'errorformat'.
Bram Moolenaar86b68352004-12-27 21:59:20 +0000737 When 'grepprg' is "internal" this works like
738 |:vimgrep|. Note that the pattern needs to be
739 enclosed in separator characters then.
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000740
741 *:lgr* *:lgrep*
742:lgr[ep][!] [arguments] Same as ":grep", except the location list for the
743 current window is used instead of the quickfix list.
744
Bram Moolenaar071d4272004-06-13 20:20:40 +0000745 *:grepa* *:grepadd*
746:grepa[dd][!] [arguments]
747 Just like ":grep", but instead of making a new list of
748 errors the matches are appended to the current list.
749 Example: >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100750 :call setqflist([])
Bram Moolenaar071d4272004-06-13 20:20:40 +0000751 :bufdo grepadd! something %
752< The first command makes a new error list which is
753 empty. The second command executes "grepadd" for each
754 listed buffer. Note the use of ! to avoid that
755 ":grepadd" jumps to the first error, which is not
756 allowed with |:bufdo|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100757 An example that uses the argument list and avoids
758 errors for files without matches: >
759 :silent argdo try
760 \ | grepadd! something %
761 \ | catch /E480:/
762 \ | endtry"
763<
Bram Moolenaar9f2c6e12006-02-04 22:45:44 +0000764 *:lgrepa* *:lgrepadd*
765:lgrepa[dd][!] [arguments]
766 Same as ":grepadd", except the location list for the
767 current window is used instead of the quickfix list.
768
Bram Moolenaar86b68352004-12-27 21:59:20 +00007695.3 Setting up external grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770
771If you have a standard "grep" program installed, the :grep command may work
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000772well with the defaults. The syntax is very similar to the standard command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000773
774 :grep foo *.c
775
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000776Will search all files with the .c extension for the substring "foo". The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000777arguments to :grep are passed straight to the "grep" program, so you can use
778whatever options your "grep" supports.
779
780By default, :grep invokes grep with the -n option (show file and line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000781numbers). You can change this with the 'grepprg' option. You will need to set
Bram Moolenaar071d4272004-06-13 20:20:40 +0000782'grepprg' if:
783
784a) You are using a program that isn't called "grep"
785b) You have to call grep with a full path
786c) You want to pass other options automatically (e.g. case insensitive
787 search.)
788
789Once "grep" has executed, Vim parses the results using the 'grepformat'
790option. This option works in the same way as the 'errorformat' option - see
791that for details. You may need to change 'grepformat' from the default if
792your grep outputs in a non-standard format, or you are using some other
793program with a special format.
794
795Once the results are parsed, Vim loads the first file containing a match and
796jumps to the appropriate line, in the same way that it jumps to a compiler
797error in |quickfix| mode. You can then use the |:cnext|, |:clist|, etc.
798commands to see the other matches.
799
800
Bram Moolenaar86b68352004-12-27 21:59:20 +00008015.4 Using :grep with id-utils
Bram Moolenaar071d4272004-06-13 20:20:40 +0000802
803You can set up :grep to work with the GNU id-utils like this: >
804
805 :set grepprg=lid\ -Rgrep\ -s
806 :set grepformat=%f:%l:%m
807
808then >
809 :grep (regexp)
810
811works just as you'd expect.
812(provided you remembered to mkid first :)
813
814
Bram Moolenaar86b68352004-12-27 21:59:20 +00008155.5 Browsing source code with :vimgrep or :grep
Bram Moolenaar071d4272004-06-13 20:20:40 +0000816
817Using the stack of error lists that Vim keeps, you can browse your files to
818look for functions and the functions they call. For example, suppose that you
819have to add an argument to the read_file() function. You enter this command: >
820
Bram Moolenaar86b68352004-12-27 21:59:20 +0000821 :vimgrep /\<read_file\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822
823You use ":cn" to go along the list of matches and add the argument. At one
824place you have to get the new argument from a higher level function msg(), and
825need to change that one too. Thus you use: >
826
Bram Moolenaar86b68352004-12-27 21:59:20 +0000827 :vimgrep /\<msg\>/ *.c
Bram Moolenaar071d4272004-06-13 20:20:40 +0000828
829While changing the msg() functions, you find another function that needs to
Bram Moolenaar86b68352004-12-27 21:59:20 +0000830get the argument from a higher level. You can again use ":vimgrep" to find
831these functions. Once you are finished with one function, you can use >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000832
833 :colder
834
835to go back to the previous one.
836
Bram Moolenaar86b68352004-12-27 21:59:20 +0000837This works like browsing a tree: ":vimgrep" goes one level deeper, creating a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000838list of branches. ":colder" goes back to the previous level. You can mix
Bram Moolenaar86b68352004-12-27 21:59:20 +0000839this use of ":vimgrep" and "colder" to browse all the locations in a tree-like
Bram Moolenaar071d4272004-06-13 20:20:40 +0000840way. If you do this consistently, you will find all locations without the
841need to write down a "todo" list.
842
843=============================================================================
8446. Selecting a compiler *compiler-select*
845
846 *:comp* *:compiler* *E666*
847:comp[iler][!] {name} Set options to work with compiler {name}.
848 Without the "!" options are set for the
849 current buffer. With "!" global options are
850 set.
851 If you use ":compiler foo" in "file.foo" and
852 then ":compiler! bar" in another buffer, Vim
853 will keep on using "foo" in "file.foo".
854 {not available when compiled without the
855 |+eval| feature}
856
857
858The Vim plugins in the "compiler" directory will set options to use the
859selected compiler. For ":compiler" local options are set, for ":compiler!"
860global options.
861 *current_compiler*
862To support older Vim versions, the plugins always use "current_compiler" and
863not "b:current_compiler". What the command actually does is the following:
864
865- Delete the "current_compiler" and "b:current_compiler" variables.
866- Define the "CompilerSet" user command. With "!" it does ":set", without "!"
867 it does ":setlocal".
868- Execute ":runtime! compiler/{name}.vim". The plugins are expected to set
869 options with "CompilerSet" and set the "current_compiler" variable to the
870 name of the compiler.
Bram Moolenaar05159a02005-02-26 23:04:13 +0000871- Delete the "CompilerSet" user command.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000872- Set "b:current_compiler" to the value of "current_compiler".
873- Without "!" the old value of "current_compiler" is restored.
874
875
876For writing a compiler plugin, see |write-compiler-plugin|.
877
878
Bram Moolenaarbae0c162007-05-10 19:30:25 +0000879GCC *quickfix-gcc* *compiler-gcc*
880
881There's one variable you can set for the GCC compiler:
882
883g:compiler_gcc_ignore_unmatched_lines
884 Ignore lines that don't match any patterns
885 defined for GCC. Useful if output from
886 commands run from make are generating false
887 positives.
888
889
Bram Moolenaar071d4272004-06-13 20:20:40 +0000890MANX AZTEC C *quickfix-manx* *compiler-manx*
891
892To use Vim with Manx's Aztec C compiler on the Amiga you should do the
893following:
894- Set the CCEDIT environment variable with the command: >
895 mset "CCEDIT=vim -q"
896- Compile with the -qf option. If the compiler finds any errors, Vim is
897 started and the cursor is positioned on the first error. The error message
898 will be displayed on the last line. You can go to other errors with the
899 commands mentioned above. You can fix the errors and write the file(s).
900- If you exit Vim normally the compiler will re-compile the same file. If you
901 exit with the :cq command, the compiler will terminate. Do this if you
902 cannot fix the error, or if another file needs to be compiled first.
903
904There are some restrictions to the Quickfix mode on the Amiga. The
905compiler only writes the first 25 errors to the errorfile (Manx's
906documentation does not say how to get more). If you want to find the others,
907you will have to fix a few errors and exit the editor. After recompiling,
908up to 25 remaining errors will be found.
909
910If Vim was started from the compiler, the :sh and some :! commands will not
911work, because Vim is then running in the same process as the compiler and
912stdin (standard input) will not be interactive.
913
914
Bram Moolenaar8c8de832008-06-24 22:58:06 +0000915PERL *quickfix-perl* *compiler-perl*
916
917The Perl compiler plugin doesn't actually compile, but invokes Perl's internal
918syntax checking feature and parses the output for possible errors so you can
919correct them in quick-fix mode.
920
921Warnings are forced regardless of "no warnings" or "$^W = 0" within the file
922being checked. To disable this set g:perl_compiler_force_warnings to a zero
923value. For example: >
924 let g:perl_compiler_force_warnings = 0
925
926
Bram Moolenaar071d4272004-06-13 20:20:40 +0000927PYUNIT COMPILER *compiler-pyunit*
928
929This is not actually a compiler, but a unit testing framework for the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000930Python language. It is included into standard Python distribution
931starting from version 2.0. For older versions, you can get it from
Bram Moolenaar071d4272004-06-13 20:20:40 +0000932http://pyunit.sourceforge.net.
933
934When you run your tests with the help of the framework, possible errors
935are parsed by Vim and presented for you in quick-fix mode.
936
937Unfortunately, there is no standard way to run the tests.
938The alltests.py script seems to be used quite often, that's all.
939Useful values for the 'makeprg' options therefore are:
940 setlocal makeprg=./alltests.py " Run a testsuite
Bram Moolenaar26df0922014-02-23 23:39:13 +0100941 setlocal makeprg=python\ %:S " Run a single testcase
Bram Moolenaar071d4272004-06-13 20:20:40 +0000942
943Also see http://vim.sourceforge.net/tip_view.php?tip_id=280.
944
945
946TEX COMPILER *compiler-tex*
947
948Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim)
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000949uses make command if possible. If the compiler finds a file named "Makefile"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000950or "makefile" in the current directory, it supposes that you want to process
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000951your *TeX files with make, and the makefile does the right work. In this case
952compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If
Bram Moolenaar071d4272004-06-13 20:20:40 +0000953neither "Makefile" nor "makefile" is found, the compiler will not use make.
954You can force the compiler to ignore makefiles by defining
955b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for
956existence only).
957
958If the compiler chose not to use make, it need to choose a right program for
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000959processing your input. If b:tex_flavor or g:tex_flavor (in this precedence)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000960variable exists, it defines TeX flavor for :make (actually, this is the name
961of executed command), and if both variables do not exist, it defaults to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000962"latex". For example, while editing chapter2.tex \input-ed from mypaper.tex
Bram Moolenaar071d4272004-06-13 20:20:40 +0000963written in AMS-TeX: >
964
965 :let b:tex_flavor = 'amstex'
966 :compiler tex
967< [editing...] >
968 :make mypaper
969
970Note that you must specify a name of the file to process as an argument (to
971process the right file when editing \input-ed or \include-ed file; portable
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000972solution for substituting % for no arguments is welcome). This is not in the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000973semantics of make, where you specify a target, not source, but you may specify
974filename without extension ".tex" and mean this as "make filename.dvi or
975filename.pdf or filename.some_result_extension according to compiler".
976
977Note: tex command line syntax is set to usable both for MikTeX (suggestion
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000978by Srinath Avadhanula) and teTeX (checked by Artem Chuprina). Suggestion
Bram Moolenaar071d4272004-06-13 20:20:40 +0000979from |errorformat-LaTeX| is too complex to keep it working for different
980shells and OSes and also does not allow to use other available TeX options,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000981if any. If your TeX doesn't support "-interaction=nonstopmode", please
Bram Moolenaar071d4272004-06-13 20:20:40 +0000982report it with different means to express \nonstopmode from the command line.
983
984=============================================================================
9857. The error format *error-file-format*
986
987 *errorformat* *E372* *E373* *E374*
988 *E375* *E376* *E377* *E378*
989The 'errorformat' option specifies a list of formats that are recognized. The
990first format that matches with an error message is used. You can add several
991formats for different messages your compiler produces, or even entries for
992multiple compilers. See |efm-entries|.
993
994Each entry in 'errorformat' is a scanf-like string that describes the format.
995First, you need to know how scanf works. Look in the documentation of your
996C compiler. Below you find the % items that Vim understands. Others are
997invalid.
998
999Special characters in 'errorformat' are comma and backslash. See
1000|efm-entries| for how to deal with them. Note that a literal "%" is matched
1001by "%%", thus it is not escaped with a backslash.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001002Keep in mind that in the `:make` and `:grep` output all NUL characters are
1003replaced with SOH (0x01).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001004
1005Note: By default the difference between upper and lowercase is ignored. If
1006you want to match case, add "\C" to the pattern |/\C|.
1007
1008
1009Basic items
1010
1011 %f file name (finds a string)
1012 %l line number (finds a number)
1013 %c column number (finds a number representing character
1014 column of the error, (1 <tab> == 1 character column))
1015 %v virtual column number (finds a number representing
1016 screen column of the error (1 <tab> == 8 screen
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001017 columns))
Bram Moolenaar071d4272004-06-13 20:20:40 +00001018 %t error type (finds a single character)
1019 %n error number (finds a number)
1020 %m error message (finds a string)
1021 %r matches the "rest" of a single-line file message %O/P/Q
Bram Moolenaarc8734422012-06-01 22:38:45 +02001022 %p pointer line (finds a sequence of '-', '.', ' ' or
1023 tabs and uses the length for the column number)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001024 %*{conv} any scanf non-assignable conversion
1025 %% the single '%' character
Bram Moolenaar2641f772005-03-25 21:58:17 +00001026 %s search text (finds a string)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001027
Bram Moolenaare344bea2005-09-01 20:46:49 +00001028The "%f" conversion may depend on the current 'isfname' setting. "~/" is
Bram Moolenaarf4630b62005-05-20 21:31:17 +00001029expanded to the home directory and environment variables are expanded.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001030
Bram Moolenaare344bea2005-09-01 20:46:49 +00001031The "%f" and "%m" conversions have to detect the end of the string. This
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00001032normally happens by matching following characters and items. When nothing is
Bram Moolenaare344bea2005-09-01 20:46:49 +00001033following the rest of the line is matched. If "%f" is followed by a '%' or a
1034backslash, it will look for a sequence of 'isfname' characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035
1036On MS-DOS, MS-Windows and OS/2 a leading "C:" will be included in "%f", even
1037when using "%f:". This means that a file name which is a single alphabetical
1038letter will not be detected.
1039
1040The "%p" conversion is normally followed by a "^". It's used for compilers
1041that output a line like: >
1042 ^
1043or >
1044 ---------^
1045to indicate the column of the error. This is to be used in a multi-line error
1046message. See |errorformat-javac| for a useful example.
1047
Bram Moolenaar2641f772005-03-25 21:58:17 +00001048The "%s" conversion specifies the text to search for to locate the error line.
1049The text is used as a literal string. The anchors "^" and "$" are added to
1050the text to locate the error line exactly matching the search text and the
1051text is prefixed with the "\V" atom to make it "very nomagic". The "%s"
1052conversion can be used to locate lines without a line number in the error
1053output. Like the output of the "grep" shell command.
1054When the pattern is present the line number will not be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001055
1056Changing directory
1057
1058The following uppercase conversion characters specify the type of special
1059format strings. At most one of them may be given as a prefix at the begin
1060of a single comma-separated format pattern.
1061Some compilers produce messages that consist of directory names that have to
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001062be prepended to each file name read by %f (example: GNU make). The following
Bram Moolenaar071d4272004-06-13 20:20:40 +00001063codes can be used to scan these directory names; they will be stored in an
1064internal directory stack. *E379*
1065 %D "enter directory" format string; expects a following
1066 %f that finds the directory name
1067 %X "leave directory" format string; expects following %f
1068
1069When defining an "enter directory" or "leave directory" format, the "%D" or
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001070"%X" has to be given at the start of that substring. Vim tracks the directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00001071changes and prepends the current directory to each erroneous file found with a
1072relative path. See |quickfix-directory-stack| for details, tips and
1073limitations.
1074
1075
1076Multi-line messages *errorformat-multi-line*
1077
1078It is possible to read the output of programs that produce multi-line
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001079messages, i.e. error strings that consume more than one line. Possible
Bram Moolenaar071d4272004-06-13 20:20:40 +00001080prefixes are:
1081 %E start of a multi-line error message
1082 %W start of a multi-line warning message
1083 %I start of a multi-line informational message
1084 %A start of a multi-line message (unspecified type)
Bram Moolenaarb3656ed2006-03-20 21:59:49 +00001085 %> for next line start with current pattern again |efm-%>|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001086 %C continuation of a multi-line message
1087 %Z end of a multi-line message
1088These can be used with '+' and '-', see |efm-ignore| below.
1089
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001090Using "\n" in the pattern won't work to match multi-line messages.
1091
Bram Moolenaar071d4272004-06-13 20:20:40 +00001092Example: Your compiler happens to write out errors in the following format
1093(leading line numbers not being part of the actual output):
1094
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001095 1 Error 275 ~
1096 2 line 42 ~
1097 3 column 3 ~
1098 4 ' ' expected after '--' ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001099
1100The appropriate error format string has to look like this: >
1101 :set efm=%EError\ %n,%Cline\ %l,%Ccolumn\ %c,%Z%m
1102
1103And the |:clist| error message generated for this error is:
1104
1105 1:42 col 3 error 275: ' ' expected after '--'
1106
1107Another example: Think of a Python interpreter that produces the following
1108error message (line numbers are not part of the actual output):
1109
1110 1 ==============================================================
1111 2 FAIL: testGetTypeIdCachesResult (dbfacadeTest.DjsDBFacadeTest)
1112 3 --------------------------------------------------------------
1113 4 Traceback (most recent call last):
1114 5 File "unittests/dbfacadeTest.py", line 89, in testFoo
1115 6 self.assertEquals(34, dtid)
1116 7 File "/usr/lib/python2.2/unittest.py", line 286, in
1117 8 failUnlessEqual
1118 9 raise self.failureException, \
1119 10 AssertionError: 34 != 33
1120 11
1121 12 --------------------------------------------------------------
1122 13 Ran 27 tests in 0.063s
1123
1124Say you want |:clist| write the relevant information of this message only,
1125namely:
1126 5 unittests/dbfacadeTest.py:89: AssertionError: 34 != 33
1127
1128Then the error format string could be defined as follows: >
1129 :set efm=%C\ %.%#,%A\ \ File\ \"%f\"\\,\ line\ %l%.%#,%Z%[%^\ ]%\\@=%m
1130
1131Note that the %C string is given before the %A here: since the expression
1132' %.%#' (which stands for the regular expression ' .*') matches every line
1133starting with a space, followed by any characters to the end of the line,
1134it also hides line 7 which would trigger a separate error message otherwise.
1135Error format strings are always parsed pattern by pattern until the first
1136match occurs.
Bram Moolenaarb3656ed2006-03-20 21:59:49 +00001137 *efm-%>*
1138The %> item can be used to avoid trying patterns that appear earlier in
1139'errorformat'. This is useful for patterns that match just about anything.
1140For example, if the error looks like this:
1141
1142 Error in line 123 of foo.c: ~
1143 unknown variable "i" ~
1144
1145This can be found with: >
1146 :set efm=xxx,%E%>Error in line %l of %f:,%Z%m
1147Where "xxx" has a pattern that would also match the second line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001149Important: There is no memory of what part of the errorformat matched before;
1150every line in the error file gets a complete new run through the error format
1151lines. For example, if one has: >
1152 setlocal efm=aa,bb,cc,dd,ee
1153Where aa, bb, etc. are error format strings. Each line of the error file will
1154be matched to the pattern aa, then bb, then cc, etc. Just because cc matched
1155the previous error line does _not_ mean that dd will be tried first on the
1156current line, even if cc and dd are multi-line errorformat strings.
1157
1158
Bram Moolenaar071d4272004-06-13 20:20:40 +00001159
1160Separate file name *errorformat-separate-filename*
1161
1162These prefixes are useful if the file name is given once and multiple messages
1163follow that refer to this file name.
1164 %O single-line file message: overread the matched part
1165 %P single-line file message: push file %f onto the stack
1166 %Q single-line file message: pop the last file from stack
1167
1168Example: Given a compiler that produces the following error logfile (without
1169leading line numbers):
1170
1171 1 [a1.tt]
1172 2 (1,17) error: ';' missing
1173 3 (21,2) warning: variable 'z' not defined
1174 4 (67,3) error: end of file found before string ended
1175 5
1176 6 [a2.tt]
1177 7
1178 8 [a3.tt]
1179 9 NEW compiler v1.1
1180 10 (2,2) warning: variable 'x' not defined
1181 11 (67,3) warning: 's' already defined
1182
1183This logfile lists several messages for each file enclosed in [...] which are
1184properly parsed by an error format like this: >
1185 :set efm=%+P[%f],(%l\\,%c)%*[\ ]%t%*[^:]:\ %m,%-Q
1186
1187A call of |:clist| writes them accordingly with their correct filenames:
1188
1189 2 a1.tt:1 col 17 error: ';' missing
1190 3 a1.tt:21 col 2 warning: variable 'z' not defined
1191 4 a1.tt:67 col 3 error: end of file found before string ended
1192 8 a3.tt:2 col 2 warning: variable 'x' not defined
1193 9 a3.tt:67 col 3 warning: 's' already defined
1194
1195Unlike the other prefixes that all match against whole lines, %P, %Q and %O
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001196can be used to match several patterns in the same line. Thus it is possible
Bram Moolenaar071d4272004-06-13 20:20:40 +00001197to parse even nested files like in the following line:
1198 {"file1" {"file2" error1} error2 {"file3" error3 {"file4" error4 error5}}}
1199The %O then parses over strings that do not contain any push/pop file name
1200information. See |errorformat-LaTeX| for an extended example.
1201
1202
1203Ignoring and using whole messages *efm-ignore*
1204
1205The codes '+' or '-' can be combined with the uppercase codes above; in that
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001206case they have to precede the letter, e.g. '%+A' or '%-G':
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207 %- do not include the matching multi-line in any output
1208 %+ include the whole matching line in the %m error string
1209
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001210One prefix is only useful in combination with '+' or '-', namely %G. It parses
Bram Moolenaar071d4272004-06-13 20:20:40 +00001211over lines containing general information like compiler version strings or
1212other headers that can be skipped.
1213 %-G ignore this message
1214 %+G general message
1215
1216
1217Pattern matching
1218
1219The scanf()-like "%*[]" notation is supported for backward-compatibility
1220with previous versions of Vim. However, it is also possible to specify
1221(nearly) any Vim supported regular expression in format strings.
1222Since meta characters of the regular expression language can be part of
1223ordinary matching strings or file names (and therefore internally have to
1224be escaped), meta symbols have to be written with leading '%':
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001225 %\ The single '\' character. Note that this has to be
Bram Moolenaar071d4272004-06-13 20:20:40 +00001226 escaped ("%\\") in ":set errorformat=" definitions.
Bram Moolenaarceaf7b82006-03-19 22:18:55 +00001227 %. The single '.' character.
1228 %# The single '*'(!) character.
1229 %^ The single '^' character. Note that this is not
1230 useful, the pattern already matches start of line.
1231 %$ The single '$' character. Note that this is not
1232 useful, the pattern already matches end of line.
1233 %[ The single '[' character for a [] character range.
1234 %~ The single '~' character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001235When using character classes in expressions (see |/\i| for an overview),
1236terms containing the "\+" quantifier can be written in the scanf() "%*"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001237notation. Example: "%\\d%\\+" ("\d\+", "any number") is equivalent to "%*\\d".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001238Important note: The \(...\) grouping of sub-matches can not be used in format
1239specifications because it is reserved for internal conversions.
1240
1241
1242Multiple entries in 'errorformat' *efm-entries*
1243
1244To be able to detect output from several compilers, several format patterns
1245may be put in 'errorformat', separated by commas (note: blanks after the comma
1246are ignored). The first pattern that has a complete match is used. If no
1247match is found, matching parts from the last one will be used, although the
1248file name is removed and the error message is set to the whole message. If
1249there is a pattern that may match output from several compilers (but not in a
1250right way), put it after one that is more restrictive.
1251
1252To include a comma in a pattern precede it with a backslash (you have to type
1253two in a ":set" command). To include a backslash itself give two backslashes
1254(you have to type four in a ":set" command). You also need to put a backslash
1255before a space for ":set".
1256
1257
1258Valid matches *quickfix-valid*
1259
1260If a line does not completely match one of the entries in 'errorformat', the
1261whole line is put in the error message and the entry is marked "not valid"
1262These lines are skipped with the ":cn" and ":cp" commands (unless there is
1263no valid line at all). You can use ":cl!" to display all the error messages.
1264
1265If the error format does not contain a file name Vim cannot switch to the
1266correct file. You will have to do this by hand.
1267
1268
1269Examples
1270
1271The format of the file from the Amiga Aztec compiler is:
1272
1273 filename>linenumber:columnnumber:errortype:errornumber:errormessage
1274
1275 filename name of the file in which the error was detected
1276 linenumber line number where the error was detected
1277 columnnumber column number where the error was detected
1278 errortype type of the error, normally a single 'E' or 'W'
1279 errornumber number of the error (for lookup in the manual)
1280 errormessage description of the error
1281
1282This can be matched with this 'errorformat' entry:
1283 %f>%l:%c:%t:%n:%m
1284
1285Some examples for C compilers that produce single-line error outputs:
1286%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages
1287 (scanf() doesn't understand [0-9])
1288%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C
1289\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers
1290%f:%l:\ %m for GCC
1291%f:%l:\ %m,%Dgmake[%*\\d]:\ Entering\ directory\ `%f',
1292%Dgmake[%*\\d]:\ Leaving\ directory\ `%f'
1293 for GCC with gmake (concat the lines!)
1294%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5)
1295%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number
1296%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m
1297 for GCC, with some extras
1298
1299Extended examples for the handling of multi-line messages are given below,
1300see |errorformat-Jikes| and |errorformat-LaTeX|.
1301
1302Note the backslash in front of a space and double quote. It is required for
1303the :set command. There are two backslashes in front of a comma, one for the
1304:set command and one to avoid recognizing the comma as a separator of error
1305formats.
1306
1307
1308Filtering messages
1309
1310If you have a compiler that produces error messages that do not fit in the
1311format string, you could write a program that translates the error messages
1312into this format. You can use this program with the ":make" command by
1313changing the 'makeprg' option. For example: >
1314 :set mp=make\ \\\|&\ error_filter
1315The backslashes before the pipe character are required to avoid it to be
1316recognized as a command separator. The backslash before each space is
1317required for the set command.
1318
1319=============================================================================
13208. The directory stack *quickfix-directory-stack*
1321
1322Quickfix maintains a stack for saving all used directories parsed from the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001323make output. For GNU-make this is rather simple, as it always prints the
1324absolute path of all directories it enters and leaves. Regardless if this is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001325done via a 'cd' command in the makefile or with the parameter "-C dir" (change
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001326to directory before reading the makefile). It may be useful to use the switch
Bram Moolenaar071d4272004-06-13 20:20:40 +00001327"-w" to force GNU-make to print out the working directory before and after
1328processing.
1329
1330Maintaining the correct directory is more complicated if you don't use
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001331GNU-make. AIX-make for example doesn't print any information about its
1332working directory. Then you need to enhance the makefile. In the makefile of
1333LessTif there is a command which echoes "Making {target} in {dir}". The
Bram Moolenaar6dfc28b2010-02-11 14:19:15 +01001334special problem here is that it doesn't print information on leaving the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001335directory and that it doesn't print the absolute path.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001336
1337To solve the problem with relative paths and missing "leave directory"
1338messages Vim uses following algorithm:
1339
13401) Check if the given directory is a subdirectory of the current directory.
1341 If this is true, store it as the current directory.
13422) If it is not a subdir of the current directory, try if this is a
1343 subdirectory of one of the upper directories.
13443) If the directory still isn't found, it is assumed to be a subdirectory
1345 of Vim's current directory.
1346
1347Additionally it is checked for every file, if it really exists in the
1348identified directory. If not, it is searched in all other directories of the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001349directory stack (NOT the directory subtree!). If it is still not found, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001350assumed that it is in Vim's current directory.
1351
Bram Moolenaare667c952010-07-05 22:57:59 +02001352There are limitations in this algorithm. These examples assume that make just
Bram Moolenaar071d4272004-06-13 20:20:40 +00001353prints information about entering a directory in the form "Making all in dir".
1354
13551) Assume you have following directories and files:
1356 ./dir1
1357 ./dir1/file1.c
1358 ./file1.c
1359
1360 If make processes the directory "./dir1" before the current directory and
1361 there is an error in the file "./file1.c", you will end up with the file
1362 "./dir1/file.c" loaded by Vim.
1363
1364 This can only be solved with a "leave directory" message.
1365
13662) Assume you have following directories and files:
1367 ./dir1
1368 ./dir1/dir2
1369 ./dir2
1370
1371 You get the following:
1372
1373 Make output Directory interpreted by Vim
1374 ------------------------ ----------------------------
1375 Making all in dir1 ./dir1
1376 Making all in dir2 ./dir1/dir2
1377 Making all in dir2 ./dir1/dir2
1378
1379 This can be solved by printing absolute directories in the "enter directory"
1380 message or by printing "leave directory" messages..
1381
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001382To avoid this problem, ensure to print absolute directory names and "leave
Bram Moolenaar071d4272004-06-13 20:20:40 +00001383directory" messages.
1384
1385Examples for Makefiles:
1386
1387Unix:
1388 libs:
1389 for dn in $(LIBDIRS); do \
1390 (cd $$dn; echo "Entering dir '$$(pwd)'"; make); \
1391 echo "Leaving dir"; \
1392 done
1393
1394Add
1395 %DEntering\ dir\ '%f',%XLeaving\ dir
1396to your 'errorformat' to handle the above output.
1397
1398Note that Vim doesn't check if the directory name in a "leave directory"
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001399messages is the current directory. This is why you could just use the message
Bram Moolenaar071d4272004-06-13 20:20:40 +00001400"Leaving dir".
1401
1402=============================================================================
14039. Specific error file formats *errorformats*
1404
1405 *errorformat-Jikes*
1406Jikes(TM), a source-to-bytecode Java compiler published by IBM Research,
1407produces simple multi-line error messages.
1408
1409An 'errorformat' string matching the produced messages is shown below.
1410The following lines can be placed in the user's |vimrc| to overwrite Vim's
1411recognized default formats, or see |:set+=| how to install this format
1412additionally to the default. >
1413
1414 :set efm=%A%f:%l:%c:%*\\d:%*\\d:,
1415 \%C%*\\s%trror:%m,
1416 \%+C%*[^:]%trror:%m,
1417 \%C%*\\s%tarning:%m,
1418 \%C%m
1419<
1420Jikes(TM) produces a single-line error message when invoked with the option
1421"+E", and can be matched with the following: >
1422
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001423 :setl efm=%f:%l:%v:%*\\d:%*\\d:%*\\s%m
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424<
1425 *errorformat-javac*
1426This 'errorformat' has been reported to work well for javac, which outputs a
1427line with "^" to indicate the column of the error: >
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001428 :setl efm=%A%f:%l:\ %m,%-Z%p^,%-C%.%#
Bram Moolenaar071d4272004-06-13 20:20:40 +00001429or: >
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001430 :setl efm=%A%f:%l:\ %m,%+Z%p^,%+C%.%#,%-G%.%#
Bram Moolenaar071d4272004-06-13 20:20:40 +00001431<
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001432Here is an alternative from Michael F. Lamb for Unix that filters the errors
1433first: >
1434 :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%#
Bram Moolenaar26df0922014-02-23 23:39:13 +01001435 :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter
Bram Moolenaar6b803a72007-05-06 14:25:46 +00001436
1437You need to put the following in "vim-javac-filter" somewhere in your path
1438(e.g., in ~/bin) and make it executable: >
1439 #!/bin/sed -f
1440 /\^$/s/\t/\ /g;/:[0-9]\+:/{h;d};/^[ \t]*\^/G;
1441
1442In English, that sed script:
1443- Changes single tabs to single spaces and
1444- Moves the line with the filename, line number, error message to just after
1445 the pointer line. That way, the unused error text between doesn't break
1446 vim's notion of a "multi-line message" and also doesn't force us to include
1447 it as a "continuation of a multi-line message."
1448
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449 *errorformat-ant*
1450For ant (http://jakarta.apache.org/) the above errorformat has to be modified
1451to honour the leading [javac] in front of each javac output line: >
1452 :set efm=%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1453
1454The 'errorformat' can also be configured to handle ant together with either
1455javac or jikes. If you're using jikes, you should tell ant to use jikes' +E
1456command line switch which forces jikes to generate one-line error messages.
1457This is what the second line (of a build.xml file) below does: >
1458 <property name = "build.compiler" value = "jikes"/>
1459 <property name = "build.compiler.emacs" value = "true"/>
1460
1461The 'errorformat' which handles ant with both javac and jikes is: >
1462 :set efm=\ %#[javac]\ %#%f:%l:%c:%*\\d:%*\\d:\ %t%[%^:]%#:%m,
1463 \%A\ %#[javac]\ %f:%l:\ %m,%-Z\ %#[javac]\ %p^,%-C%.%#
1464<
1465 *errorformat-jade*
1466parsing jade (see http://www.jclark.com/) errors is simple: >
1467 :set efm=jade:%f:%l:%c:%t:%m
1468<
1469 *errorformat-LaTeX*
1470The following is an example how an 'errorformat' string can be specified
1471for the (La)TeX typesetting system which displays error messages over
1472multiple lines. The output of ":clist" and ":cc" etc. commands displays
1473multi-lines in a single line, leading white space is removed.
1474It should be easy to adopt the above LaTeX errorformat to any compiler output
1475consisting of multi-line errors.
1476
1477The commands can be placed in a |vimrc| file or some other Vim script file,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001478e.g. a script containing LaTeX related stuff which is loaded only when editing
Bram Moolenaar071d4272004-06-13 20:20:40 +00001479LaTeX sources.
1480Make sure to copy all lines of the example (in the given order), afterwards
1481remove the comment lines. For the '\' notation at the start of some lines see
1482|line-continuation|.
1483
1484 First prepare 'makeprg' such that LaTeX will report multiple
1485 errors; do not stop when the first error has occurred: >
1486 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
1487<
1488 Start of multi-line error messages: >
1489 :set efm=%E!\ LaTeX\ %trror:\ %m,
1490 \%E!\ %m,
1491< Start of multi-line warning messages; the first two also
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001492 include the line number. Meaning of some regular expressions:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001493 - "%.%#" (".*") matches a (possibly empty) string
1494 - "%*\\d" ("\d\+") matches a number >
1495 \%+WLaTeX\ %.%#Warning:\ %.%#line\ %l%.%#,
1496 \%+W%.%#\ at\ lines\ %l--%*\\d,
1497 \%WLaTeX\ %.%#Warning:\ %m,
1498< Possible continuations of error/warning messages; the first
1499 one also includes the line number: >
1500 \%Cl.%l\ %m,
1501 \%+C\ \ %m.,
1502 \%+C%.%#-%.%#,
1503 \%+C%.%#[]%.%#,
1504 \%+C[]%.%#,
1505 \%+C%.%#%[{}\\]%.%#,
1506 \%+C<%.%#>%.%#,
1507 \%C\ \ %m,
1508< Lines that match the following patterns do not contain any
1509 important information; do not include them in messages: >
1510 \%-GSee\ the\ LaTeX%m,
1511 \%-GType\ \ H\ <return>%m,
1512 \%-G\ ...%.%#,
1513 \%-G%.%#\ (C)\ %.%#,
1514 \%-G(see\ the\ transcript%.%#),
1515< Generally exclude any empty or whitespace-only line from
1516 being displayed: >
1517 \%-G\\s%#,
1518< The LaTeX output log does not specify the names of erroneous
1519 source files per line; rather they are given globally,
1520 enclosed in parentheses.
1521 The following patterns try to match these names and store
1522 them in an internal stack. The patterns possibly scan over
1523 the same input line (one after another), the trailing "%r"
1524 conversion indicates the "rest" of the line that will be
1525 parsed in the next go until the end of line is reached.
1526
1527 Overread a file name enclosed in '('...')'; do not push it
1528 on a stack since the file apparently does not contain any
1529 error: >
1530 \%+O(%f)%r,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001531< Push a file name onto the stack. The name is given after '(': >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001532 \%+P(%f%r,
1533 \%+P\ %\\=(%f%r,
1534 \%+P%*[^()](%f%r,
1535 \%+P[%\\d%[^()]%#(%f%r,
1536< Pop the last stored file name when a ')' is scanned: >
1537 \%+Q)%r,
1538 \%+Q%*[^()])%r,
1539 \%+Q[%\\d%*[^()])%r
1540
1541Note that in some cases file names in the LaTeX output log cannot be parsed
1542properly. The parser might have been messed up by unbalanced parentheses
1543then. The above example tries to catch the most relevant cases only.
1544You can customize the given setting to suit your own purposes, for example,
1545all the annoying "Overfull ..." warnings could be excluded from being
1546recognized as an error.
1547Alternatively to filtering the LaTeX compiler output, it is also possible
1548to directly read the *.log file that is produced by the [La]TeX compiler.
1549This contains even more useful information about possible error causes.
1550However, to properly parse such a complex file, an external filter should
1551be used. See the description further above how to make such a filter known
1552by Vim.
1553
1554 *errorformat-Perl*
1555In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl
1556error messages into a format that quickfix mode will understand. See the
Bram Moolenaar8c8de832008-06-24 22:58:06 +00001557start of the file about how to use it. (This script is deprecated, see
1558|compiler-perl|.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001559
1560
1561
1562 vim:tw=78:ts=8:ft=help:norl: