*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 sources |VAM-addon-names| 2.3. Example: configurable setup |VAM-complex-setup-sample| 2.4. unattended installation |VAM-unattended-installation| 2.5. Searching the plugins |VAM-plugins-search| 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| 12.1. Common error messages |VAM-common-errors| 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| 16.1. The perfect plugin |VAM-plugin-guide| 17. VAM tricks and hacks |VAM-tricks| ============================================================================== 3. Functionality provided *VAM-functionality* ------------------------------------------------------------------------------ 3.1. Commands *VAM-commands* InstallAddons {name} ... *:InstallAddons* Install addons with given names. See |vam#install#Install()| 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. ListActivatedAddons *:ListActivatedAddons* List all currently activated addons. UninstallNotLoadedAddons {name} ... *:UninstallNotLoadedAddons* Unistall addons with given names. See |vam#install#UninstallAddons()| for more details. AddonsInfo {id/name/any-regex} ... *:AddonsInfo* Shows addon information. Accepts both VAM script names and www.vim.org script numbers. If neither succeeds the any-regex is used and compared against any field of the repository dictionaries. Thus you can use it to find addons by github url etc. Its best to use the directory part of the url only. because github urls can be written using git@ or https:// and with or without trailing ".git" in some cases. *:OKVAMBisect* *:BADVAMBisect* AddonsBisect [vim] [arg1] ... *:AddonsBisect* Command that helps find which one of the activated plugins is causing the problem. In order to do this it launches new vim instance which will activate only half (1/4, 1/8 and so on) of the plugins currently activated. In newly launched vim you are able to use :OKVAMBisect command to mark this set of plugins as non-problematic and :BADVAMBisect to mark this set of plugins as problematic. It will repeat bisection until there is only one plugin in the list. If arguments are given they are used as a command that launches vim. If you know how to make vim test whether problem occurs use > AddonsBisect vim -c if\ has(problem)|BADVAMBisect|else|OKVAMBisect|endif < (note the space escaping). ------------------------------------------------------------------------------ 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": "https://github.com/{Name}/vim-addon-{Name}} github:{N}/{Repo} {"type": "git", "url": "https://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 it 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|. Note 3: Utilized by |VAM-plugin_dir_by_name|. If you override that function option may have effect only on a limited set of undocumented options. additional_addon_dirs *VAM-additional-addon-dirs* List of directories. If present, plugins will be looked up in those directories additionally to |VAM-plugin_root_dir|. Note: Utilized by |VAM-plugin_dir_by_name|. If you override that function option may have no effect. *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-pi. 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". 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: "". Spaces and bars are not escaped. Use zero to disable this completely. 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. source_missing_files *VAM-source_missing_files* Bool, determines whether VAM should check whether all plugin/ files were sourced at the point of |VimEnter| event and source missed ones. Default: 1. This is needed if you load additional plugins in a plugin/*.vim file which may happen if you use http://github.com/MarcWeber/vim-addon-local-vimrc for instance The following options are used by vim-pi, 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, |vim-pi| 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 |vim-pi|, 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 www.vim.org script numbers to |vim-pi| 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* Some documentation will be moved to vim-wiki: http://vim-wiki.mawercer.de/wiki/topic/addon-info.json.html Example: > { dependencies : { 'dependency-1-name': {}, 'dependency-2-name': {} } } 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. 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. Depending on `script-type' and `target_dir' keys this file will be put under: 1. {root}/{target_dir} if `target_dir' key exists. 2. {root}/syntax, {root}/indent, {root}/ftplugin if `script-type' is equal to "syntax", "indent" or "ftplugin" respectively. 3. {root}/colors if `script-type' is equal to "color scheme". 4. {root}/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 (assuming you installed it in ~/.vim/vim-addons) > cd ~/.vim/vim-addons hg clone http://hg.code.sf.net/p/vimpluginloader/dev-tools cd dev-tools ./test.zsh -a vim-addon-manager . If test fails test.zsh prints out a list of failed tests and exits with non-zero code. Dependencies: - zsh - perl - YAML::Any (+some YAML implementation) and WWW::Mechanize perl packages Note: YAML implementation must accept YAML files without leading ---. YAML parser shipped with perl does not accept them, use YAML::LibYAML. - vim Tests dependencies (not required for test.zsh, but for the tests themselves): - git, mercurial, subversion and bazaar version control systems - wget or curl. Unlike VAM tests cannot use any other downloader. - 7z or zip and tar+gzip+bzip2 - vimball plugin ============================================================================== 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://hg.code.sf.net/p/vimpluginloader/pluginloader-overlay or https://bitbucket.org/ZyX_I/pluginloader-overlay (mirror). 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://hg.code.sf.net/p/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: > pluginloader-overlay Overlay that contains some additional vim plugins http://hg.code.sf.net/p/vimpluginloader/pluginloader-overlay 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* Using a $SHELL setting other than /bin/sh may not work on *nix like systems [BUG 101] Directories with commas are not supported. Any discussion is here: https://github.com/MarcWeber/vim-addon-manager/issues/101 [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) 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', 1),"\n") if f =~ '/db/' | continue | endif exec 'source '.fnameescape(f) endfor < [4]: VAM depends on git. Why does it? |vim-pi| 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. ------------------------------------------------------------------------------ 12.1. Common error messages *VAM-common-errors* 1. unknown function: vam#ActivateAddons This means that Vim's |runtimepath| setting does not contain the path you have VAM in. Using the recommended setup this should not happen. Have a second glance at the minimal setup at |VAM-install|. See also |autoload|. ============================================================================== 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 |vim-pi| then. [5] - full update must be done by :UpdateAddons -known 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. What about parallel installation, fetching, activation, ... ~ Possible problems: - activation order could be important, the plugin manager eventually does not know (yet) - Vim itself does not allow parallel processing, thus this make VAM depend on external tools such as parallel, python or the like. It has been a design choice to keep things simple (VimL only). - While loading plugins at runtime works mostly it does not work always, thus installing a plugin and activating it later might change behaviour. And that has been a design choice that you can trust (as much as possible) that the result of a VAM installation behaves the same. (no version locking yet, I know - if you need it create a github bug) - parallel updating can be implemented trivially, eg using shell scripting: for git in ~/.vim/vim-addons/*/*.git; do cd $(dirname $git); git pull & done ============================================================================== 14. VAM vs ... *VAM-comparison* Up to date information will be found on this wiki: See http://vim-wiki.mawercer.de/wiki/topic/vim%20plugin%20managment.html ------------------------------------------------------------------------------ 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). + Does not allow changing installation directory. + No post-install and post-update hooks. + Allows only git sources. - Vundle has a command to clean unused plugins. - Vundle has “interactive mode” which speeds up certain workflows. ------------------------------------------------------------------------------ 14.4. VAM vs Neobundle *VAM-vs-neobundle* URL: https://github.com/Shougo/neobundle.vim + Dependencies are specified in the vimrc, not in the installed plugin. - Allows lazy loading of the plugins (autocommands, commands, mappings, functions and filetypes that trigger the load are specified in the vimrc). - Is able to check for presence of some executables (i.e. external commands dependencies). Is also specified in the vimrc though. - Supports revision lock. - Has a command to clean unused plugins. - Supports unite.vim for interaction (interactive updating, installing, updating, removing, previewing documentation, reinstalling, opening plugin directory and plugin page). - Supports unite.vim for searching. ------------------------------------------------------------------------------ 14.5. 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. + No post-install and post-update hooks. - 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.6. 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.7. VAM vs vim-plug *VAM-vs-vimplug* URL: https://github.com/c9s/Vimana vim-plug allows lazy loading and parallel installation/updating. I don't know much about it ------------------------------------------------------------------------------ 14.17. 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): ~ > hg log -l 500 # list last 500 changes of repositories hg update 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(':p:h:h', 1) " 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. ------------------------------------------------------------------------------ 16.1. The perfect plugin *VAM-plugin-guide* Well - this should not be here either - and its only "my personal view on it". useful plugins for developing in VimL: vim-dev and reload. plugin/NAME.vim is sourced always. Thus it should only contain the user interface configuration and code which is always used anyway (autocommands, mappings, commands). autoload/NAME.vim is loaded as needed. It should contain the remaining code. syntax/ contains syntax files. ftdetect/ contains rules to assign file types to files. colors/ contains color schemes. You may want to use :h plugin or :helpgrep to find details in the Vim help. I personally don't like globbering the golbal namespace with > if !exists(g:my_plugin_width') let g:my_plugin_width = 20 endif because it is harder to read (3 lines). Historically Vim did not support dictionaries, so using g:foo{'var'} = value was the only way. Today Vim supports dictionaries which is why I personally prefer the “bind global named dictionary to a short local s: var”. VAM itself shows how to do it (grep for s:c) Almost of all of my plugins follow these rules. common rules: - rather be simple than complicated - follow the principle of least surprise - try to find an existing plugin, join. - if you have to write from scratch document why - consider referencing related projects which do similar things. After all we're a community and our task is to keep it healthy thus to provide value to each other. - ... ============================================================================== 17. VAM tricks and hacks *VAM-tricks* Create these directories: > ~/.vim/after/plugin/after-vim.vim ~/.vim/ftdetect/ftdetect-vim.vim ~/my/after/plugin/after-foreign.vim ~/my/ftdetect/ftdetect-foreign.vim and add the following line to the each of them: > echomsg expand(':t', 1) < ~/.vimrc contents: > filetype on set rtp+=~/my You will now notice that you have only after-vim.vim and ftdetect-vim.vim lines in messages. But being put into ~/.vim/vim-addons after/ and ftdetect/ directories present in some plugins are equivalent to ~/my/after and ~/my/ftdetect from the example. VAM will source after-foreign.vim and ftdetect-foreign.vim for you, see vam#GlobThenSource usage. Also see this line in source: " HACKS source files which Vim only sources at startup (before VimEnter) grep for this source line to learn about how VAM runs autocommand events for plugins loaded at runtime: > let newaugs = filter(s:GetAuGroups(), '!has_key(oldaugs, v:key)') ============================================================================== 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