-
Notifications
You must be signed in to change notification settings - Fork 59
/
vim-addon-manager-additional-documentation.txt
1405 lines (1163 loc) · 66.9 KB
/
vim-addon-manager-additional-documentation.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*vim-addon-manager-additional-documentation.txt* Declarative package manager for Vim
==============================================================================
CONTENTS *VAM-contents-additional*
In |vim-addon-manager-getting-started.txt|:
1. Intro |VAM-intro|
2. Installation & installing plugins |VAM-installation|
2.2. Names of addons and addon sources |VAM-addon-names|
2.3. Example: configurable setup |VAM-complex-setup-sample|
2.4. unattended installation |VAM-unattended-installation|
2.5. Searching the plugins |VAM-plugins-search|
Here:
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
4. Options |VAM-options|
6. Uninstalling plugins |VAM-uninstall-plugins|
7. Addon-info file |VAM-addon-info|
8. Author, credits, some notes |VAM-related|
9. Testing this plugin |VAM-testing|
10. Some notes for windows users |VAM-windows|
11. Some notes for Gentoo users |VAM-gentoo|
12. Troubleshooting and known bugs |VAM-trouble-shooting|
12.1. Common error messages |VAM-common-errors|
13. TODO notes |VAM-TODO|
14. VAM vs ... |VAM-comparison|
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
16.1. The perfect plugin |VAM-plugin-guide|
17. VAM tricks and hacks |VAM-tricks|
==============================================================================
3. Functionality provided *VAM-functionality*
------------------------------------------------------------------------------
3.1. Commands *VAM-commands*
InstallAddons {name} ... *:InstallAddons*
Install addons with given names. See |vam#install#Install()| for
more details.
You use InstallAddons instead of ActivateAddons if you want to review
plugin source before running it. Also see |:RunInstallHooks|, it may
be required to complete installation.
RunInstallHooks {name} ... *:RunInstallHooks*
Run post-install hooks for given plugins. Required if plugin has been
installed using |:InstallAddons| and has hooks that are needed for it
to work.
ActivateAddons {name} ... *:ActivateAddons*
Activate addons with given names. See |vam#ActivateAddons()| for
more details.
ActivateInstalledAddons {name} ... *:ActivateInstalledAddons*
See |:ActivateAddons|, this command is just the same, but completion
function completes only installed addon names.
UpdateAddons [{name} ...] *:UpdateAddons*
Update addons with given names. Without arguments updates all addons.
See |vam#install#Update()| for more details.
UpdateActivatedAddons *:UpdateActivatedAddons*
Like |:UpdateAdons| with a list of all activated plugins in place of
its arguments.
ListActivatedAddons *:ListActivatedAddons*
List all currently activated addons.
UninstallNotLoadedAddons {name} ... *:UninstallNotLoadedAddons*
Unistall addons with given names. See
|vam#install#UninstallAddons()| for more details.
AddonsInfo {id/name/any-regex} ... *:AddonsInfo*
Shows addon information. Accepts both VAM script names and www.vim.org
script numbers. If neither succeeds the any-regex is used and compared
against any field of the repository dictionaries. Thus you can use it
to find addons by github url etc. Its best to use the directory part
of the url only. because github urls can be written using git@ or
https:// and with or without trailing ".git" in some cases.
*:OKVAMBisect* *:BADVAMBisect*
AddonsBisect [vim] [arg1] ... *:AddonsBisect*
Command that helps find which one of the activated plugins is causing
the problem. In order to do this it launches new vim instance which
will activate only half (1/4, 1/8 and so on) of the plugins currently
activated. In newly launched vim you are able to use :OKVAMBisect
command to mark this set of plugins as non-problematic and
:BADVAMBisect to mark this set of plugins as problematic. It will
repeat bisection until there is only one plugin in the list.
If arguments are given they are used as a command that launches vim.
If you know how to make vim test whether problem occurs use >
AddonsBisect vim -c if\ has(problem)|BADVAMBisect|else|OKVAMBisect|endif
< (note the space escaping).
------------------------------------------------------------------------------
3.2. Functions *VAM-functions*
vam#ActivateAddons({addons}[, {opts}]) *vam#ActivateAddons()*
Installs and activates plugins listed in {addons} (see description of
|vam#install#Install()|) list alongside with their dependencies. This
is meant to be called from your .vimrc. Installation takes place only
if plugin directory does not exist. Activation means adding plugin
directory to 'runtimepath'. If vim has already started VAM will also
source plugin/**/*.vim (in other case sourcing is done by vim).
Optional {opts} argument should be a dictionary with one of the
following keys:
Key Description ~
auto_install Boolean, overrides |VAM-auto_install|.
force_loading_plugins_now Boolean. By default plugins are sourced
only if has("vim_starting") is false
because if it is true and VAM was called
from vimrc, then plugins will be loaded by
vim itself after adding them to 'rtp'. But
if VAM was called from a plugin after vim
started loading them new additions to
'runtimepath' may be ignored by vim, hence
the option.
In order to manually activate plugins try using |:ActivateAddons|
which also provides completion.
Implementation details: ~
Vim's startup behaviour is:
1. source ~/.vimrc
2. find all plugin/*.vim files in &rtp
3. source them
4. emit the VimEnter au command
Now it does not do its job 2. properly: some after/* files are not
sources. If you add paths rtp at runtime plugin/* files aren't sourced
either. VAM takes care of this for you - but changing source order may
fail in rare cases.
vam#install#Install({addons}[, {opts}]) *vam#install#Install()*
Installs plugins listed in {addons} list. Each list item must be one
of the following:
- Name of the plugin
- Path to |addon-info.txt| file (it must contain at least one
forward or back slash, so use `./plugname-addon-info.txt' for
files located in the current directory)i
- |addon-info.txt| URL. In this case {arg} must start with
“http://” or “https://”.
After installing the plugin help tags are updated, see |:helptags|.
{addons}: See |VAM-addon-names|
{opts} argument is described in |vam#ActivateAddons()|.
vam#install#Update({addons}) *vam#install#Update()*
Updates plugins which names are listed in {addons}. If an empty list
is given, then updates all plugins. vam#install#Update also updates
the help tags. Note that if plugin is not under control of some VCS,
it tries to retain user changes unless |VAM-do_diff| is disabled.
vam#AddonInfo({name}) *vam#AddonInfo()*
Returns dictionary that contains information given in |addon-info.txt|
file that comes with requested addon. If no |addon-info.txt| file is
present, it is not readable or addon with given name is not installed,
then it returns an empty dictionary.
*vam#install#MergePluginFiles()*
vam#install#MergePluginFiles([{name}] [, blacklist-regex ])
Highly experimental function that may speed up vim start on heavy IO
load. This function renames all `plugin' directories to
contents into `~/.vim/after/plugin/vim-addon-manager-merged.vim' which
should cause less IO stress to your system, thus Vim will startup
faster. This can scripts because:
- s:... script global variables are renamed automatically to
prevent name clashes
- Guards are replaced by if ... endif which might be inefficient
- `finish' statement that start line and every line after them are
just commented out
Using the blacklist-regex you can filter plugin/*.vim files and
prevent them from being included. For example this excludes many tlib
plugins.: >
let s:merge = [ "tlib" ]
call vam#ActivateAddons(s:merge)
command MergePluginFiles call vam#install#MergePluginFiles(s:merge+["tlib"], '\%(cmdlinehelp\|concordance\|evalselection\|glark\|hookcursormoved\|linglang\|livetimestamp\|localvariables\|loremipsum\|my_tinymode\|pim\|quickfixsigns\|scalefont\|setsyntax\|shymenu\|spec\|tassert\|tbak\|tbibtools\|tcalc\|tcomment\|techopair\|tgpg\|tmarks\|tmboxbrowser\|tortoisesvn\|tregisters\|tselectbuffer\|tselectfile\|tsession\|tskeleton\|tstatus\|viki\|vikitasks\)\.vim_merged')
command UnmergePluginFiles call vam#install#UnmergePluginFiles()
<
Yes, the info files should be cached as well (TODO)
vam#install#RewriteName({name}) *vam#install#RewriteName()*
Returns a dictionary if {name} matches one of the following patterns:
Pattern Dictionary ~
github:{Name} {"type": "git",
"url": "https://github.com/{Name}/vim-addon-{Name}}
github:{N}/{Repo} {"type": "git",
"url": "https://github.com/{N}/{Repo}"}
git:{URL} {"type": "git", "url": {URL}} (experimental)
hg:{URL} {"type": "hg", "url": {URL}} (experimental)
vam#install#CompleteAddonName *vam#install#CompleteAddonName()*
Function suitable to be a completion function for omni completion
('omnifunc'). Completes addon names. See also |VAM-addon_completion_lhs|.
vam#vcs#GitCheckout *vam#vcs#GitCheckout*
vam#vcs#MercurialCheckout *vam#vcs#MercurialCheckout*
vam#vcs#SubversionCheckout *vam#vcs#SubversionCheckout*
Functions that do their best to checkout plugins, trying various
additional methods:
SCM Additional methods tried ~
git Mercurial with hg-git, bazaar with bzr-git,
github/bitbucket bundles
hg Bitbucket bundles
svn Mercurial with hgsubversion, bazaar with bzr-svn
To use them add the following to the vimrc: >
let g:vim_addon_manager={'scms': {'git': {}, 'svn': {}, 'hg': {}}}
let g:vim_addon_manager.scms.git.clone=['vam#vcs#GitCheckout']
let g:vim_addon_manager.scms.hg.clone =['vam#vcs#MercurialCheckout']
let g:vim_addon_manager.scms.svn.clone=['vam#vcs#SubversionCheckout']
==============================================================================
4. Options *VAM-options*
*g:vim_addon_manager*
All options are located in the global dictionary g:vim_addon_manager. You can
set them this way: >
let g:vim_addon_manager = {}
let g:vim_addon_manager.auto_install = 1
let g:vim_addon_manager.do_diff = 0
" ...
< where KEY_NAME is one of auto_install, plugin_sources, ... (see below)
It also contains some stuff that user should never modify if he wants to see
this plugin working. Possible keys:
auto_install *VAM-auto_install*
This options disables plugin installation confirmation. It will not
disable deprecation warnings and other prompts.
plugin_sources *VAM-plugin_sources*
This option contains a dictionary where keys are plugin names and
values are described by |addon-info-repository|. Values defined in
this dictionary override corresponding values in |addon-info.txt|
files, so be careful when you extend it.
plugin_root_dir *VAM-plugin_root_dir*
Defines a directory where plugins will be installed to. If directory
where this plugin is installed to (three levels up relative to
autoload/vam.vim: autoload/../..) is writeable by user, then it
defaults to directory in question (so, if user has installed
vim-addon-manager to ~/.vim/bundle/vim-addon-manager, this will be
equal to ~/.vim/bundle). If it is not writeable by the user, then it
defaults to ~/.vim/vim-addons.
Note that you must set this variable before calling any vam function.
Note 2: it may be ignored in custom |VAM-plugin_dir_by_name|.
Note 3: Utilized by |VAM-plugin_dir_by_name|. If you override that
function option may have effect only on a limited set of
undocumented options.
additional_addon_dirs *VAM-additional-addon-dirs*
List of directories. If present, plugins will be looked up in those
directories additionally to |VAM-plugin_root_dir|.
Note: Utilized by |VAM-plugin_dir_by_name|. If you override that
function option may have no effect.
*VAM-known_repos_activation_policy*
known_repos_activation_policy
String, valid values: `ask', `never' and `autoload' (default). Defines
when |VAM-known| plugin should be loaded. `Ask' means that user will
be prompted when this option is required. `Never' means that
|VAM-known| will not be loaded and the user will not get any prompts.
`Autoload' means that it will be loaded when it is required, user also
won't get asked.
known *VAM-known*
String, specifies the name of plugin which provides list of
repositories. Default is vim-pi.
change_to_unix_ff *VAM-change_to_unix_ff*
Remove CR symbols before LF symbols in any vim files (changes dos and
mixed dos/unix line endings to unix line endings). Is on by default if
you are on unix (unix, win32unix, macunix), off otherwise.
do_diff *VAM-do_diff*
If this option is true (default), then try to retain user changes to
installed plugins (unless they are under SCM control). Requires diff
and patch programs installed.
name_rewriting *VAM-name_rewriting*
Set this to a dictionary with functions each taking a plugin name and
returning either a dictionary with repository location (see
|addon-info-repository|) for given name or zero. Location will be set
to the first non-zero value, functions are executed in order
determined by |sort()|ing |keys()| of the dictionary. These functions
will be called when repository location for requested plugin is not
found.
Value will be extended with >
{"99git+github": "vam#install#RewriteName"}
< after it is read (see |vam#install#RewriteName()|).
plugin_dir_by_name *VAM-plugin_dir_by_name*
Function name or function reference that transforms plugin names into
absolute paths plugins are to be installed into. Function must return
path without trailing path separators or |VAM-do_diff| will break.
Default is "vam#DefaultPluginDirFromName".
scms *VAM-scms*
This option determines how sources with supported SCM's should be
checked out and updated. It is a dictionary where keys are known SCM's
and values are dictionaries with the following keys:
Key Value ~
clone Determines how sources should be checked out.
Additional arguments: repository url, target
directory.
update Determines how sources that are already checked out
should be updated.
Additional argument: updated directory.
wdrev Determines how current revision should be obtained.
Used to distinguish between cases “update has not
updated anything” and “update successfully pulled and
checked out new revision(s)” and also for logging new
changes.
Additional argument: updated directory.
log Returns log (string) with changes.
Additional arguments: updated directory, old revision
identifier, new revision identifier (values
obtained by wdrev above).
Values of keys `clone' and `executable' should be lists that look like
if you want to call them with call("call", {value}), but with
additional arguments added to the second element of the list. You may
omit second argument, in this case it will considered to be empty.
Example: >
function GitCheckout(url, target)
execute 'silent! !git clone' a:url shellescape(a:target, 1)
endfunction
function GitUpdate(command, directory) dict
execute 'sil! !cd' shellescape(a:directory, 1) '&&' a:command
endfunction
let g:vim_addon_manager.scms={'git': {
\'clone': ['GitCheckout', []],
\'update': [function("GitUpdate"), ['git pull']],\
\'executable': $HOME.'/bin/git'}}
" “'clone': ['GitCheckout']” works as well
< Note: if some keys are missing, then VAM will use the defaults. So it
is safe to override just one “clone” key as it is shown in
|vam#vcs#GitCheckout| example.
pool_fun *VAM-pool_fun*
Name or reference of a function that must return dictionary contains
{{plugin-name}: {repository}} ({repository} is described under
|addon-info-repository|) map.
Default is "vam#install#Pool".
addon_completion_lhs *VAM-addon_completion_lhs*
{lhs} of the mapping that uses |vam#install#CompleteAddonName()| for
completion. Default: "<C-x><C-p>". Spaces and bars are not escaped.
Use zero to disable this completely.
shell_commands_run_method *VAM-shell_commands_run_method*
String, possible values: “bang”, “system”. Determines method used to
run shell commands: “bang” (default) uses “:execute '!'.cmd”,
“system” uses “sysem(cmd)”, output is echoed. Second avoids hit-enter
prompts, but is unable to run commands with newline (see
|system()|).
*VAM-hooks*
post_install_hook_functions *VAM-post_install_hook_functions*
pre_update_hook_functions *VAM-pre_update_hook_functions*
post_update_hook_functions *VAM-post_update_hook_functions*
post_scms_update_hook_functions *VAM-post_scms_update_hook_functions*
Lists of function names or function references that will be called
when hook is executed (see |addon-info-hooks|). All functions get four
arguments: addon info dictionary, repository dictionary, plugin
directory location and hook options dictionary.
Default values:
post_install_hook_functions: absent
pre_update_hook_functions: ["vam#install#CreatePatch"]
post_update_hook_functions: ["vam#install#ApplyPatch"]
post_scms_update_hook_functions: ["vam#install#ShowShortLog"]
Note: update hooks values are required for |VAM-do_diff| to work,
vam#install#CreatePatch must be the last function and
vam#install#ApplyPatch should be the first.
debug_activation *VAM-debug_activation*
Bool, makes VAM print lines explaining reasons for activation
particular plugins. Not pretty - but helpful in some cases.
source_missing_files *VAM-source_missing_files*
Bool, determines whether VAM should check whether all plugin/ files
were sourced at the point of |VimEnter| event and source missed ones.
Default: 1.
This is needed if you load additional plugins in a plugin/*.vim file
which may happen if you use http://github.com/MarcWeber/vim-addon-local-vimrc
for instance
The following options are used by vim-pi, not by VAM itself. So if you set
|vim-addon-manager-known| to another value they may have no effect.
*VAM-drop_SCM_sources*
drop_git_sources *VAM-drop_git_sources*
drop_hg_sources *VAM-drop_hg_sources*
drop_svn_sources *VAM-drop_svn_sources*
drop_bzr_sources *VAM-drop_bzr_sources*
Determines whether given SCM sources should be dropped before merging
scm sources by |scm_merge_strategy|. This way you can force using
www.vim.org sources. But you may get different plugin versions
scm_merge_strategy *VAM-scm_merge_strategy*
String, valid values: `force' (default), `keep' and `never'. Defines,
whether SCM sources should be used instead of www.vim.org sources:
`forces' stands for prefering SCM over www.vim.org, `keep' means that
SCM sources will be used only if the plugin is not available from
www.vim.org, `never' means that SCM sources will be never used.
MergeSources *VAM-MergeSources*
Function reference, defines a function that will be used to merge
user, |vim-pi| and SCM sources.
Overrides |VAM-scm_merge_strategy| and |VAM-drop_SCM_sources|. Will be
called with five arguments: user sources (most of time it is an empty
dictionary), non-SCM sources defined in |vim-pi|, SCM sources also
defined there, patch function name and snr_to_name dictionary. Patch
function is a function that being given sources dictionary (like one
of first three arguments) and snr_to_name dictionary patches first
adding missing information (like missing dependencies). Last
dictionary is a map of www.vim.org script numbers to |vim-pi| names.
If MergeSources function is a dictionary function, it will be provided
an empty dictionary as |self| dictionary.
An Example can be found in this file.
==============================================================================
6. Uninstalling Plugins *VAM-uninstall-plugins*
Follow these steps:
- Remove the plugin name from the call to |vam#ActivateAddons()| in your
vimrc.
- Restart Vim and remove plugin directory using >
:UninstallNotLoadedAddons {pluginname}
< or rm -fr those directories manually.
==============================================================================
7. Addon-info file *VAM-addon-info*
*addon-info.json* *addon-info.txt*
Some documentation will be moved to vim-wiki:
http://vim-wiki.mawercer.de/wiki/topic/addon-info.json.html
Example: >
{
dependencies : {
'dependency-1-name': {},
'dependency-2-name': {}
}
}
Each plugin that intends to use vim-addon-manager for distributing itself
needs to have addon-info.json [1] file in its root,
that contains the JSON dictionary with the following keys (none of the keys
are required):
[1]: older alternative name: {plugname}-addon-info.txt
name *addon-info-name*
Name of the plugin. Must not contain any characters that cannot be
used in a directory name (including directory names separator).
Note that if the value of this key, {plugname} part in addon-info.txt
file name and directory under which plugin is installed are not equal,
then user that tries to use your plugin may catch strange bugs.
repository *addon-info-repository*
Describes where the plugin should be fetched from. Ignored unless the
plugin is installed using either the second or third form of
|vam#install#Install()| call (see its description). This is
a dictionary with the following keys:
Key Description ~
type Required, must be either one of `hg', `git', `svn', `bzr' or
an empty string.
url If `type' key contains a VCS name (`hg', `git', `bzr' or
`svn'), then this key describes a url that will be passed to
this VCS. If `type' key contains an empty string, then it
should contain location of the archive.
script-type
One of `plugin', `syntax', `color scheme', or `indent'. The
.vim file will be moved into the specific subdirectory.
archive_name
If `type' key contains an empty string, then archive which
location is described by the `url' key will be saved in file
with name {archive_name} and processed according to its
extension. Supported extensions (note that if you have 7-zip
installed no other archive tools are required):
Extension How it is handled ~
.vim This extension designates that plugin is
a single file. Depending on `script-type' and
`target_dir' keys this file will be put
under:
1. {root}/{target_dir} if `target_dir' key
exists.
2. {root}/syntax, {root}/indent,
{root}/ftplugin if `script-type' is equal to
"syntax", "indent" or "ftplugin"
respectively.
3. {root}/colors if `script-type' is equal to
"color scheme".
4. {root}/plugin otherwise.
.tar.gz, .tgz This extension designates that plugin is
contained inside tar archive compressed by
gzip. In this case, archive is uncompressed by
`gzip' and unpacked to its directory by `tar'
(both utilities may be replaced with `7z x').
.tar.bz2, .tbz2
Like .tar.gz, but with bzip2 compression.
.tar This extension designates that plugin is
contained inside uncompressed tar archive. In
this case, archive is unpacked to its directory
by `tar'.
.zip This extension designates that plugin is
contained inside a zip archive. In this case
archive is unpacked to its directory by
`unzip' (may be replaced by `7z x').
.7z, .rar, .cab, .arj, .jar
This extension designates that plugin is
contained inside an archive that is supported
by p7zip archiver. In this case archive is
unpacked to its directory by `7z x'.
.vba This extension designates that plugin is
contained in a vimball archive. In this case
vimball#Vimball() function is used, see
|:UseVimball| for more details.
.vba.gz This extension designates that plugin is
contained in a vimball archive compressed by
gzip. In this case archive is uncompressed and
vimball#Vimball() function is used, see
|:UseVimball| for more details.
.vba.bz2 Like .vba.bz2, but with bzip2 compression.
deprecated
If this key is present and contains non-empty string, then
every time when user tries to install this plugin he will see
this message and will have to confirm installation.
strip-components
Strip first {strip-components} directories after unpacking an
archive. If it is equal to special value `-1' (default), then
it will strip either one directory (if archive contains the
only directory that is not special) or will not strip anything
at all. Recognized special directories: [ft]plugin, autoload,
colors, compiler, indent, keymap, lang, print, spell, syntax.
addon-info
Contains addon information in case plugin does not supply its
own addon-info file. Will be written to addo-info.json file.
vim_script_nr
Contains www.vim.org script ID.
homepage
Contains home page URL. Though it is possible to use it, VAM
currently is also able to use repository.url to determine
plugin home page (github and bitbucket sources only). May be
the only source of home page URL in the future.
*addon-info-hooks*
post-install-hook *addon-info-post-install-hook*
post-update-hook *addon-info-post-update-hook*
post-scms-update-hook *addon-info-post-scms-update-hook*
pre-update-hook *addon-info-pre-update-hook*
Contains VimL command (string), that is |:execute|d after some
replacements are done: “%d” gets replaced with |expression| evaluating
to plugin root directory, “%i” – to addon-info dictionary and “%r” –
to repository dictionary, “%o” – to opts dictionary (used to save
information between “pre-” and “post-” hooks).
Hooks are executed in the following cases:
Hook Case ~
post-install After successfully installing a plugin using
|:ActivateAddons| or running |:RunInstallHooks|.
pre-update Before a non-VCS source update.
post-update After a non-VCS source update.
post-scms-update After VCS source update.
In non-scms *-update hooks opts dictionary also contains oldVersion
and newVersion values. In post-scms-update hook repository and opts
dictionaries also contain them, but here they are whatever
|VAM-scms|.{SCM}.wdrev returns or zero. Additionally sdescr key is
available with support functions (one of |VAM-scms| dictionaries).
dependencies *addon-info-dependencies*
Describes plugins that are required for the plugin, must contain
a dictionary where keys are plugin names and values describe where
appropriate plugins should be fetched from (overriden by
|VAM-plugin_sources|). The format of the values is the same as
|addon-info-repository|.
version *addon-info-version*
author *addon-info-author*
maintainer *addon-info-maintainer*
description *addon-info-description*
homepage *addon-info-homepage*
Version, author, maintainer, description and plugin homepage. Ignored,
but setting them to the real values will not do any harm.
==============================================================================
8. Author, credits, some notes *VAM-related*
Related work: ~
PATHOGEN:
Until now I thought it was only about manipulating runtimepath.
But the most recent announcement about mirroring all vim scripts
shows that it may become a competitive VAM alternative?
http://www.vim.org/scripts/script.php?script_id=2332
http://vim-scripts.org/index.html
There are also some other package managers for vim:
https://github.com/c9s/Vimana
https://github.com/gmarik/vundle (git support only, VimL)
You can try and see which is the best.
another list: http://vim-scripts.org/tools.html
Emacs install scripts manager:
el-get https://github.com/dimitri/el-get/blob/master/el-get.el
janus collection also seems to have kind of dependency management.
I tried contacting them - no reply.
See https://groups.google.com/group/janus-vimius/browse_thread/thread/78db65eebd9cc5d8?hl=de
vimpyre: A python package managing vim scripts somehow. Its using pathogen to
manage loading of the scripts: https://github.com/pct/vimpyre
There is another project which has the same name:
http://packages.debian.org/sid/vim-addon-manager
The author (Jamessan) is fine with this project sharing the same name.
------------------------------------------------------------------------------
7.1. Author contacts *VAM-author*
Github account: MarcWeber
Email: marco-oweber@gmx.de
------------------------------------------------------------------------------
7.2. Contributors *VAM-contributors*
(Incomplete list):
Tim Pope (+) (tpope on github)
- Json validation
ZyX (+) (Nikolay Pavlov, ZyX-I on github)
- enhancing this vim documentation
- various fixes
- discussing implementation details
- initial implementation for updating plugins which were installed by
archive
- pushing 7z and providing a reference implementation
- smart strip components implementation
Tux Tom (+) (https://github.com/TuxTom)
- helping fixing a cd bug on Windows
creidiki (Leonardo Valeri Manera)
- greatly improving Windows support
- working around the tar issues on Windows
..
Mike Smullin:
- for asking to find a way to source addons when gui is running.
There is a hint now. This is important if you don't start vim from console
Israel Chauca Fuentes:
- reporting and fixing some bugs
Zach Kelling (zeekay twitter/github):
providing an initial almost working attempt to load plugins lazily based on
filetype
(+) means they are collaborators on github and could take action in case of serious
trouble.
------------------------------------------------------------------------------
ROADMAP:
What features are missing?
- When updating archive based plugins create diffs so that you can patch
those files without changes being lost. I expect users to customize mappings
and such
- add a command like AddonManagerFetchUtils which does all the work listed in
9. for you putting the tar etc into a directory and adding it to PATH
- suggestions?
==============================================================================
9. Testing this plugin *VAM-testing*
Run (assuming you installed it in ~/.vim/vim-addons) >
cd ~/.vim/vim-addons
hg clone http://hg.code.sf.net/p/vimpluginloader/dev-tools
cd dev-tools
./test.zsh -a vim-addon-manager
. If test fails test.zsh prints out a list of failed tests and exits with
non-zero code. Dependencies:
- zsh
- perl
- YAML::Any (+some YAML implementation) and WWW::Mechanize perl packages
Note: YAML implementation must accept YAML files without leading ---. YAML
parser shipped with perl does not accept them, use YAML::LibYAML.
- vim
Tests dependencies (not required for test.zsh, but for the tests themselves):
- git, mercurial, subversion and bazaar version control systems
- wget or curl. Unlike VAM tests cannot use any other downloader.
- 7z or zip and tar+gzip+bzip2
- vimball plugin
==============================================================================
10. Some notes for windows users *VAM-windows*
Finally the nightmare came to an end:
http://mawercer.de/~marc/vam/index.php
Enter plugins names, download final .zip. Be happy and enjoy VAM.
We could create a vim-addon-curl-unzip-for-windowns plugin providing those
executables. Then VAM would be able to install many plugins after
bootstrapping without help of the vam/index.php url. Tell me to work on it.
Also see BUG [4]
OLD docs:
Win32 tools for vim-addon-manager
Fast: put curl into ~/.vim/vim-addons/binary-utils/dist then call this function
to setup the remaining tools (tar, bzip, gzip, unzip)
>
call vam#install#FetchAdditionalWindowsTools()
<
If 7z is in PATH bzip, unzip, gzip are not pulled. So consider installing that
and add it to PATH by
>
let $PATH=$PATH.';'.PATH_TO_7z
<
( TODO: test it, provide a way to install 7z instead? )
After the tools are setup, sometimes installing an addon still fail.
Usually this is triggered by a weird value of |shellslash| or |shellquote|.
Here is that was found to be working:
>
set shellslash=0
set shellquote=\"
<
See https://stackoverflow.com/questions/355988/how-do-i-deal-with-quote-characters-when-using-cmd-exe
for more informations.
Ashwin Nanjappa provided an alternative installation instruction here which
worked for him. You may still want to read this section first. There are
multiple ways to make VIM run on Windows and install all missing dependencies.
http://choorucode.wordpress.com/2010/12/09/using-vim-addon-manager-on-windows/
Does it make sense to support svn and git this way as well?
Is it even possible?
At least we can fetch and execute the installers..
Section provided by creidiki:
Curl:
Get Curl here: http://curl.haxx.se/download.html
1. Scroll down to the end of the "Packages" list. You want (ideally) the
latest version, of type `binary' (not libcurl or devel). SSL is not
necessary but won't hurt. If your OS is 64-bit, you can get the Win64
version if you want, but it won't be any faster.
2. Install it. Then point vim-addon-manager (and, incidentally, netrw) to
it by putting something like this in your _vimrc: >
let g:netrw_http_cmd='{path_to_curl}\curl.exe -o'
< (replace {path-to-curl} with the installation directory, including the
brackets).
Don't forget the -o argument at the end. :)
Archives:
Get 7-zip here: http://7-zip.org/download.html. You need the full version
with gui because package with command-line version contains only 7za
executable, while you need 7z in order to support more archives. You can
skip all subsequent projects, one 7z is enough for all supported archive
file formats.
Get Tar, Gzip and Unzip from the GnuWin32 project
Gzip: http://gnuwin32.sourceforge.net/packages/gzip.htm
Tar: http://gnuwin32.sourceforge.net/packages/gtar.htm
Unzip: http://gnuwin32.sourceforge.net/packages/unzip.htm
Either get the complete package setups, or the binary installers. All you
need is the binaries.
Install or unpack them somewhere.
Get xzdec here: http://nullprogram.com/blog/2010/04/16/
or here: http://www.stats.ox.ac.uk/pub/Rtools/goodies/xzutils.zip
You only need xzdec.exe. Put in the same place you put those other archive
tools.
Either add them to your system or user path (google it!) or add them just
to vim's path by putting something like this in _vimrc: >
let $PATH='{path-to-gnu-utils};'.$PATH
< Again, replace the whole of {path-to-gnu-utils} including brackets with
the directory you have installed/unpacked them to. You need the same for
7-zip too.
VCS:
MSysGit (and TortoiseGit/GitExtensions) by default add the `git'
executable to your PATH. If you chose not to for whatever reason, you can
use the trick above to let vim see them. TortoiseHG does the same with the
mercurial `hg' executable. TortoiseSVN does not include the commandline
`svn' executable, so if you need it install SilkSVN
SilkSVN: http://www.sliksvn.com/en/download/
MsysGit: http://code.google.com/p/msysgit/
Mercurial: http://mercurial.selenic.com/
Darcs: http://darcs.net/
See also |vam#vcs#GitCheckout|.
We tried thinking about making using vim-addon-manager easier for Windows
users. One idea was introducing a proxy which asks a linux server to package
git/svn/mercurial/bazaar/darcs as zip file on the fly. This would mean you
don’t have to install svn,hg,.. to use plugins only.
If you want something like this to happen contact me.
==============================================================================
11. Some notes for Gentoo users *VAM-gentoo*
ZyX packaged vim-addon-manager for gentoo. Eventually you still prefer using
SetupVAM because it works on any unix like system - and its files are that
small so its debatable whether its worth sharing.
The overlay is accessible via mercurial, url:
http://hg.code.sf.net/p/vimpluginloader/pluginloader-overlay or
https://bitbucket.org/ZyX_I/pluginloader-overlay (mirror).
In order to use this overlay paludis users can add the pluginloader.conf file
to /etc/paludis/repositories/ with the following contents: >
location = /var/paludis/repositories/pluginloader
format = e
sync = hg+http://hg.code.sf.net/p/vimpluginloader/pluginloader-overlay
master_repository = gentoo
names_cache = ${location}/.cache/names
write_cache = /var/cache/paludis/metadata
Then you should unmask app-vim/vim-addon-manager and run >
paludis --sync && paludis --install vim-addon-manager
or >
cave sync && cave resolve -x vim-addon-manager
and everything will probably be fine.
For portage+layman users:
1. Create a file /var/lib/layman/pluginloader-overlay.xml with the following
contents: >
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="unofficial">
<name>pluginloader-overlay</name>
<description>Overlay that contains some additional vim plugins</description>
<source type="mercurial">http://hg.code.sf.net/p/vimpluginloader/pluginloader-overlay</source>
</repo>
</repositories>
2. Add the following line to /etc/layman/layman.cfg just after the line that
starts with `overlays' (do not forget to indent it, see comment above the
target line): >
file:///var/lib/layman/pluginloader-overlay.xml
3. Run >
layman -ka pluginloader-overlay
4. Unmask vim-addon-manager and run >
emerge vim-addon-manager
==============================================================================
*marc-weber-VAM-design-notes*
Until now I tried following the "New Jersey", KISS, MIT principles:
- Try to achieve 80% of value by spending 20% of effort
- I consider this piece of code being perfect if there is nothing you can
remove.
- If it behaves ok in 95% of all use cases its good enough (for me)
because I prefer a minimal code base.
ZyX created a branch which tries to be accurate summarrized by quoting him:
"I am trying to get rid of as much future errors as possible".
See related work to get it instead of this. Lets watch it and be curious about
what's going to happen.
==============================================================================
12. Troubleshooting and known bugs *VAM-trouble-shooting*
Using a $SHELL setting other than /bin/sh may not work on *nix like systems
[BUG 101] Directories with commas are not supported.
Any discussion is here: https://github.com/MarcWeber/vim-addon-manager/issues/101
[BUG 10] Think about how to integrate ideas found in ipi
http://www.vim.org/scripts/script.php?script_id=3809
Runtimepath manipulation should be separated from installation / update
logic. This way you can have different implementation for updating plugins
eg one being written in python which you can run from commandline.
However to keep it portable this means we had to support
- a VimL solution (eg for Windows users ?)
- a python/ruby/perl/whatsoever commandline version
(See thread "which plugin management system to use?" on vim_use)
ANY OTHER ERROR:
Try commenting all your code in .vimrc and other plugins - does it work
then? Settings which are known to cause trouble:
:echo &shell
:echo &shellslash (some windows users seem to set this differently?)
older vim's eg 7.0...
jolan78 has fixed one issue with older vims. There are likely to be more:
https://github.com/MarcWeber/vim-addon-manager/issues/51#issuecomment-2112747
[*]: Comment about calling ActivateAddons() using autocommands:
Obviously GUIEnter is only an option if you use gvim only.
Some plugins may fail to assign their changes to existing buffers
this way. That's one of the reasons why calling ActivateAddons()
using an autocommand is marked as experimental.
Probably those are I "won't fix" bugs. Eventually consider patching
those plugins instead.
Workaround: Try adding this to to ActivateAddons() function which should
catch almost all issues by reassigning the filetype to each buffer: >
bufdo exec 'set ft='.&ft
< (or use the tlib#buffer#BufDo() function from tlib which will try to
preserve the current buffer ... or ... - This may have undesired
side effects: Try "vim small-file 2gb-file.txt" and vim will startup fast
because the 2gb file will be loaded only if you switch to the buffer.
Eg try :bn and you'll wait several minutes. Using bufdo will force loading
the (all) buffers on command line immediately ..).
You get the idea why I'm not going to maintain this. Putting it into your
.vimrc should be easy enough.
[3]: VAM does not work nicely with older versions of Vim (won't fix)
For vim-7.0 you can make it work easily by adding loading all .vim files
always:
1) replace shellescape( [...] ,1) by shellescape([...])
2) add to SetupVAM (because function(..) does not behave correctly load
all files always): >
" slow performance. This could be optimized some more - I do no longer
" care about such old Vim versions. Think about upgrading.
for f in split(glob(vam_install_path.'/vim-addon-manager*/**/*.vim', 1),"\n")
if f =~ '/db/' | continue | endif
exec 'source '.fnameescape(f)
endfor
<
[4]: VAM depends on git. Why does it?
|vim-pi| is checked out by git which contains the default merge function.
As advanced user you can define your own sources and define your own merge
function trivially - that somehow defeats the idea of having one working
maitained pool of sources though.
It can be fixed: Eg github allows downloading zip files. However then you
still have to
(1) download sources (curl, wget, python support + urllib, ...)
which is not the default for windows.
(2) implement a way to determine when updates should take place eg when a
repo is outdated. Again probably there are ways to query github even
though I know about web scraping only .. But isn't installing git or
using the web interface for Windows users much nicer?
Tell the VAM team if you want git-less installations to be easier and
supported, please. Right now we're lazy.
For windows users there is: http://mawercer.de/~marc/vam/index.php
which will also work on sytems not having git but an unzip implementation.
------------------------------------------------------------------------------
12.1. Common error messages *VAM-common-errors*
1. unknown function: vam#ActivateAddons
This means that Vim's |runtimepath| setting does not contain the path you
have VAM in. Using the recommended setup this should not happen.
Have a second glance at the minimal setup at |VAM-install|.
See also |autoload|.
==============================================================================
13. TODO notes *VAM-TODO*
- support vim-scripts.org. This will let you get all www.vim.org scripts using
git repositories only. I think the general idea is great. However we have to
take care to keep patches which were written for git/hg in sync.
If you want this feature tell me. I'll add the sources to |vim-pi| then.
[5]
- full update must be done by
:UpdateAddons -known<tab>
restart
:UpdateAddons
Running :UpdateAddons once should be enough
The fix is to force users to use MergeFunction when patching
and moving the sources into autoload functions you can reload.
Then you can rerun the MergeFunc to get up to date pool in Vim memory.
Sometimes it happens that some small bugs appear. Most of the time they are
easy to identify and trivial fix. Usually fixes happen very fast (within less
than 2 days)
If you don't want to wait try running >
git checkout HEAD^
< in the vim-addon-manager directory up to 10 times to checkout older
revisions and retry.
tianyicui : Actually I think the name [vim-addon-manager] is too long