Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 360 lines (293 sloc) 16.294 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)
47 - propagates collaborative coding by providing simple dependeoncy managament
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|.
a1e2590 @MarcWeber add some more documentation about what the gentoo way is so that peop…
authored
96 Gentoo users : skim |VAM-gentoo|
97 which explains how to install VAM system wide using layman overlays.
98 IMHO Fastest is continuing reading below though.
99
ca3b3c9 @MarcWeber improve docs:
authored
100 rest (linux like everything supporting /bin/sh like shells) users keep reading
101 here
102
103 minimal setup ~
104 This is the minimal setup which makes VAM work.
105 However you want to use the longer commented version below because it also
106 fetches VAM.
107 Then copy pasting .vimrc is enough to replicate your setup.
108
109 Add to your .vimrc >
110 set runtimepath+=PATH-TO-VAM
111 call vam#ActivateAddons([.. list of plugin names ..], {'auto_install' : 0})
112
113 recommended setup ~
114 1) Copy paste the following to your .vimrc.
115 2) Read the comments carefully. They help you getting started. Then you can remove them.
116 3) Add addon names to the ActivateAddons call, start Vim, you sohuld be done. >
117
56a2cd3 @MarcWeber forgott to add argument to EnsureVamIsOnDisk function
authored
118 fun! EnsureVamIsOnDisk(vam_install_path)
ca3b3c9 @MarcWeber improve docs:
authored
119 " windows users want to use http://mawercer.de/~marc/vam/index.php
120 " to fetch VAM, VAM-known-repositories and the listed plugins
121 " without having to install curl, unzip, git tool chain first
122 " -> BUG [4] (git-less installation)
123 if !filereadable(a:vam_install_path.'/vim-addon-manager/.git/config')
124 \&& 1 == confirm("Clone VAM into ".a:vam_install_path."?","&Y\n&N")
125 " I'm sorry having to add this reminder. Eventually it'll pay off.
126 call confirm("Remind yourself that most plugins ship with ".
127 \"documentation (README*, doc/*.txt). It is your ".
128 \"first source of knowledge. If you can't find ".
129 \"the info you're looking for in reasonable ".
130 \"time ask maintainers to improve documentation")
131 call mkdir(a:vam_install_path, 'p')
132 execute '!git clone --depth=1 git://github.com/MarcWeber/vim-addon-manager '.shellescape(a:vam_install_path, 1).'/vim-addon-manager'
133 " VAM runs helptags automatically when you install or update
134 " plugins
135 exec 'helptags '.fnameescape(a:vam_install_path.'/vim-addon-manager/doc')
136 endif
137 endf
138
139 fun! SetupVAM()
140 " Set advanced options like this:
141 " let g:vim_addon_manager = {}
142 " let g:vim_addon_manager['key'] = value
143
144 " Example: drop git sources unless git is in PATH. Same plugins can
145 " be installed from www.vim.org. Lookup MergeSources to get more control
146 " let g:vim_addon_manager['drop_git_sources'] = !executable('git')
147
148 " VAM install location:
149 let vam_install_path = expand('$HOME') . '/.vim/vim-addons'
150 call EnsureVamIsOnDisk(vam_install_path)
151 exec 'set runtimepath+='.vam_install_path.'/vim-addon-manager'
152
153 " Tell VAM which plugins to fetch & load:
154 call vam#ActivateAddons([], {'auto_install' : 0})
155 " sample: call vam#ActivateAddons(['pluginA','pluginB', ...], {'auto_install' : 0})
156
157 " Addons are put into vam_install_path/plugin-name directory
158 " unless those directories exist. Then they are activated.
159 " Activating means adding addon dirs to rtp and do some additional
160 " magic
161
162 " How to find addon names?
163 " - look up source from pool
164 " - (<c-x><c-p> complete plugin names):
165 " You can use name rewritings to point to sources:
166 " ..ActivateAddons(["github:foo", .. => github://foo/vim-addon-foo
167 " ..ActivateAddons(["github:user/repo", .. => github://user/repo
168 " Also see section "2.2. names of addons and addon sources" in VAM's documentation
169 endfun
170 call SetupVAM()
171 " experimental [E1]: load plugins lazily depending on filetype, See
172 " NOTES
173 " experimental [E2]: run after gui has been started (gvim) [3]
174 " option1: au VimEnter * call SetupVAM()
175 " option2: au GUIEnter * call SetupVAM()
176 " See BUGS sections below [*]
177 " Vim 7.0 users see BUGS section [3]
178
179
180
181 NOTES: ~
182 experimental: load plugins lazily depending on filetype [E1]~
183 >
184 let ft_addons = {
185 \ '^\%(c\|cpp\)$': [ 'plugin-for-c-development' ],
186 \ 'javascript': [ 'plugin-for-javascript' ]
187 \ }
188 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
189 < Provide feedback about this. If it works we may add it as builtin
190
191 experimental: setup VAM when GUI has started [E2] ~
192 Depending on the option you choose to run ActivateAddons Vim may not be
193 able to show the questions correctly asking you to install a plugin.
194 If that's the case (for whatever reason) I recommend installing the plugin
195 using |:InstallAddons| or |:ActivateAddons| before adding it to the list in
196 .vimrc
197
198 If you're annoyed by the message: >
199 "Press enter to continue"
200 < There are at least two solutions you can try:
201
202 - press q once and Vim should stop asking
203 - set auto_install = 1 (to make Vim stop asking you any questions. However you
204 won't know if knew dependencies are fetched in that case etc)
205
206
207 Example how to patch vcs checkout functions (eg if you're behind a proxy and
208 need to checkout github urls by http://): >
209 let g:vim_addon_manager = {'scms': {'git': {}}}
210 fun! MyGitCheckout(repository, targetDir)
211 let a:repository.url = substitute(a:repository.url, '^git://github', 'http://github', '')
212 return vam#utils#RunShell('git clone --depth=1 $.url $p', a:repository, a:targetDir)
213 endfun
214 let g:vim_addon_manager.scms.git.clone=['MyGitCheckout']
215 <
216
217 Another example: replace git_update and show changelog >
218 let g:vim_addon_manager = {'scms': {'git': {}}}
219 fun! MyGitUpdate(targetDir)
220 let cd = shellescape
221 let oldHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
222 call vam#utils#RunShell('cd $p && git pull', a:targetDir)
223 let newHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
224 if oldHash isnot# newHash
225 silent enew
226 setlocal buftype=nofile bufhidden=wipe
227 call setline(1, a:targetDir)
228 call append(1, split(system(vam#utils#ShellDSL('cd $; git log $[]..$[]', a:targetDir, oldHash, newHash)), "\n"))
229 endif
230 return 0
231 endfun
232 let g:vim_addon_manager.scms.git.update=['MyGitUpdate']
233 <
234
235 HOWTO benchmark startup? >
236 vim --startuptime logfile -c q
237 < Then read the logfile. As alternative you can benchmark activating scripts
238 *at rurntime* by >
239 tlib#cmd#Time('call vam#ActivateAddons(["A"])')
240 < which requires tlib. Why at runtime? Because plugin/*.vim files are sourced
241 by VIM after .vimrc has been processed
242
243 ------------------------------------------------------------------------------
244 2.2 Names of addons and addon sources *VAM-addon-names*
245
246 Because we are human VAM uses readable names as unique identifier for plugins.
247 Those identifieres (= plugin names) are passed to |vam#ActivateAddons()|, |:InstallAddons|,
248 |:ActivateAddons| . The name is automatically derived from plugin titles at
249 www.vim.org.
250
251 types of names:
252 1) Plugin name looked up in pool. Try |:AddonInfo| NAME
253
254 Determining addon names ~
255 - From ID: |:AddonsInfo| SCRIPT_ID, pick the word right after string "Plugin: ".
256 - use |:InstallAddons|' name completion by typing some chars then pressing
257 <c-d> then <tab>.
258 - Use <c-x><c-p> completion while editing your vimrc.
259
260 2) Name which gets rewritten internally (see |vam#install#RewriteName()|) >
261 github:{Name} => {"type": "git", "url": "git://github.com/{Name}/vim-addon-{Name}}
262 github:{N}/{Repo} => {"type": "git", "url": "git://github.com/{N}/{Repo}"}
263 git:{GIT_URL} => {"type": "git", "url": "GIT_URL"}
264 < Don't use if you expect others to create plugins depending on yours. Add
265 your plugin to |VAM-kr| instead.
266
267
268 Instead of telling us to add your plugin to |VAM-kr| you can also patch the
269 pool easily: |VAM-kr-patching| - however if you contribute to |VAM-kr| the
270 community will benefit much more.
271
272 *VAM-kr* is the default pool. VAM checks it out by default. Its long name is
273 *vim-addon-manager-known-repositories* (stored in |VAM-known| option).
274
275 *VAM-kr-patching*
276 VAM-kr merges both sources (scm and www.vim.org ones), see |VAM-MergeSources|.
277 The result is provided by vam_known_repositories#Pool() which is the only pool
278 used by default. See example and default implementation vam#install#Pool().
279
280 If you want to add your own soucres consider submitting them to
281 VAM-kr as patch. If you don't there are two ways:
282
283 WAY 1: (still supported) add to your .vimrc before activating VAM (BUG/TODO [5]): >
284 let g:vim_addon_manager = {}
285 let g:vim_addon_manager.plugin_sources = {}
286 let g:vim_addon_manager.plugin_sources['your_plugin_name'] = { plugin dictionary }
287 <
288 WAY 2: define your own Pool function: >
289 let g:vim_addon_manager = {}
290 let g:vim_addon_manager.pool_fun = function('MyPoolFun')
291 fun MyPoolFun()
292 let d = vam#install#Pool()
293 let d['my_plugin'] = { 'type' : 'git', 'url' : ' ... ' }
294 return d
295 endf
296
297 Plugin dictionaries are described in |addon-info-repository|.
298
299 Example: overwriting the MergeSources function (VAM-kr pool implementation): >
300 Yes, you can do this in MyPoolFun shown above as well >
301
302 fun! vam_known_repositories#MergeSources(plugin_sources, www_vim_org, scm_plugin_sources, patch_function, snr_to_name)
303
304 " run default:
305 call vam_known_repositories#MergeSources(a:plugin_sources, a:www_vim_org, a:scm_plugin_sources, a:patch_function, a:snr_to_name)
306
307 " patch sources the way you like. This example adds username and password
308 " for SVN repositories. As alternative you could overwrite git urls etc ..
309 for your_plugin in ['svn-driven-key1', ...]
310 let a:plugin_sources[your_plugin]['username'] = 'svn user'
311 let a:plugin_sources[your_plugin]['password'] = 'svn user'
312 endfor
313
314 let a:plugin_sources['your_plugin_name'] = { plugin dictionary }
315 endf
316 " tell VAM to use your MergeSources function:
317 let g:vim_addon_manager = {}
318 let g:vim_addon_manager['MergeSources'] = function('MyMergeSources')
319 <
320
321
322 ------------------------------------------------------------------------------
323 2.3 Example: configurable setup *VAM-complex-setup-sample*
324 >
325 call vam#ActivateAddons(["github:YOURNAME"],{'auto_install' : 0})
326 " this initializes Vim the way *you* want also loading more plugins:
327 call vim_addon_YOURNAME#Activate(['c-dev','ruby-dev'])
328 <
329 My implementation looks like this:
330 https://github.com/MarcWeber/vim-addon-MarcWeber/blob/master/autoload/vim_addon_MarcWeber.vim
331
332 You can then load plugins depending on env vars:
333 Example: >
334 call vim_addon_YOURNAME#Activate(['always']+split($V,','))
335 < Then you can run vim like this from shell >
336 V=c-dev,ruby-dev vim
337 <
338 This section was written to inspire you only.
339
340 ------------------------------------------------------------------------------
341 2.4 Unattended installation *VAM-unattended-installation*
342
343 Note: You should always review foreign code before running it. That said this
344 is how you can update or install unattended (without confirmations ..):
345
346 redir! > /tmp/log-vim.txt
347 silent! ACTION
348 messages
349
350 where ACTION is either UpdateActivatedAddons or vam#InstallAddons()
351
352 This works for http://mawercer.de/~marc/vam/index.php.
353
354 There is also the undocumented g:vim_addon_manager.dont_source option which
355 should be used if you want to checkout eventually untrusted code! If you're
356 going to use the plugins anyway its of no use.
357 You may also want to set auto_install.
358
6d27796 @ZyX-I Section tags work fine no matter where these tags are located.
ZyX-I authored
359 vim: tw=78:ts=8:ft=help:norl
Something went wrong with that request. Please try again.