Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 386 lines (320 sloc) 17.882 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
49 - supports many sources (git,hg,bzr,svn,www.vim.org)
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,
73 Subversion and Bazaar repositories
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)
83 - Git, Mercurial, Subversion and Bazaar (if you want to install plugins
84 from appropriate repositories)
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 peop…
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')
152
153 " VAM install location:
154 let vam_install_path = expand('$HOME') . '/.vim/vim-addons'
919a9da @MarcWeber fix issue 75, by v0n
authored
155 if !EnsureVamIsOnDisk(vam_install_path) | echoe "NO VAM FOUND!" | return | endif
ca3b3c9 @MarcWeber improve docs:
authored
156 exec 'set runtimepath+='.vam_install_path.'/vim-addon-manager'
157
158 " Tell VAM which plugins to fetch & load:
159 call vam#ActivateAddons([], {'auto_install' : 0})
160 " sample: call vam#ActivateAddons(['pluginA','pluginB', ...], {'auto_install' : 0})
161
162 " Addons are put into vam_install_path/plugin-name directory
163 " unless those directories exist. Then they are activated.
164 " Activating means adding addon dirs to rtp and do some additional
165 " magic
166
167 " How to find addon names?
168 " - look up source from pool
169 " - (<c-x><c-p> complete plugin names):
170 " You can use name rewritings to point to sources:
171 " ..ActivateAddons(["github:foo", .. => github://foo/vim-addon-foo
172 " ..ActivateAddons(["github:user/repo", .. => github://user/repo
173 " Also see section "2.2. names of addons and addon sources" in VAM's documentation
174 endfun
175 call SetupVAM()
176 " experimental [E1]: load plugins lazily depending on filetype, See
177 " NOTES
178 " experimental [E2]: run after gui has been started (gvim) [3]
179 " option1: au VimEnter * call SetupVAM()
180 " option2: au GUIEnter * call SetupVAM()
181 " See BUGS sections below [*]
182 " Vim 7.0 users see BUGS section [3]
183
184
185
186 NOTES: ~
187 experimental: load plugins lazily depending on filetype [E1]~
188 >
189 let ft_addons = {
190 \ '^\%(c\|cpp\)$': [ 'plugin-for-c-development' ],
191 \ 'javascript': [ 'plugin-for-javascript' ]
192 \ }
193 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
194 < Provide feedback about this. If it works we may add it as builtin
195
196 experimental: setup VAM when GUI has started [E2] ~
197 Depending on the option you choose to run ActivateAddons Vim may not be
198 able to show the questions correctly asking you to install a plugin.
199 If that's the case (for whatever reason) I recommend installing the plugin
200 using |:InstallAddons| or |:ActivateAddons| before adding it to the list in
201 .vimrc
202
203 If you're annoyed by the message: >
204 "Press enter to continue"
205 < There are at least two solutions you can try:
206
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
207 - press q once and Vim should stop asking
208 - set |VAM-auto_install| to 1 (to make VAM stop asking you questions before
209 installing anything)
210 , set |VAM-shell_commands_run_method| to "system" (to make VAM use
211 |system()| for running installation commands and thus avoid |hit-enter|
212 prompts)
213 and set 'nomore' before ActivateAddons call (to avoid |more-prompt|).
214
215
216 Example how to patch vcs checkout functions (eg if you're behind a proxy
217 and need to checkout github urls by http://): >
218 let g:vim_addon_manager = {'scms': {'git': {}}}
219 fun! MyGitCheckout(repository, targetDir)
220 let a:repository.url = substitute(a:repository.url, '^git://github', 'http://github', '')
221 return vam#utils#RunShell('git clone --depth=1 $.url $p', a:repository, a:targetDir)
222 endfun
223 let g:vim_addon_manager.scms.git.clone=['MyGitCheckout']
ca3b3c9 @MarcWeber improve docs:
authored
224 <
225
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
226 Another example: replace git_update and show changelog >
227 let g:vim_addon_manager = {'scms': {'git': {}}}
228 fun! MyGitUpdate(targetDir)
229 let cd = shellescape
230 let oldHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
231 call vam#utils#RunShell('cd $p && git pull', a:targetDir)
232 let newHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
233 if oldHash isnot# newHash
234 silent enew
235 setlocal buftype=nofile bufhidden=wipe
236 call setline(1, a:targetDir)
237 call append(1, split(system(vam#utils#ShellDSL('cd $; git log $[]..$[]', a:targetDir, oldHash, newHash)), "\n"))
238 endif
239 return 0
240 endfun
241 let g:vim_addon_manager.scms.git.update=['MyGitUpdate']
ca3b3c9 @MarcWeber improve docs:
authored
242 <
243
96f3202 @ZyX-I Modified “Installation” section:
ZyX-I authored
244 Startup benchmarking ~
245 Some non-precise benchmarking can be done by >
246 vim --startuptime startup.log -c q
247 < . Timings will be printed to startup.log file. You can do it more precisely
248 by using >
249 vim --cmd 'profile start profile.log' \
250 --cmd 'profile func *' \
251 --cmd 'profile file *' \
252 -c 'profile pause' \
253 -c 'qa!'
254 < Then it will output full profile information where time consumed by each
255 line is shown, with a summary of function call times at the end. You can
256 also get a summary of script file times if you open profile.log and do >
257 let timings=[]
258 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\+$'')'))
259 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])'))
260 < . You can also get times of scripts activation if you run >
261 tlib#cmd#Time('call vam#ActivateAddons(["A"])')
262 < for plugins which were not already activated after vim has started.
263 Requires tlib. Adds time which takes VAM to do activation to actual
264 activation. For filetype, indent, syntax, compiler, colorscheme and
265 autoload plugins time spend in VAM is likely to exceed time used to load
266 plugin (because actual loading will take place later if required), so it is
267 better to read |profiling| instead.
ca3b3c9 @MarcWeber improve docs:
authored
268
269 ------------------------------------------------------------------------------
270 2.2 Names of addons and addon sources *VAM-addon-names*
271
272 Because we are human VAM uses readable names as unique identifier for plugins.
273 Those identifieres (= plugin names) are passed to |vam#ActivateAddons()|, |:InstallAddons|,
274 |:ActivateAddons| . The name is automatically derived from plugin titles at
275 www.vim.org.
276
277 types of names:
278 1) Plugin name looked up in pool. Try |:AddonInfo| NAME
279
280 Determining addon names ~
281 - From ID: |:AddonsInfo| SCRIPT_ID, pick the word right after string "Plugin: ".
282 - use |:InstallAddons|' name completion by typing some chars then pressing
283 <c-d> then <tab>.
284 - Use <c-x><c-p> completion while editing your vimrc.
285
286 2) Name which gets rewritten internally (see |vam#install#RewriteName()|) >
287 github:{Name} => {"type": "git", "url": "git://github.com/{Name}/vim-addon-{Name}}
288 github:{N}/{Repo} => {"type": "git", "url": "git://github.com/{N}/{Repo}"}
289 git:{GIT_URL} => {"type": "git", "url": "GIT_URL"}
290 < Don't use if you expect others to create plugins depending on yours. Add
291 your plugin to |VAM-kr| instead.
292
293
294 Instead of telling us to add your plugin to |VAM-kr| you can also patch the
295 pool easily: |VAM-kr-patching| - however if you contribute to |VAM-kr| the
296 community will benefit much more.
297
298 *VAM-kr* is the default pool. VAM checks it out by default. Its long name is
299 *vim-addon-manager-known-repositories* (stored in |VAM-known| option).
300
301 *VAM-kr-patching*
302 VAM-kr merges both sources (scm and www.vim.org ones), see |VAM-MergeSources|.
303 The result is provided by vam_known_repositories#Pool() which is the only pool
304 used by default. See example and default implementation vam#install#Pool().
305
306 If you want to add your own soucres consider submitting them to
307 VAM-kr as patch. If you don't there are two ways:
308
309 WAY 1: (still supported) add to your .vimrc before activating VAM (BUG/TODO [5]): >
310 let g:vim_addon_manager = {}
311 let g:vim_addon_manager.plugin_sources = {}
312 let g:vim_addon_manager.plugin_sources['your_plugin_name'] = { plugin dictionary }
313 <
314 WAY 2: define your own Pool function: >
315 let g:vim_addon_manager = {}
316 let g:vim_addon_manager.pool_fun = function('MyPoolFun')
317 fun MyPoolFun()
318 let d = vam#install#Pool()
319 let d['my_plugin'] = { 'type' : 'git', 'url' : ' ... ' }
320 return d
321 endf
322
323 Plugin dictionaries are described in |addon-info-repository|.
324
325 Example: overwriting the MergeSources function (VAM-kr pool implementation): >
326 Yes, you can do this in MyPoolFun shown above as well >
327
328 fun! vam_known_repositories#MergeSources(plugin_sources, www_vim_org, scm_plugin_sources, patch_function, snr_to_name)
329
330 " run default:
331 call vam_known_repositories#MergeSources(a:plugin_sources, a:www_vim_org, a:scm_plugin_sources, a:patch_function, a:snr_to_name)
332
333 " patch sources the way you like. This example adds username and password
334 " for SVN repositories. As alternative you could overwrite git urls etc ..
335 for your_plugin in ['svn-driven-key1', ...]
336 let a:plugin_sources[your_plugin]['username'] = 'svn user'
337 let a:plugin_sources[your_plugin]['password'] = 'svn user'
338 endfor
339
340 let a:plugin_sources['your_plugin_name'] = { plugin dictionary }
341 endf
342 " tell VAM to use your MergeSources function:
343 let g:vim_addon_manager = {}
344 let g:vim_addon_manager['MergeSources'] = function('MyMergeSources')
345 <
346
347
348 ------------------------------------------------------------------------------
349 2.3 Example: configurable setup *VAM-complex-setup-sample*
350 >
351 call vam#ActivateAddons(["github:YOURNAME"],{'auto_install' : 0})
352 " this initializes Vim the way *you* want also loading more plugins:
353 call vim_addon_YOURNAME#Activate(['c-dev','ruby-dev'])
354 <
355 My implementation looks like this:
356 https://github.com/MarcWeber/vim-addon-MarcWeber/blob/master/autoload/vim_addon_MarcWeber.vim
357
358 You can then load plugins depending on env vars:
359 Example: >
360 call vim_addon_YOURNAME#Activate(['always']+split($V,','))
361 < Then you can run vim like this from shell >
362 V=c-dev,ruby-dev vim
363 <
364 This section was written to inspire you only.
365
366 ------------------------------------------------------------------------------
367 2.4 Unattended installation *VAM-unattended-installation*
368
369 Note: You should always review foreign code before running it. That said this
370 is how you can update or install unattended (without confirmations ..):
371
372 redir! > /tmp/log-vim.txt
373 silent! ACTION
374 messages
375
376 where ACTION is either UpdateActivatedAddons or vam#InstallAddons()
377
378 This works for http://mawercer.de/~marc/vam/index.php.
379
380 There is also the undocumented g:vim_addon_manager.dont_source option which
381 should be used if you want to checkout eventually untrusted code! If you're
382 going to use the plugins anyway its of no use.
383 You may also want to set auto_install.
384
6d27796 @ZyX-I Section tags work fine no matter where these tags are located.
ZyX-I authored
385 vim: tw=78:ts=8:ft=help:norl
Something went wrong with that request. Please try again.