usr_51.txt (27340B)
1 *usr_51.txt* For Vim version 9.2. Last change: 2026 Aug 23 2 3 4 VIM USER MANUAL by Bram Moolenaar 5 6 7 Write plugins 8 9 10 Plugins can be used to define settings for a specific type of file, syntax 11 highlighting and many other things. This chapter explains how to write the 12 most common Vim plugins. 13 14 |51.1| Writing a generic plugin 15 |51.2| Writing a filetype plugin 16 |51.3| Writing a compiler plugin 17 |51.4| Distributing Vim scripts 18 19 Next chapter: |usr_52.txt| Write large plugins 20 Previous chapter: |usr_50.txt| Advanced Vim script writing 21 Table of contents: |usr_toc.txt| 22 23 ============================================================================== 24 *51.1* Writing a generic plugin *write-plugin* 25 26 You can write a Vim script in such a way that many people can use it. This is 27 called a plugin. Vim users can drop your script in their plugin directory and 28 use its features right away |add-plugin|. 29 30 There are actually two types of plugins: 31 32 global plugins: For all types of files. 33 filetype plugins: Only for files of a specific type. 34 35 In this section the first type is explained. Most items are also relevant for 36 writing filetype plugins. The specifics for filetype plugins are in the next 37 section |write-filetype-plugin|. 38 39 We will use |Vim9| syntax here, the recommended way to write new plugins. 40 Make sure the file starts with the `vim9script` command. 41 42 43 NAME 44 45 First of all you must choose a name for your plugin. The features provided 46 by the plugin should be clear from its name. And it should be unlikely that 47 someone else writes a plugin with the same name but which does something 48 different. 49 50 A script that corrects typing mistakes could be called "typecorrect.vim". We 51 will use it here as an example. 52 53 For the plugin to work for everybody, it should follow a few guidelines. This 54 will be explained step-by-step. The complete example plugin is at the end. 55 56 57 BODY 58 59 Let's start with the body of the plugin, the lines that do the actual work: > 60 61 12 iabbrev teh the 62 13 iabbrev otehr other 63 14 iabbrev wnat want 64 15 iabbrev synchronisation 65 16 \ synchronization 66 67 The actual list should be much longer, of course. 68 69 The line numbers have only been added to explain a few things, don't put them 70 in your plugin file! 71 72 73 FIRST LINE 74 > 75 1 vim9script noclear 76 77 You need to use `vim9script` as the very first command. Best is to put it in 78 the very first line. 79 80 The script we are writing will have a `finish` command to bail out when it is 81 loaded a second time. To avoid that the items defined in the script are lost 82 the "noclear" argument is used. More info about this at |vim9-reload|. 83 84 85 HEADER 86 87 You will probably add new corrections to the plugin and soon have several 88 versions lying around. And when distributing this file, people will want to 89 know who wrote this wonderful plugin and where they can send remarks. 90 Therefore, put a header at the top of your plugin: > 91 92 2 # Vim global plugin for correcting typing mistakes 93 3 # Last Change: 2021 Dec 30 94 4 # Maintainer: Bram Moolenaar <Bram@vim.org> 95 96 About copyright and licensing: Since plugins are very useful and it's hardly 97 worth restricting their distribution, please consider making your plugin 98 either public domain or use the Vim |license|. A short note about this near 99 the top of the plugin should be sufficient. Example: > 100 101 5 # License: This file is placed in the public domain. 102 103 104 NOT LOADING 105 106 It is possible that a user doesn't always want to load this plugin. Or the 107 system administrator has dropped it in the system-wide plugin directory, but a 108 user has their own plugin they want to use. Then the user must have a chance 109 to disable loading this specific plugin. These lines will make it possible: > 110 111 7 if exists("g:loaded_typecorrect") 112 8 finish 113 9 endif 114 10 g:loaded_typecorrect = 1 115 116 This also avoids that when the script is loaded twice it would pointlessly 117 redefine functions and cause trouble for autocommands that are added twice. 118 119 The name is recommended to start with "g:loaded_" and then the file name of 120 the plugin, literally. The "g:" is prepended to make the variable global, so 121 that other places can check whether its functionality is available. Without 122 "g:" it would be local to the script. 123 124 Using `finish` stops Vim from reading the rest of the file, it's much quicker 125 than using if-endif around the whole file, since Vim would still need to parse 126 the commands to find the `endif`. 127 128 129 MAPPING 130 131 Now let's make the plugin more interesting: We will add a mapping that adds a 132 correction for the word under the cursor. We could just pick a key sequence 133 for this mapping, but the user might already use it for something else. To 134 allow the user to define which keys a mapping in a plugin uses, the <Leader> 135 item can be used: > 136 137 20 map <unique> <Leader>a <Plug>(TypecorrAdd) 138 139 The "<Plug>(TypecorrAdd)" thing will do the work, more about that further on. 140 141 The user can set the "g:mapleader" variable to the key sequence that they want 142 plugin mappings to start with. Thus if the user has done: > 143 144 g:mapleader = "_" 145 146 the mapping will define "_a". If the user didn't do this, the default value 147 will be used, which is a backslash. Then a map for "\a" will be defined. 148 149 Note that <unique> is used, this will cause an error message if the mapping 150 already happened to exist. |:map-<unique>| 151 152 But what if the user wants to define their own key sequence? We can allow 153 that with this mechanism: > 154 155 19 if !hasmapto('<Plug>(TypecorrAdd)') 156 20 map <unique> <Leader>a <Plug>(TypecorrAdd) 157 21 endif 158 159 This checks if a mapping to "<Plug>(TypecorrAdd)" already exists, and only 160 defines the mapping from "<Leader>a" if it doesn't. The user then has a 161 chance of putting this in their vimrc file: > 162 163 map ,c <Plug>(TypecorrAdd) 164 165 Then the mapped key sequence will be ",c" instead of "_a" or "\a". 166 167 168 PIECES 169 170 If a script gets longer, you often want to break up the work in pieces. You 171 can use functions or mappings for this. But you don't want these functions 172 and mappings to interfere with the ones from other scripts. For example, you 173 could define a function Add(), but another script could try to define the same 174 function. To avoid this, we define the function local to the script. 175 Fortunately, in |Vim9| script this is the default. In a legacy script you 176 would need to prefix the name with "s:". 177 178 We will define a function that adds a new typing correction: > 179 180 28 def Add(from: string, correct: bool) 181 29 var to = input($"type the correction for {from}: ") 182 30 exe $":iabbrev {from} {to}" 183 ... 184 34 enddef 185 186 Now we can call the function Add() from within this script. If another 187 script also defines Add(), it will be local to that script and can only 188 be called from that script. There can also be a global g:Add() function, 189 which is again another function. 190 191 <SID> can be used with mappings. It generates a script ID, which identifies 192 the current script. In our typing correction plugin we use it like this: > 193 194 22 noremap <unique> <script> <Plug>(TypecorrAdd) <SID>Add 195 ... 196 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR> 197 198 Thus when a user types "\a", this sequence is invoked: > 199 200 \a -> <Plug>(TypecorrAdd) -> <SID>Add -> :call <SID>Add(...) 201 202 If another script also maps <SID>Add, it will get another script ID and 203 thus define another mapping. 204 205 Note that instead of Add() we use <SID>Add() here. That is because the 206 mapping is typed by the user, thus outside of the script context. The <SID> 207 is translated to the script ID, so that Vim knows in which script to look for 208 the Add() function. 209 210 This is a bit complicated, but it's required for the plugin to work together 211 with other plugins. The basic rule is that you use <SID>Add() in mappings and 212 Add() in other places (the script itself, autocommands, user commands). 213 214 We can also add a menu entry to do the same as the mapping: > 215 216 24 noremenu <script> Plugin.Add\ Correction <SID>Add 217 218 The "Plugin" menu is recommended for adding menu items for plugins. In this 219 case only one item is used. When adding more items, creating a submenu is 220 recommended. For example, "Plugin.CVS" could be used for a plugin that offers 221 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc. 222 223 Note that in line 26 ":noremap" is used to avoid that any other mappings cause 224 trouble. Someone may have remapped ":call", for example. In line 22 we also 225 use ":noremap", but we do want "<SID>Add" to be remapped. This is why 226 "<script>" is used here. This only allows mappings which are local to the 227 script. |:map-<script>| The same is done in line 24 for ":noremenu". 228 |:menu-<script>| 229 230 231 <SID> AND <Plug> *using-<Plug>* 232 233 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere 234 with mappings that are only to be used from other mappings. Note the 235 difference between using <SID> and <Plug>: 236 237 <Plug> is visible outside of the script. It is used for mappings which the 238 user might want to map a key sequence to. <Plug> is a special code 239 that a typed key will never produce. 240 To make it very unlikely that other plugins use the same sequence of 241 characters, use this structure: <Plug> scriptname mapname 242 In our example the scriptname is "Typecorr" and the mapname is "Add". 243 We wrap the name in parentheses. This results in 244 "<Plug>(TypecorrAdd)". The convention of using PascalCase helps 245 telling scriptname apart from mapname. 246 247 Note: the text after "<Plug>" is chosen by the plugin author and is 248 entirely arbitrary. Wrapping the name in parentheses, using 249 PascalCase, or adding a ";" terminator like "<Plug>TypecorrAdd;" are 250 only conventions to keep the name readable and unlikely to clash with 251 other plugins. None of them are required: all that matters is that 252 the sequence starts with "<Plug>" and is unique. 253 A mapping whose {lhs} starts with <Plug> is always applied to the 254 {rhs} of another mapping, even if remapping is explicitly disallowed. 255 |:nore| 256 257 <SID> is the script ID, a unique identifier for a script. 258 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any 259 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()" 260 in one script, and "<SNR>22_Add()" in another. You can see this if 261 you use the ":function" command to get a list of functions. The 262 translation of <SID> in mappings is exactly the same, that's how you 263 can call a script-local function from a mapping. 264 Note: when <SID> appears in the {rhs} of a mapping, you might consider 265 using <script>. |:map-<script>| 266 267 268 USER COMMAND 269 270 Now let's add a user command to add a correction: > 271 272 36 if !exists(":Correct") 273 37 command -nargs=1 Correct :call Add(<q-args>, false) 274 38 endif 275 276 The user command is defined only if no command with the same name already 277 exists. Otherwise we would get an error here. Overriding the existing user 278 command with ":command!" is not a good idea, this would probably make the user 279 wonder why the command they defined themselves doesn't work. |:command| 280 If it did happen you can find out who to blame with: > 281 282 verbose command Correct 283 284 285 SCRIPT VARIABLES 286 287 When a variable starts with "s:" it is a script variable. It can only be used 288 inside a script. Outside the script it's not visible. This avoids trouble 289 with using the same variable name in different scripts. The variables will be 290 kept as long as Vim is running. And the same variables are used when sourcing 291 the same script again. |s:var| 292 293 The nice thing about |Vim9| script is that variables are local to the script 294 by default. You can prepend "s:" if you like, but you do not need to. And 295 functions in the script can also use the script variables without a prefix 296 (they must be declared before the function for this to work). 297 298 Script-local variables can also be used in functions, autocommands and user 299 commands that are defined in the script. Thus they are the perfect way to 300 share information between parts of your plugin, without it leaking out. In 301 our example we can add a few lines to count the number of corrections: > 302 303 17 var count = 4 304 ... 305 28 def Add(from: string, correct: bool) 306 ... 307 32 count += 1 308 33 echo "you now have " .. count .. " corrections" 309 34 enddef 310 311 "count" is declared and initialized to 4 in the script itself. When later 312 the Add() function is called, it increments "count". It doesn't matter from 313 where the function was called, since it has been defined in the script, it 314 will use the local variables from this script. 315 316 317 THE RESULT 318 319 Here is the resulting complete example: > 320 321 1 vim9script noclear 322 2 # Vim global plugin for correcting typing mistakes 323 3 # Last Change: 2021 Dec 30 324 4 # Maintainer: Bram Moolenaar <Bram@vim.org> 325 5 # License: This file is placed in the public domain. 326 6 327 7 if exists("g:loaded_typecorrect") 328 8 finish 329 9 endif 330 10 g:loaded_typecorrect = 1 331 11 332 12 iabbrev teh the 333 13 iabbrev otehr other 334 14 iabbrev wnat want 335 15 iabbrev synchronisation 336 16 \ synchronization 337 17 var count = 4 338 18 339 19 if !hasmapto('<Plug>(TypecorrAdd)') 340 20 map <unique> <Leader>a <Plug>(TypecorrAdd) 341 21 endif 342 22 noremap <unique> <script> <Plug>(TypecorrAdd) <SID>Add 343 23 344 24 noremenu <script> Plugin.Add\ Correction <SID>Add 345 25 346 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR> 347 27 348 28 def Add(from: string, correct: bool) 349 29 var to = input($"type the correction for {from}: ") 350 30 exe $":iabbrev {from} {to}" 351 31 if correct | exe "normal viws\<C-R>\" \b\e" | endif 352 32 count += 1 353 33 echo "you now have " .. count .. " corrections" 354 34 enddef 355 35 356 36 if !exists(":Correct") 357 37 command -nargs=1 Correct call Add(<q-args>, false) 358 38 endif 359 360 Line 31 wasn't explained yet. It applies the new correction to the word under 361 the cursor. The |:normal| command is used to use the new abbreviation. Note 362 that mappings and abbreviations are expanded here, even though the function 363 was called from a mapping defined with ":noremap". 364 365 366 DOCUMENTATION *write-local-help* 367 368 It's a good idea to also write some documentation for your plugin. Especially 369 when its behavior can be changed by the user. See |help-writing| for the 370 syntax used by the help files and |add-local-help| for how local help files 371 are installed. 372 373 Here is a simple example for a plugin help file, called "typecorrect.txt": > 374 375 1 *typecorrect.txt* Plugin for correcting typing mistakes 376 2 377 3 If you make typing mistakes, this plugin will have them corrected 378 4 automatically. 379 5 380 6 There are currently only a few corrections. Add your own if you like. 381 7 382 8 Mappings: 383 9 <Leader>a or <Plug>(TypecorrAdd) 384 10 Add a correction for the word under the cursor. 385 11 386 12 Commands: 387 13 :Correct {word} 388 14 Add a correction for {word}. 389 15 390 16 *typecorrect-settings* 391 17 This plugin doesn't have any settings. 392 393 The first line is actually the only one for which the format matters. It will 394 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of 395 help.txt |local-additions|. The first "*" must be in the first column of the 396 first line. After adding your help file do ":help" and check that the entries 397 line up nicely. 398 399 You can add more tags inside ** in your help file. But be careful not to use 400 existing help tags. You would probably use the name of your plugin in most of 401 them, like "typecorrect-settings" in the example. 402 403 Using references to other parts of the help in || is recommended. This makes 404 it easy for the user to find associated help. 405 406 407 SUMMARY *plugin-special* 408 409 Summary of special things to use in a plugin: 410 411 var name Variable local to the script. 412 413 <SID> Script-ID, used for mappings and functions local to 414 the script. 415 416 hasmapto() Function to test if the user already defined a mapping 417 for functionality the script offers. 418 419 <Leader> Value of "mapleader", which the user defines as the 420 keys that plugin mappings start with. 421 422 map <unique> Give a warning if a mapping already exists. 423 424 noremap <script> Only remap mappings defined in this script that start 425 with <SID>. 426 427 exists(":Cmd") Check if a user command already exists. 428 429 ============================================================================== 430 *51.2* Writing a filetype plugin *write-filetype-plugin* *ftplugin* 431 432 A filetype plugin is like a global plugin, except that it sets options and 433 defines mappings for the current buffer only. See |add-filetype-plugin| for 434 how this type of plugin is used. 435 436 First read the section on global plugins above |51.1|. All that is said there 437 also applies to filetype plugins. There are a few extras, which are explained 438 here. The essential thing is that a filetype plugin should only have an 439 effect on the current buffer. 440 441 442 DISABLING 443 444 If you are writing a filetype plugin to be used by many people, they need a 445 chance to disable loading it. Put this at the top of the plugin: > 446 447 # Only do this when not done yet for this buffer 448 if exists("b:did_ftplugin") 449 finish 450 endif 451 b:did_ftplugin = 1 452 453 This also needs to be used to avoid that the same plugin is executed twice for 454 the same buffer (happens when using an ":edit" command without arguments). 455 456 Now users can disable loading the default plugin completely by making a 457 filetype plugin with only these lines: > 458 459 vim9script 460 b:did_ftplugin = 1 461 462 This does require that the filetype plugin directory comes before $VIMRUNTIME 463 in 'runtimepath'! 464 465 If you do want to use the default plugin, but overrule one of the settings, 466 you can write the different setting in a script: > 467 468 setlocal textwidth=70 469 470 Now write this in the "after" directory, so that it gets sourced after the 471 distributed "vim.vim" ftplugin |after-directory|. For Unix this would be 472 "~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set 473 "b:did_ftplugin", it is ignored here. 474 475 476 OPTIONS 477 478 To make sure the filetype plugin only affects the current buffer use the > 479 480 setlocal 481 482 command to set options. And only set options which are local to a buffer (see 483 the help for the option to check that). When using `:setlocal` for global 484 options or options local to a window, the value will change for many buffers, 485 and that is not what a filetype plugin should do. 486 487 When an option has a value that is a list of flags or items, consider using 488 "+=" and "-=" to keep the existing value. Be aware that the user may have 489 changed an option value already. First resetting to the default value and 490 then changing it is often a good idea. Example: > 491 492 setlocal formatoptions& formatoptions+=ro 493 494 495 MAPPINGS 496 497 To make sure mappings will only work in the current buffer use the > 498 499 map <buffer> 500 501 command. This needs to be combined with the two-step mapping explained above. 502 An example of how to define functionality in a filetype plugin: > 503 504 if !hasmapto('<Plug>JavaImport;') 505 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport; 506 endif 507 noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc> 508 509 |hasmapto()| is used to check if the user has already defined a map to 510 <Plug>JavaImport;. If not, then the filetype plugin defines the default 511 mapping. This starts with |<LocalLeader>|, which allows the user to select 512 the key(s) they want filetype plugin mappings to start with. The default is a 513 backslash. 514 "<unique>" is used to give an error message if the mapping already exists or 515 overlaps with an existing mapping. 516 |:noremap| is used to avoid that any other mappings that the user has defined 517 interferes. You might want to use ":noremap <script>" to allow remapping 518 mappings defined in this script that start with <SID>. 519 520 The user must have a chance to disable the mappings in a filetype plugin, 521 without disabling everything. Here is an example of how this is done for a 522 plugin for the mail filetype: > 523 524 # Add mappings, unless the user didn't want this. 525 if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps") 526 # Quote text by inserting "> " 527 if !hasmapto('<Plug>MailQuote;') 528 vmap <buffer> <LocalLeader>q <Plug>MailQuote; 529 nmap <buffer> <LocalLeader>q <Plug>MailQuote; 530 endif 531 vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR> 532 nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR> 533 endif 534 535 Two global variables are used: 536 |g:no_plugin_maps| disables mappings for all filetype plugins 537 |g:no_mail_maps| disables mappings for the "mail" filetype 538 539 540 USER COMMANDS 541 542 To add a user command for a specific file type, so that it can only be used in 543 one buffer, use the "-buffer" argument to |:command|. Example: > 544 545 command -buffer Make make %:r.s 546 547 548 VARIABLES 549 550 A filetype plugin will be sourced for each buffer of the type it's for. Local 551 script variables will be shared between all invocations. Use local buffer 552 variables |b:var| if you want a variable specifically for one buffer. 553 554 555 FUNCTIONS 556 557 When defining a function, this only needs to be done once. But the filetype 558 plugin will be sourced every time a file with this filetype will be opened. 559 This construct makes sure the function is only defined once: > 560 561 if !exists("*Func") 562 def Func(arg) 563 ... 564 enddef 565 endif 566 < 567 Don't forget to use "noclear" with the `vim9script` command to avoid that the 568 function is deleted when the script is sourced a second time. 569 570 571 UNDO *undo_indent* *undo_ftplugin* 572 573 When the user does ":setfiletype xyz" the effect of the previous filetype 574 should be undone. Set the b:undo_ftplugin variable to the commands that will 575 undo the settings in your filetype plugin. Example: > 576 577 b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" 578 \ .. "| unlet b:match_ignorecase b:match_words b:match_skip" 579 580 Using ":setlocal" with "<" after the option name resets the option to its 581 global value. That is mostly the best way to reset the option value. 582 583 For undoing the effect of an indent script, the b:undo_indent variable should 584 be set accordingly. 585 586 Both these variables use legacy script syntax, not |Vim9| syntax. 587 588 RECOMMENDED STYLE *ft_recommended_style* 589 590 A filetype plugin or indent script may set options that reflect a 591 recommended or commonly used style for that filetype, rather than a strict 592 requirement of the language. Since not every user wants these stylistic 593 settings, guard them so they can be disabled. 594 595 Check two variables, the filetype-specific one first, then the general one, 596 defaulting to enabled (1): > 597 598 if get(g:, '<filetype>_recommended_style', 599 \ get(g:, 'filetype_recommended_style', 1)) 600 " set the recommended style options here 601 endif 602 603 Replace <filetype> with the actual filetype name, e.g. "python" gives 604 g:python_recommended_style. 605 606 This lets the user turn recommended style settings off for all filetypes: > 607 608 let g:filetype_recommended_style = 0 609 610 or for one filetype while leaving the rest enabled: > 611 612 let g:python_recommended_style = 0 613 614 The filetype-specific variable takes precedence over the general one, so a 615 user can disable styling everywhere with g:filetype_recommended_style and 616 re-enable it for a single filetype by setting g:<filetype>_recommended_style 617 to 1 (or vice versa). 618 619 Settings that are required for the language to work correctly (not merely 620 stylistic) should not be placed behind this guard. 621 622 FILE NAME 623 624 The filetype must be included in the file name |ftplugin-name|. Use one of 625 these three forms: 626 627 .../ftplugin/stuff.vim 628 .../ftplugin/stuff_foo.vim 629 .../ftplugin/stuff/bar.vim 630 631 "stuff" is the filetype, "foo" and "bar" are arbitrary names. 632 633 634 FILETYPE DETECTION *plugin-filetype* 635 636 If your filetype is not already detected by Vim, you should create a filetype 637 detection snippet in a separate file. It is usually in the form of an 638 autocommand that sets the filetype when the file name matches a pattern. 639 Example: > 640 641 au BufNewFile,BufRead *.foo setlocal filetype=foofoo 642 643 Write this single-line file as "ftdetect/foofoo.vim" in the first directory 644 that appears in 'runtimepath'. For Unix that would be 645 "~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the 646 filetype for the script name. 647 648 You can make more complicated checks if you like, for example to inspect the 649 contents of the file to recognize the language. Also see |new-filetype|. 650 651 652 SUMMARY *ftplugin-special* 653 654 Summary of special things to use in a filetype plugin: 655 656 <LocalLeader> Value of "maplocalleader", which the user defines as 657 the keys that filetype plugin mappings start with. 658 659 map <buffer> Define a mapping local to the buffer. 660 661 noremap <script> Only remap mappings defined in this script that start 662 with <SID>. 663 664 setlocal Set an option for the current buffer only. 665 666 command -buffer Define a user command local to the buffer. 667 668 exists("*s:Func") Check if a function was already defined. 669 670 Also see |plugin-special|, the special things used for all plugins. 671 672 ============================================================================== 673 *51.3* Writing a compiler plugin *write-compiler-plugin* 674 675 A compiler plugin sets options for use with a specific compiler. The user can 676 load it with the |:compiler| command. The main use is to set the 677 'errorformat' and 'makeprg' options. 678 679 Easiest is to have a look at examples. This command will edit all the default 680 compiler plugins: > 681 682 next $VIMRUNTIME/compiler/*.vim 683 684 Type `:next` to go to the next plugin file. 685 686 There are two special items about these files. First is a mechanism to allow 687 a user to overrule or add to the default file. The default files start with: > 688 689 vim9script 690 if exists("g:current_compiler") 691 finish 692 endif 693 g:current_compiler = "mine" 694 695 When you write a compiler file and put it in your personal runtime directory 696 (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to 697 make the default file skip the settings. 698 *:CompilerSet* 699 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for 700 ":compiler". Vim defines the ":CompilerSet" user command for this. This is 701 an example: > 702 703 CompilerSet errorformat& " use the default 'errorformat' 704 CompilerSet makeprg=nmake 705 706 Note: arguments need to be escaped according to |option-backslash|. 707 708 When you write a compiler plugin for the Vim distribution or for a system-wide 709 runtime directory, use the mechanism mentioned above. When 710 "current_compiler" was already set by a user plugin nothing will be done. 711 712 When you write a compiler plugin to overrule settings from a default plugin, 713 don't check "current_compiler". This plugin is supposed to be loaded 714 last, thus it should be in a directory at the end of 'runtimepath'. For Unix 715 that could be ~/.vim/after/compiler. 716 717 ============================================================================== 718 *51.4* Distributing Vim scripts *distribute-script* 719 720 Vim users will look for scripts on the Vim website: http://www.vim.org. 721 If you made something that is useful for others, share it! 722 723 Another place is github. But there you need to know where to find it! The 724 advantage is that most plugin managers fetch plugins from github. You'll have 725 to use your favorite search engine to find them. 726 727 Vim scripts can be used on any system. However, there might not be a tar or 728 gzip command. If you want to pack files together and/or compress them the 729 "zip" utility is recommended. 730 731 For utmost portability use Vim itself to pack scripts together. This can be 732 done with the Vimball utility. See |vimball|. 733 734 It's good if you add a line to allow automatic updating. See |glvs-plugins|. 735 736 ============================================================================== 737 738 Next chapter: |usr_52.txt| Write large plugins 739 740 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: