Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
1188 lines (997 sloc) 58.4 KB
*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 soucres |VAM-addon-names|
2.3 Example: configurable setup |VAM-complex-setup-sample|
2.4 unattended installation |VAM-unattended-installation|
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|
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|
==============================================================================
3. Functionality provided *VAM-functionality*
------------------------------------------------------------------------------
3.1. Commands *VAM-commands*
InstallAddons {name} ... *:InstallAddons*
Install addons with given names. See |vam#install#InstallAddons()| 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.
UninstallNotLoadedAddons {name} ... *:UninstallNotLoadedAddons*
Unistall addons with given names. See
|vam#install#UninstallAddons()| for more details.
AddonsInfo {id/name} ... *:AddonsInfo*
Shows addon information. Accepts both VAM script names and www.vim.org
script numbers.
------------------------------------------------------------------------------
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": "git://github.com/{Name}/vim-addon-{Name}}
github:{N}/{Repo} {"type": "git",
"url": "git://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 autoload/vam.vim 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|.
*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-addon-manager-known-repositories.
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".
Note: If not all plugins are contained in the same direcotry
completion for |:UninstallAddons| breaks because simple globbing
is used.
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 escaped.
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.
The following options are used by vim-addon-manager-known-repositories, 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, |VAM-kr| 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 |VAM-kr|, 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 vim.org script numbers to VAM-kr 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*
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.
Also accepts `after/syntax' which is a hack that makes VAM
move source into after/syntax directory.
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. So, if exists key `script-type'
and it is equal to `syntax' or `indent', then
this file is put under {plugname}/syntax or
under {plugname}/indent, otherwise it is put
under directory described by
{plugname}/{target_dir} (where {target_dir} is
a value of `target_dir' key if it is present
and `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 >
# Replace ~/.vim/vim-addons/vim-addon-manager with the path you installed this
# plugin to
cd ~/.vim/vim-addons/vim-addon-manager
sh vim-addon-manager-test.sh
.
You should see >
1
1
1
at the end. Written for Linux only. Code coverage is bad. Its a starting
point.
==============================================================================
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://vimpluginloader.hg.sourceforge.net:8000/hgroot/vimpluginloader/pluginloader-overlay
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://vimpluginloader.hg.sourceforge.net:8000/hgroot/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://vimpluginloader.hg.sourceforge.net:8000/hgroot/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*
[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)
ERROR: Vim(call):E117: Unknown function: vam#Activate
SOLUTION: set runtimepath (rtp) correctly. It must match the directory you
installed VAM into.
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'),"\n")
if f =~ 'plugin/vim-addon-manager-known-repositories.vim' | continue | endif
exec 'source '.fnameescape(f)
endfor
<
[4]: VAM depends on git. Why does it?
VAM-kr 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.
==============================================================================
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 |VAM-kr| 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
(github) and totally uncool.
Marc Weber: Your suggestion VAM as abbreviation is fine. Let's use that.
Switching the name means a lot of work and many dead links.
I'm not going to switch the name for 'uncoolness' reasons soon.
Don't have those commands? See |VAM-installation|.
Windows installation is more tedious than on Linux - yes.
Still trouble? Get in touch, see |VAM-author|
The help file should be using VAM. (Yes - but its too much work to get it
right for now)
You have to trust script authors:
Because everybody can upload everything to the repositories (in particular
www.vim.org) you must trust authors. I can't review all code - so expect code
to steal your passwords, run sudo rm -fr / ... etc. (This never happened to
me. But it could)
Briefly: I'm not responsible for the code you get using vim-addon-manager.
You can use |InstallAddons| to preview source.
If something goes wrong - and if I don't reply within 24h:
The following github users are collaborators. This means they have write
access to the official repository:
tpope, dertuxmalwieder, TuxTom.
If a plugin behaves strangely then try
http://github.com/dahu/VimLint/blob/master/plugin/vimlint.vim.
Maybe you have an uncommon Vim setting causing some plugins to fail.
There is currently no way forcing loading a plugin at .vimrc time.
Vim delays executing plugin/*.vim files until .vimrc finished processing.
This leads to some hacks such as defining g:in_load_known_repositories.
Forcing loading a plugin earlier (including dependencies !) would allow us to
get rid of this hack.
Its a bug that VAM supports ',' in path items of runtimepath.
Most other plugins do not. IMHO the true fix would be fixing Vim:
call add(g:runtimepath, "newpath") and all the trouble would be gone.
But vim does not use g:runtimpath, it uses an option with strange quoting.
Same applies to errorformat.
So don't use ',' in paths and everyone is happy.
I only act uppon feedback. So if you want changes you have to contact me.
Don't expect me to know what you dream about.
"I want feature X" such as browsable lists of plugins. ActivateAddons FOO
make launching the plugin permanent, ...
Me too - pay me.
Seriously: I don't want to add all features to VAM. It is designed as minimal
as possible. This excludes any gui features. If you want to add such browser
or the like create a new plugin "vim-addon-manager-gui" people can install and
use. I'm happy to put a link into this manual or assist you. However
I personally don't have time to write it.
VAM only checks out 2 revisions using git.
Its not a bug. You can get remaining versions by git fetch --depth=9999999
or such. This speeds up installation very much and should be still be
sufficient to prepare patches.
==============================================================================
14. VAM vs ... *VAM-comparison*
------------------------------------------------------------------------------
14.1. VAM vs pathogen *VAM-vs-pathogen*
URL: https://github.com/tpope/vim-pathogen
+ |:helptags| is run automatically only after updating or installing the
plugin.
+ There is a maintained pool of plugins that makes possible to
1. create hooks which may be required to finish installation (like
Command-T requiring some compilation)
2. patch (mainly tell VAM that plugin has different runtimepath) or
deprecate plugins (for example, Sanders snipmate)
+ VAM handles plugin dependencies (of course, if author or pool maintainer
added required information).
+ VAM is able to download and install or update plugins.
+ VAM is able to load plugins while vim is running.
------------------------------------------------------------------------------
14.2. VAM vs tplugin *VAM-vs-tplugin*
URL: https://github.com/tomtom/tplugin_vim
+ VAM is able to download and install or update plugins. TPlugin updates only
VCS controlled ones and is not able to install anything.
+ VAM is able to select only some of installed plugins (well, it is unable to
select all of them at once)
+ Non-standart layouts are handled by TPlugin only with help of the user.
? TPlugin is able to construct a menu with available plugins, with VAM you
have to use completion for ActivateInstalledAddons.
- Automatically loads plugins only when their commands, functions or mappings
are called (can’t handle all possible ways of defining a command, function
or mapping though).
- Requires running TPluginScan after each update.
- Has “autocommands” for executing something before/after loading specific
file.
------------------------------------------------------------------------------
14.3. VAM vs vundle *VAM-vs-vundle*
URL: https://github.com/gmarik/vundle
+ Vundles seems to source after/* files for you, but it does not care about
ordering when adding to rtp, thus “~/.vim/after/ftplugin/*” is sourced
before “~/.vim/bundle/PLUGIN/ftplugin”. It is though unlikely that you run
into this issue.
+ Does not handle dependencies (though it is in TODO).
- Vundle has a command to clean unused plugins.
- Vundle has “interactive mode” which speeds up certain workflows.
------------------------------------------------------------------------------
14.4. VAM vs GetLatestVimScripts *VAM-vs-GLVS*
+ VAM uses human-readable names instead of script IDs.
+ GLVS is able to handle only www.vim.org sources.
+ GLVS puts all files into “~/.vim”, VAM (and others mentioned above) uses
one-directory-for-one-plugin approach.
+ GLVS does not seem to track which files belong to which plugin so is not
able to uninstall plugins.
- Unlike VAM GLVS is included in standart vim distribution.
- GLVS was released (posted to www.vim.org) in Nov 2004, while VAM only in
Dec 2009, so it is likely that more plugins define dependencies using GLVS
(needs more exploration though). On the other hand, VAM has large maintained
database also with dependency information.
- Uses downloaded archives’ IDs to determine whether update is needed, this
may have a difference if author does not bother with changing versions, have
chosen the same version because previous upload was packaged wrongly (e.g.
has missing files), etc.
------------------------------------------------------------------------------
14.5. VAM vs Vimana *VAM-vs-Vimana*
URL: https://github.com/c9s/Vimana
+ Requires perl.
+ (For plain vim files posted to vim.org) requires special comment.
+ Has less number of supported distribution formats.
+ Requires manually adding runtimepaths of newly installed plugins or puts
everything into ~/.vim (well, in first entry of 'runtimepath')
+ No dependency handling.
- Has easy support for changing runtimepath for particular plugin
(see also “+” above).
- Is able to do online searches on www.vim.org.
- Has support for Makefiles and Rakefiles.
------------------------------------------------------------------------------
14.6. Some other similar projects *VAM-vs-other*
There are other projects known which are not so popular as the above:
1. janus (https://github.com/carlhuda/janus)
+ Has plugin managment system built on top of pathogen
? Janus is a vim distribution, not only package manager
2. vimpyre (https://github.com/pct/vimpyre)
+ Requires python and some python packages
+ Uses pathogen to actually load plugins, it does only installation itself
+ Supports only git
? Not a vim plugin, but a python extension. Is installed using pip.
- Is able to do some local searches
- Vimpyre can open plugin home page in browser
3. Vim script management system
(http://snk.tuxfamily.org/log/vim-script-management-system.html)
+ Requires ruby and mechanize gem
+ Not supported: 23 March 2011 author has chosen to use
http://github.com/vim-scripts mirror of www.vim.org
+ Supports only www.vim.org
+ Always installs plain .vim files to plugin/ directory
+ Has less number of supported distribution formats
+ No dependency handling
+ Uses script IDs
? Not a vim plugin, but a shell command-line utility
- Uses downloaded archives’ IDs to determine whether update is needed
Most people are using VAM or Pathogen now AFAIK - so if you feel need for this
list submit patches
I personally don't have anything against the other solutions. I like to point
out the importance of the "dependency" feature. It allows reusing code easily.
Thus code will be reused easily. Thus code review will take place yielding
more collaboration thus better code. That was the main reason why I started
VAM. And that's good for community.
==============================================================================
15. Tracking down errors *VAM-tracking-down-errors*
1) Where does the error or unexpected behaviour come from?
Try disabling plugins until you know which plugins are left causing the bad
behaviour. Then you can try checking out older versions.
Pathogen is using "git submodules" which would allow setting back many
repositories in time at once. Because VAM does not use git submodules you
have to checkout older versions for each plugin manually.
GIT (git): ~
- optional: fetch all history (VAM by default uses shallow clones):
git fetch --depth=99999
- list changes:
gitk (gui) or git log -500
- list all changes in time:
git reflog show HEAD@{now} lists lines like this:
b8aee58 HEAD@{Wed Feb 15 03:22:53 2012 +0100}: commit: documentation improvements
^^^^^ the hash
- checkout older revision (thus put plugin back in time to older revision):
git checkout hash
git checkout master # latest revision (unless you use different branches)
tip: hash~2 checks out two versions before hash.
Thus master~10 checks 10 revisions before the most current one.
If you know which hash is causing the bad behaviour you may want to have
look at changes using.
git show hash
Of course #git on irc.freenode.net is willing to help if you have trouble
MERCURIAL (hg): ~
TODO improve this.
hg log -l 500 # list last 500 changes of repositories
hg update -C hash_or_number
SVN (svn)~
svn log -l 500
svn up -rREVISION_NUMBER
Eventually you want to sent a bug report to maintainers
==============================================================================
16. Making plugins work with VAM *VAM-adjusting-plugins*
Most plugins should work out of the box.
Some older plugins expect to be installed into ~/.vim. Probably they can be
patched easily by replacing ~/.vim by a path relative to the file running the
code: >
" this is ~/.vim/vim-addons/foo/autoload/x.vim
" does not work inside a function!
let s:plugin_base_dir = expand('<sfile>:p:h:h')
" now s:plugin_base_dir contains ~/.vim/vim-addons/foo
<
Then plugins can find additional resources (templates, python files, ..)
relative to s:parent_dir_of_this_file
Filetype detection files (from ftdetect/ directory) are loaded if you set
"filetype on". Thus if you do it after last call to vam#ActivateAddons,
everything should be fine.
==============================================================================
The linux script is gone. Search for "unix based os" to learn about its
replacment.
See :h 'modeline' to learn about the following line setting up defaults.
Usually you'd prefer ftplugin files (do it once).
vim: tw=78:ts=8:ft=help:norl
Jump to Line
Something went wrong with that request. Please try again.