:h vim-addon-manager-additional-documentation.txt

vim-addon-manager-additional-documentation.txt Declarative package manager for VimLINK

==============================================================================

CONTENTS VAM-contents-additionalLINK

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-functionalityLINK

------------------------------------------------------------------------------

3.1. Commands VAM-commandsLINK

InstallAddons {name} ... :InstallAddonsLINK

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} ... :RunInstallHooksLINK

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} ... :ActivateAddonsLINK

Activate addons with given names. See vam#ActivateAddons() for

more details.

ActivateInstalledAddons {name} ... :ActivateInstalledAddonsLINK

See :ActivateAddons, this command is just the same, but completion

function completes only installed addon names.

UpdateAddons [{name} ...] :UpdateAddonsLINK

Update addons with given names. Without arguments updates all addons.

See vam#install#Update() for more details.

UpdateActivatedAddons :UpdateActivatedAddonsLINK

Like :UpdateAdons with a list of all activated plugins in place of

its arguments.

ListActivatedAddons :ListActivatedAddonsLINK

List all currently activated addons.

UninstallNotLoadedAddons {name} ... :UninstallNotLoadedAddonsLINK

Unistall addons with given names. See

vam#install#UninstallAddons() for more details.

AddonsInfo {id/name/any-regex} ... :AddonsInfoLINK

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 directhory 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 :BADVAMBisectLINK

AddonsBisect [vim] [arg1] ... :AddonsBisectLINK

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-functionsLINK

vam#ActivateAddons({addons}[, {opts}]) vam#ActivateAddons()LINK

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()LINK

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()LINK

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()LINK

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()LINK

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 UnmergePluginFiles call vam#install#UnmergePluginFiles()

Yes, the info files should be cached as well (TODO)

vam#install#RewriteName({name}) vam#install#RewriteName()LINK

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()LINK

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#GitCheckoutLINK

vam#vcs#MercurialCheckout vam#vcs#MercurialCheckoutLINK

vam#vcs#SubversionCheckout vam#vcs#SubversionCheckoutLINK

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-optionsLINK

g:vim_addon_managerLINK

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_installLINK

This options disables plugin installation confirmation. It will not

disable deprecation warnings and other prompts.

plugin_sources VAM-plugin_sourcesLINK

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_dirLINK

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-dirsLINK

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_policyLINK

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-knownLINK

String, specifies the name of plugin which provides list of

repositories. Default is vim-pi.

change_to_unix_ff VAM-change_to_unix_ffLINK

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_diffLINK

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_rewritingLINK

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_nameLINK

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-scmsLINK

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_funLINK

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_lhsLINK

{lhs} of the mapping that uses vam#install#CompleteAddonName() for

completion. Default: "<C-x><C-p>". Spaces and bars are not escaped.

Use zero to disable this completely.

shell_commands_run_method VAM-shell_commands_run_methodLINK

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-hooksLINK

post_install_hook_functions VAM-post_install_hook_functionsLINK

pre_update_hook_functions VAM-pre_update_hook_functionsLINK

post_update_hook_functions VAM-post_update_hook_functionsLINK

post_scms_update_hook_functions VAM-post_scms_update_hook_functionsLINK

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_activationLINK

Bool, makes VAM print lines explaining reasons for activation

particular plugins. Not pretty - but helpful in some cases.

source_missing_files VAM-source_missing_filesLINK

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_sourcesLINK

drop_git_sources VAM-drop_git_sourcesLINK

drop_hg_sources VAM-drop_hg_sourcesLINK

drop_svn_sources VAM-drop_svn_sourcesLINK

drop_bzr_sources VAM-drop_bzr_sourcesLINK

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_strategyLINK

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-MergeSourcesLINK

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-pluginsLINK

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-infoLINK

addon-info.json addon-info.txtLINK

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-nameLINK

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-repositoryLINK

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-hooksLINK

post-install-hook addon-info-post-install-hookLINK

post-update-hook addon-info-post-update-hookLINK

post-scms-update-hook addon-info-post-scms-update-hookLINK

pre-update-hook addon-info-pre-update-hookLINK

Contains VimL command (string), that is :executed 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-dependenciesLINK

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-versionLINK

author addon-info-authorLINK

maintainer addon-info-maintainerLINK

description addon-info-descriptionLINK

homepage addon-info-homepageLINK

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-relatedLINK

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-authorLINK

Github account: MarcWeber

Email: marco-oweber@gmx.de

------------------------------------------------------------------------------

7.2. Contributors VAM-contributorsLINK

(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