Skip to content
This repository
Newer
Older
100644 399 lines (333 sloc) 18.224 kb
379f6427 »
2012-04-07 Fixed first tag in new file
1 *vim-addon-manager-getting-started.txt* Declarative package manager for Vim
ca3b3c99 »
2012-04-04 improve docs:
2 ==============================================================================
b6140150 »
2012-04-19 remove duplicate tags
3 CONTENTS *VAM-contents-getting-started*
ca3b3c99 »
2012-04-04 improve docs:
4
5 0. GETTING STARTED & LOOKING FOR HELP <<
6
7 1. Intro |VAM-intro|
6d277965 »
2012-04-07 Section tags work fine no matter where these tags are located.
8 2. Installation & installing plugins |VAM-installation|
ca3b3c99 »
2012-04-04 improve docs:
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|
6d277965 »
2012-04-07 Section tags work fine no matter where these tags are located.
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|
ca3b3c99 »
2012-04-04 improve docs:
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)
ec138396 »
2012-05-20 Fixed minor typo
47 - propagates collaborative coding by providing simple dependency managament
ca3b3c99 »
2012-04-04 improve docs:
48 improving code sharing
d5aaf717 »
2012-07-11 Added notes about darcs to documentation
49 - supports many sources (git, hg, bzr, svn, darcs, www.vim.org)
ca3b3c99 »
2012-04-04 improve docs:
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,
d5aaf717 »
2012-07-11 Added notes about darcs to documentation
73 Subversion, Bazaar and Darcs repositories
ca3b3c99 »
2012-04-04 improve docs:
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)
d5aaf717 »
2012-07-11 Added notes about darcs to documentation
83 - Git, Mercurial, Subversion, Bazaar and Darcs (if you want to install
84 plugins from appropriate repositories)
ca3b3c99 »
2012-04-04 improve docs:
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|.
96f3202c »
2012-05-05 Modified “Installation” section:
96 Gentoo users : skim |VAM-gentoo| which explains how to install VAM system-wide
97 from the layman overlay.
a1e2590a »
2012-04-19 add some more documentation about what the gentoo way is so that peop…
98
96f3202c »
2012-05-05 Modified “Installation” section:
99 Rest (linux and everything able to run POSIX shell) users should keep reading
100 here.
ca3b3c99 »
2012-04-04 improve docs:
101
96f3202c »
2012-05-05 Modified “Installation” section:
102 Minimal setup ~
ca3b3c99 »
2012-04-04 improve docs:
103 This is the minimal setup which makes VAM work.
96f3202c »
2012-05-05 Modified “Installation” section:
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.
ca3b3c99 »
2012-04-04 improve docs:
107
108 Add to your .vimrc >
96f3202c »
2012-05-05 Modified “Installation” section:
109 set runtimepath+=PATH-TO-VAM
110 call vam#ActivateAddons([.. list of plugin names ..], {'auto_install' : 0})
ca3b3c99 »
2012-04-04 improve docs:
111
112 recommended setup ~
96f3202c »
2012-05-05 Modified “Installation” section:
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 >
56a2cd34 »
2012-04-05 forgott to add argument to EnsureVamIsOnDisk function
118 fun! EnsureVamIsOnDisk(vam_install_path)
96f3202c »
2012-05-05 Modified “Installation” section:
119 " windows users may want to use http://mawercer.de/~marc/vam/index.php
ca3b3c99 »
2012-04-04 improve docs:
120 " to fetch VAM, VAM-known-repositories and the listed plugins
96f3202c »
2012-05-05 Modified “Installation” section:
121 " without having to install curl, 7-zip and git tools first
ca3b3c99 »
2012-04-04 improve docs:
122 " -> BUG [4] (git-less installation)
919a9dad »
2012-06-18 fix issue 75, by v0n
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)
ca3b3c99 »
2012-04-04 improve docs:
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')
236c85dc »
2012-06-27 adding debug_activation option
152 " let g:vim_addon_manager.debug_activation = 1
ca3b3c99 »
2012-04-04 improve docs:
153
154 " VAM install location:
155 let vam_install_path = expand('$HOME') . '/.vim/vim-addons'
04ac1cd7 »
2012-06-18 Don’t use :echoe ever.
156 if !EnsureVamIsOnDisk(vam_install_path)
5fee544b »
2012-06-18 Guess it was really meant not to break execution, thus no :throw
157 echohl ErrorMsg
158 echomsg "No VAM found!"
159 echohl NONE
160 return
04ac1cd7 »
2012-06-18 Don’t use :echoe ever.
161 endif
ca3b3c99 »
2012-04-04 improve docs:
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
96f3202c »
2012-05-05 Modified “Installation” section:
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']
ca3b3c99 »
2012-04-04 improve docs:
230 <
231
96f3202c »
2012-05-05 Modified “Installation” section:
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']
ca3b3c99 »
2012-04-04 improve docs:
248 <
249
96f3202c »
2012-05-05 Modified “Installation” section:
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.
ca3b3c99 »
2012-04-04 improve docs:
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:
379bee0a »
2012-07-13 Fixed command name.
284 1) Plugin name looked up in pool. Try |:AddonsInfo| NAME
ca3b3c99 »
2012-04-04 improve docs:
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.
389 You may also want to set auto_install.
390
a1bc46a9 »
2012-07-11 document results from issue 77
391 Also see https://github.com/MarcWeber/vim-addon-manager/issues/77:
392 >
393 let g:vim_addon_manager = {
394 \'shell_commands_run_method': 'system',
395 \'auto_install': 1,
396 \}
397 <
6d277965 »
2012-04-07 Section tags work fine no matter where these tags are located.
398 vim: tw=78:ts=8:ft=help:norl
Something went wrong with that request. Please try again.