Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 426 lines (355 sloc) 18.994 kb
379f642 @ZyX-I Fixed first tag in new file
ZyX-I authored
1 *vim-addon-manager-getting-started.txt* Declarative package manager for Vim
ca3b3c9 @MarcWeber improve docs:
authored
2 ==============================================================================
b614015 @MarcWeber remove duplicate tags
authored
3 CONTENTS *VAM-contents-getting-started*
ca3b3c9 @MarcWeber improve docs:
authored
4
5 0. GETTING STARTED & LOOKING FOR HELP <<
6
7 1. Intro |VAM-intro|
6d27796 @ZyX-I Section tags work fine no matter where these tags are located.
ZyX-I authored
8 2. Installation & installing plugins |VAM-installation|
ca3b3c9 @MarcWeber improve docs:
authored
9 2.2 Names of addons and addon soucres |VAM-addon-names|
10 2.3 Example: configurable setup |VAM-complex-setup-sample|
11 2.4 unattended installation |VAM-unattended-installation|
6d27796 @ZyX-I Section tags work fine no matter where these tags are located.
ZyX-I authored
12 In |vim-addon-manager-additional-documentation.txt|:
13 3. Functionality provided |VAM-functionality|
14 3.1. Commands |VAM-commands|
15 3.2. Functions |VAM-functions|
16 4. Options |VAM-options|
17 6. Uninstalling plugins |VAM-uninstall-plugins|
18 7. Addon-info file |VAM-addon-info|
19 8. Author, credits, some notes |VAM-related|
20 9. Testing this plugin |VAM-testing|
21 10. Some notes for windows users |VAM-windows|
22 11. Some notes for Gentoo users |VAM-gentoo|
23 12. Troubleshooting and known bugs |VAM-trouble-shooting|
24 13. TODO notes |VAM-TODO|
25 14. VAM vs ... |VAM-comparison|
26 15. Tracking down errors |VAM-tracking-down-erros|
27 16. Making plugins work with VAM |VAM-adjusting-plugins|
ca3b3c9 @MarcWeber improve docs:
authored
28
29 ==============================================================================
30
31 0. GETTING STARTED & LOOKING FOR HELP - something doesn't work
32
33 Getting started fast: ~
34 Read: |VAM-installation| and |VAM-addon-names|
35
36
37 NEED HELP: ~
38 Join irc.freenode.net, /join #vim. Ask there. VAM has many users
39 MarcWeber is hanging around often so ping him or create a github ticket [1] and
40 people will try to help you. You should skim the docs before asking for
41 help though. Also see |VAM-author|
42 [1] https://github.com/MarcWeber/vim-addon-manager/issues
43
44 WHY VAM?: ~
45 - two maintainers (ZyX and Marc Weber)
46 - friendly to users (install addons by name)
ec13839 @Inkane Fixed minor typo
Inkane authored
47 - propagates collaborative coding by providing simple dependency managament
ca3b3c9 @MarcWeber improve docs:
authored
48 improving code sharing
d5aaf71 @ZyX-I Added notes about darcs to documentation
ZyX-I authored
49 - supports many sources (git, hg, bzr, svn, darcs, www.vim.org)
ca3b3c9 @MarcWeber improve docs:
authored
50 - provides a way to deprecate plugins which are superseded by others
51 - most plugins can also be loaded at runtime (some problems may [BUG 10])
52 - some Windows support
53 - is not too shy telling you that alternatives exist (and which one)
54 - copes with "subdirectories contain vim runtimepath" cases
55
56 ==============================================================================
57 1. Intro *VAM-intro*
58
59 VAM is a shortcut for vim-addon-manager. Its vision is: Make it easiest to
60 install plugin somewhat following the 20% of efforts yields 80% of value rule.
61
62 Difference names addon plugin: Almost none.
63 >
64 :h plugin
65 tells you about the old manual manual way of installing plugins. VAM helps
66 keeping ~/.vim clean by separating plugins from each other.
67
68 Features:
69
70 - Separate directories for each plugins
71 - Dependency resolution
72 - Popular VCS support: plugin supports fetching from Git, Mercurial,
d5aaf71 @ZyX-I Added notes about darcs to documentation
ZyX-I authored
73 Subversion, Bazaar and Darcs repositories
ca3b3c9 @MarcWeber improve docs:
authored
74 - maintained pool of addons (vim-addon-manager-known-repositories)
75 which warns you if you try to install an outdated plugin
76 - replicate your Vim setup by copying your .vimrc (See SetupVAM)
77 - load plugins lazily when Vim is already running. Some plugins require
78 additional tweaks for this to work
79
80 Dependencies:
81 - Curl, wget or other program that can output URL contents to stdout (in
82 order to get http protocol support)
d5aaf71 @ZyX-I Added notes about darcs to documentation
ZyX-I authored
83 - Git, Mercurial, Subversion, Bazaar and Darcs (if you want to install
84 plugins from appropriate repositories)
ca3b3c9 @MarcWeber improve docs:
authored
85 - Either tar, gzip and zip or 7-zip (required for unpacking some addons)
86
87 What does "Declarative package manager" mean? The final behaviour of Vim
88 should be declared once. Your ~/.vimrc and |:UpdateAddons| should be enough
89 to cause same Vim behaviour everywhere.
90
91
92 ==============================================================================
93 2. Installation *VAM-installation*
94
95 Windows users: skim |VAM-windows|.
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
96 Gentoo users : skim |VAM-gentoo| which explains how to install VAM system-wide
97 from the layman overlay.
a1e2590 @MarcWeber add some more documentation about what the gentoo way is so that people ...
authored
98
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
99 Rest (linux and everything able to run POSIX shell) users should keep reading
100 here.
ca3b3c9 @MarcWeber improve docs:
authored
101
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
102 Minimal setup ~
ca3b3c9 @MarcWeber improve docs:
authored
103 This is the minimal setup which makes VAM work.
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
104 However you may want to use the longer commented version below because it
105 also fetches VAM so that copying your .vimrc is enough to replicate your
106 setup.
ca3b3c9 @MarcWeber improve docs:
authored
107
108 Add to your .vimrc >
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
109 set runtimepath+=PATH-TO-VAM
110 call vam#ActivateAddons([.. list of plugin names ..], {'auto_install' : 0})
ca3b3c9 @MarcWeber improve docs:
authored
111
112 recommended setup ~
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
113 1) Paste the following to your .vimrc.
114 2) Read the comments carefully. They help you getting started. Then you can
115 remove them.
116 3) Add addon names to the ActivateAddons call, start Vim. That’s all.
117 >
56a2cd3 @MarcWeber forgott to add argument to EnsureVamIsOnDisk function
authored
118 fun! EnsureVamIsOnDisk(vam_install_path)
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
119 " windows users may want to use http://mawercer.de/~marc/vam/index.php
ca3b3c9 @MarcWeber improve docs:
authored
120 " to fetch VAM, VAM-known-repositories and the listed plugins
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
121 " without having to install curl, 7-zip and git tools first
ca3b3c9 @MarcWeber improve docs:
authored
122 " -> BUG [4] (git-less installation)
919a9da @MarcWeber fix issue 75, by v0n
authored
123 let is_installed_c = "isdirectory(a:vam_install_path.'/vim-addon-manager/autoload')"
124 if eval(is_installed_c)
125 return 1
126 else
127 if 1 == confirm("Clone VAM into ".a:vam_install_path."?","&Y\n&N")
128 " I'm sorry having to add this reminder. Eventually it'll pay off.
129 call confirm("Remind yourself that most plugins ship with ".
130 \"documentation (README*, doc/*.txt). It is your ".
131 \"first source of knowledge. If you can't find ".
132 \"the info you're looking for in reasonable ".
133 \"time ask maintainers to improve documentation")
134 call mkdir(a:vam_install_path, 'p')
135 execute '!git clone --depth=1 git://github.com/MarcWeber/vim-addon-manager '.shellescape(a:vam_install_path, 1).'/vim-addon-manager'
136 " VAM runs helptags automatically when you install or update
137 " plugins
138 exec 'helptags '.fnameescape(a:vam_install_path.'/vim-addon-manager/doc')
139 endif
140 return eval(is_installed_c)
ca3b3c9 @MarcWeber improve docs:
authored
141 endif
142 endf
143
144 fun! SetupVAM()
145 " Set advanced options like this:
146 " let g:vim_addon_manager = {}
147 " let g:vim_addon_manager['key'] = value
148
149 " Example: drop git sources unless git is in PATH. Same plugins can
150 " be installed from www.vim.org. Lookup MergeSources to get more control
151 " let g:vim_addon_manager['drop_git_sources'] = !executable('git')
236c85d @MarcWeber adding debug_activation option
authored
152 " let g:vim_addon_manager.debug_activation = 1
ca3b3c9 @MarcWeber improve docs:
authored
153
154 " VAM install location:
155 let vam_install_path = expand('$HOME') . '/.vim/vim-addons'
04ac1cd @ZyX-I Don’t use :echoe ever.
ZyX-I authored
156 if !EnsureVamIsOnDisk(vam_install_path)
5fee544 @ZyX-I Guess it was really meant not to break execution, thus no :throw
ZyX-I authored
157 echohl ErrorMsg
158 echomsg "No VAM found!"
159 echohl NONE
160 return
04ac1cd @ZyX-I Don’t use :echoe ever.
ZyX-I authored
161 endif
ca3b3c9 @MarcWeber improve docs:
authored
162 exec 'set runtimepath+='.vam_install_path.'/vim-addon-manager'
163
164 " Tell VAM which plugins to fetch & load:
165 call vam#ActivateAddons([], {'auto_install' : 0})
166 " sample: call vam#ActivateAddons(['pluginA','pluginB', ...], {'auto_install' : 0})
167
168 " Addons are put into vam_install_path/plugin-name directory
169 " unless those directories exist. Then they are activated.
170 " Activating means adding addon dirs to rtp and do some additional
171 " magic
172
173 " How to find addon names?
174 " - look up source from pool
175 " - (<c-x><c-p> complete plugin names):
176 " You can use name rewritings to point to sources:
177 " ..ActivateAddons(["github:foo", .. => github://foo/vim-addon-foo
178 " ..ActivateAddons(["github:user/repo", .. => github://user/repo
179 " Also see section "2.2. names of addons and addon sources" in VAM's documentation
180 endfun
181 call SetupVAM()
182 " experimental [E1]: load plugins lazily depending on filetype, See
183 " NOTES
184 " experimental [E2]: run after gui has been started (gvim) [3]
185 " option1: au VimEnter * call SetupVAM()
186 " option2: au GUIEnter * call SetupVAM()
187 " See BUGS sections below [*]
188 " Vim 7.0 users see BUGS section [3]
189
190
191
192 NOTES: ~
193 experimental: load plugins lazily depending on filetype [E1]~
194 >
195 let ft_addons = {
196 \ '^\%(c\|cpp\)$': [ 'plugin-for-c-development' ],
197 \ 'javascript': [ 'plugin-for-javascript' ]
198 \ }
199 au FileType * for l in values(filter(copy(ft_addons), string(expand('<amatch>')).' =~ v:key')) | call vam#ActivateAddons(l, {'force_loading_plugins_now':1}) | endfor
200 < Provide feedback about this. If it works we may add it as builtin
201
202 experimental: setup VAM when GUI has started [E2] ~
203 Depending on the option you choose to run ActivateAddons Vim may not be
204 able to show the questions correctly asking you to install a plugin.
205 If that's the case (for whatever reason) I recommend installing the plugin
206 using |:InstallAddons| or |:ActivateAddons| before adding it to the list in
207 .vimrc
208
209 If you're annoyed by the message: >
210 "Press enter to continue"
211 < There are at least two solutions you can try:
212
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
213 - press q once and Vim should stop asking
214 - set |VAM-auto_install| to 1 (to make VAM stop asking you questions before
215 installing anything)
216 , set |VAM-shell_commands_run_method| to "system" (to make VAM use
217 |system()| for running installation commands and thus avoid |hit-enter|
218 prompts)
219 and set 'nomore' before ActivateAddons call (to avoid |more-prompt|).
220
221
222 Example how to patch vcs checkout functions (eg if you're behind a proxy
223 and need to checkout github urls by http://): >
224 let g:vim_addon_manager = {'scms': {'git': {}}}
225 fun! MyGitCheckout(repository, targetDir)
226 let a:repository.url = substitute(a:repository.url, '^git://github', 'http://github', '')
227 return vam#utils#RunShell('git clone --depth=1 $.url $p', a:repository, a:targetDir)
228 endfun
229 let g:vim_addon_manager.scms.git.clone=['MyGitCheckout']
ca3b3c9 @MarcWeber improve docs:
authored
230 <
231
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
232 Another example: replace git_update and show changelog >
233 let g:vim_addon_manager = {'scms': {'git': {}}}
234 fun! MyGitUpdate(targetDir)
235 let cd = shellescape
236 let oldHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
237 call vam#utils#RunShell('cd $p && git pull', a:targetDir)
238 let newHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
239 if oldHash isnot# newHash
240 silent enew
241 setlocal buftype=nofile bufhidden=wipe
242 call setline(1, a:targetDir)
243 call append(1, split(system(vam#utils#ShellDSL('cd $; git log $[]..$[]', a:targetDir, oldHash, newHash)), "\n"))
244 endif
245 return 0
246 endfun
247 let g:vim_addon_manager.scms.git.update=['MyGitUpdate']
ca3b3c9 @MarcWeber improve docs:
authored
248 <
249
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
250 Startup benchmarking ~
251 Some non-precise benchmarking can be done by >
252 vim --startuptime startup.log -c q
253 < . Timings will be printed to startup.log file. You can do it more precisely
254 by using >
255 vim --cmd 'profile start profile.log' \
256 --cmd 'profile func *' \
257 --cmd 'profile file *' \
258 -c 'profile pause' \
259 -c 'qa!'
260 < Then it will output full profile information where time consumed by each
261 line is shown, with a summary of function call times at the end. You can
262 also get a summary of script file times if you open profile.log and do >
263 let timings=[]
264 g/^SCRIPT/call add(timings, [getline('.')[len('SCRIPT '):], matchstr(getline(line('.')+1), '^Sourced \zs\d\+')]+map(getline(line('.')+2, line('.')+3), 'matchstr(v:val, ''\d\+\.\d\+$'')'))
265 call setline('.', ['count total (s) self (s) script']+map(copy(timings), 'printf("%5u %9s %8s %s", v:val[1], v:val[2], v:val[3], v:val[0])'))
266 < . You can also get times of scripts activation if you run >
267 tlib#cmd#Time('call vam#ActivateAddons(["A"])')
268 < for plugins which were not already activated after vim has started.
269 Requires tlib. Adds time which takes VAM to do activation to actual
270 activation. For filetype, indent, syntax, compiler, colorscheme and
271 autoload plugins time spend in VAM is likely to exceed time used to load
272 plugin (because actual loading will take place later if required), so it is
273 better to read |profiling| instead.
ca3b3c9 @MarcWeber improve docs:
authored
274
275 ------------------------------------------------------------------------------
276 2.2 Names of addons and addon sources *VAM-addon-names*
277
278 Because we are human VAM uses readable names as unique identifier for plugins.
279 Those identifieres (= plugin names) are passed to |vam#ActivateAddons()|, |:InstallAddons|,
280 |:ActivateAddons| . The name is automatically derived from plugin titles at
281 www.vim.org.
282
283 types of names:
379bee0 @ZyX-I Fixed command name.
ZyX-I authored
284 1) Plugin name looked up in pool. Try |:AddonsInfo| NAME
ca3b3c9 @MarcWeber improve docs:
authored
285
286 Determining addon names ~
287 - From ID: |:AddonsInfo| SCRIPT_ID, pick the word right after string "Plugin: ".
288 - use |:InstallAddons|' name completion by typing some chars then pressing
289 <c-d> then <tab>.
290 - Use <c-x><c-p> completion while editing your vimrc.
291
292 2) Name which gets rewritten internally (see |vam#install#RewriteName()|) >
293 github:{Name} => {"type": "git", "url": "git://github.com/{Name}/vim-addon-{Name}}
294 github:{N}/{Repo} => {"type": "git", "url": "git://github.com/{N}/{Repo}"}
295 git:{GIT_URL} => {"type": "git", "url": "GIT_URL"}
296 < Don't use if you expect others to create plugins depending on yours. Add
297 your plugin to |VAM-kr| instead.
298
299
300 Instead of telling us to add your plugin to |VAM-kr| you can also patch the
301 pool easily: |VAM-kr-patching| - however if you contribute to |VAM-kr| the
302 community will benefit much more.
303
304 *VAM-kr* is the default pool. VAM checks it out by default. Its long name is
305 *vim-addon-manager-known-repositories* (stored in |VAM-known| option).
306
307 *VAM-kr-patching*
308 VAM-kr merges both sources (scm and www.vim.org ones), see |VAM-MergeSources|.
309 The result is provided by vam_known_repositories#Pool() which is the only pool
310 used by default. See example and default implementation vam#install#Pool().
311
312 If you want to add your own soucres consider submitting them to
313 VAM-kr as patch. If you don't there are two ways:
314
315 WAY 1: (still supported) add to your .vimrc before activating VAM (BUG/TODO [5]): >
316 let g:vim_addon_manager = {}
317 let g:vim_addon_manager.plugin_sources = {}
318 let g:vim_addon_manager.plugin_sources['your_plugin_name'] = { plugin dictionary }
319 <
320 WAY 2: define your own Pool function: >
321 let g:vim_addon_manager = {}
322 let g:vim_addon_manager.pool_fun = function('MyPoolFun')
323 fun MyPoolFun()
324 let d = vam#install#Pool()
325 let d['my_plugin'] = { 'type' : 'git', 'url' : ' ... ' }
326 return d
327 endf
328
329 Plugin dictionaries are described in |addon-info-repository|.
330
331 Example: overwriting the MergeSources function (VAM-kr pool implementation): >
332 Yes, you can do this in MyPoolFun shown above as well >
333
334 fun! vam_known_repositories#MergeSources(plugin_sources, www_vim_org, scm_plugin_sources, patch_function, snr_to_name)
335
336 " run default:
337 call vam_known_repositories#MergeSources(a:plugin_sources, a:www_vim_org, a:scm_plugin_sources, a:patch_function, a:snr_to_name)
338
339 " patch sources the way you like. This example adds username and password
340 " for SVN repositories. As alternative you could overwrite git urls etc ..
341 for your_plugin in ['svn-driven-key1', ...]
342 let a:plugin_sources[your_plugin]['username'] = 'svn user'
343 let a:plugin_sources[your_plugin]['password'] = 'svn user'
344 endfor
345
346 let a:plugin_sources['your_plugin_name'] = { plugin dictionary }
347 endf
348 " tell VAM to use your MergeSources function:
349 let g:vim_addon_manager = {}
350 let g:vim_addon_manager['MergeSources'] = function('MyMergeSources')
351 <
352
353
354 ------------------------------------------------------------------------------
355 2.3 Example: configurable setup *VAM-complex-setup-sample*
356 >
357 call vam#ActivateAddons(["github:YOURNAME"],{'auto_install' : 0})
358 " this initializes Vim the way *you* want also loading more plugins:
359 call vim_addon_YOURNAME#Activate(['c-dev','ruby-dev'])
360 <
361 My implementation looks like this:
362 https://github.com/MarcWeber/vim-addon-MarcWeber/blob/master/autoload/vim_addon_MarcWeber.vim
363
364 You can then load plugins depending on env vars:
365 Example: >
366 call vim_addon_YOURNAME#Activate(['always']+split($V,','))
367 < Then you can run vim like this from shell >
368 V=c-dev,ruby-dev vim
369 <
370 This section was written to inspire you only.
371
372 ------------------------------------------------------------------------------
373 2.4 Unattended installation *VAM-unattended-installation*
374
375 Note: You should always review foreign code before running it. That said this
376 is how you can update or install unattended (without confirmations ..):
377
378 redir! > /tmp/log-vim.txt
379 silent! ACTION
380 messages
381
382 where ACTION is either UpdateActivatedAddons or vam#InstallAddons()
383
384 This works for http://mawercer.de/~marc/vam/index.php.
385
386 There is also the undocumented g:vim_addon_manager.dont_source option which
387 should be used if you want to checkout eventually untrusted code! If you're
388 going to use the plugins anyway its of no use.
26cfa98 @rocksolidwebdesign Added documentation
rocksolidwebdesign authored
389
ca3b3c9 @MarcWeber improve docs:
authored
390 You may also want to set auto_install.
391
a1bc46a @MarcWeber document results from issue 77
authored
392 Also see https://github.com/MarcWeber/vim-addon-manager/issues/77:
393 >
394 let g:vim_addon_manager = {
395 \'shell_commands_run_method': 'system',
396 \'auto_install': 1,
397 \}
398 <
2cf9007 @MarcWeber improving the patch by introducing a buffer to which vim will write the ...
authored
399
26cfa98 @rocksolidwebdesign Added documentation
rocksolidwebdesign authored
400 and possibly log_to_buf which will prevent you from having to deal with most
401 of those "hit enter to continue" prompts while VAM downloads plugins
402
403 Also see https://github.com/MarcWeber/vim-addon-manager/issues/79:
404 >
405 let g:vim_addon_manager = {
406 \'shell_commands_run_method': 'system',
407 \'auto_install': 1,
408 \'log_to_buf': 1,
409 \}
410 <
411
412 and if you wish, you may customize the location of the VAM log file, just
413 use the vam_log_buffer_name option which defaults to a value of VAM_LOG.txt
414 in the VAM plugin's root directory e.g.
415 ~/.vim/vim-addons/vim-addon-manager/VAM_LOG.txt
416 >
417 let g:vim_addon_manager = {
418 \'shell_commands_run_method': 'system',
419 \'auto_install': 1,
420 \'log_to_buf': 1,
421 \'vam_log_buffer_name': '/tmp/vam_install.log',
422 \}
423 <
2cf9007 @MarcWeber improving the patch by introducing a buffer to which vim will write the ...
authored
424
6d27796 @ZyX-I Section tags work fine no matter where these tags are located.
ZyX-I authored
425 vim: tw=78:ts=8:ft=help:norl
Something went wrong with that request. Please try again.