From: Ubaldo Tiberi Date: Mon, 27 Jul 2026 18:40:49 +0000 (+0000) Subject: runtime(doc): clarify vim9 script autoload mechanism X-Git-Tag: v9.2.0860~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=935fa240ea276f7bf361be87a1b0aa3ea15fd33a;p=thirdparty%2Fvim.git runtime(doc): clarify vim9 script autoload mechanism closes: #20833 Signed-off-by: Ubaldo Tiberi Signed-off-by: Christian Brabandt --- diff --git a/runtime/doc/usr_52.txt b/runtime/doc/usr_52.txt index f59e74b4eb..b34a80d490 100644 --- a/runtime/doc/usr_52.txt +++ b/runtime/doc/usr_52.txt @@ -1,4 +1,4 @@ -*usr_52.txt* For Vim version 9.2. Last change: 2026 Feb 14 +*usr_52.txt* For Vim version 9.2. Last change: 2026 Jul 27 VIM USER MANUAL by Bram Moolenaar @@ -136,47 +136,83 @@ prefix that is very unlikely to be used elsewhere. For example, if you have a ============================================================================== *52.2* Autoloading -After splitting your large script into pieces, all the lines will still be -loaded and executed the moment the script is used. Every `import` loads the -imported script to find the items defined there. Although that is good for -finding errors early, it also takes time. Which is wasted if the -functionality is not often used. +After splitting a large script into pieces, an imported script is loaded and +executed at the moment the importing script is sourced. Every |:import| loads +the imported script to find the items defined there. However, if an imported +script is large, then the startup time may become noticeably slower, but on +the other hand if there are errors they will be detected at import time. -Instead of having `import` load the script immediately, it can be postponed -until needed. Using the example above, only one change needs to be made in -the plugin/theplugin.vim script: > +To avoid long startup times, the loading of an imported script may be deferred +until it is actually needed. This is done with the `autoload` keyword. Using +the example above, only one change is needed in `plugin/theplugin.vim`: +> import autoload "../lib/getmessage.vim" - +< Nothing in the rest of the script needs to change. However, the types will -not be checked. Not even the existence of the GetMessage() function is -checked until it is used. You will have to decide what is more important for -your script: fast startup or getting errors early. You can also add the -"autoload" argument later, after you have checked everything works. +not be checked, and "../lib/getmessage.vim" is not loaded at import time; Vim +only verifies that the file exists and is readable. Not even the existence of +the GetMessage() function is checked until it is used. As a result, errors in +the "getmessage.vim" script are detected only at runtime. +You will have to decide what is more important for your script: fast startup +or getting errors early. -AUTOLOAD DIRECTORY +A practical strategy is to omit the `autoload` keyword during development and +debugging so that errors are reported immediately, then add it back before +distributing your plugin to improve startup performance. -Another form is to use autoload with a script name that is not an absolute or -relative path: > - import autoload "monthlib.vim" -This will search for the script "monthlib.vim" in the autoload directories of -'runtimepath'. With Unix one of the directories often is "~/.vim/autoload". -It will also search under 'packpath', under "start". +AUTOLOAD DIRECTORIES -The main advantage of this is that this script can be easily shared with other -scripts. You do need to make sure that the script name is unique, since Vim -will search all the "autoload" directories in 'runtimepath', and if you are -using several plugins with a plugin manager, it may add a directory to -'runtimepath', each of which might have an "autoload" directory. +Another way to lazily load scripts is to `import autoload` a script without +specifying any relative or absolute path, like in the following example: > -Without autoload: > + import autoload "monthlib.vim" +< +Vim searches for the script in the "autoload" directories under 'runtimepath'. +This means that the script must reside in an "autoload" folder. On Unix +systems, one such directory is often `~/.vim/autoload`. It will also search +under 'packpath', under "start". + +When a script is imported this way, its exported symbols are referenced +through a global autoload namespace rather than remaining local to the +importing script. + +Since Vim searches every "autoload" directory in 'runtimepath', choose a +unique script name. Plugin managers often add multiple directories to +'runtimepath', each of which may contain an "autoload" directory. + +The two forms of `import autoload` are summarized as follows: + +- `import autoload "foo.vim"` + Vim searches 'runtimepath' for the script. Because such scripts must reside + under an "autoload" directory, exported symbols are available through the + global autoload namespace. + +- `import autoload "/some/path/foo.vim"` + If the resolved path falls under an "autoload" directory, exported symbols + are likewise in the global autoload namespace; otherwise they remain local + to the importing script. + +The main advantage of accessing symbols through the global autoload namespace +is that the script can be easily imported by other scripts, and symbols can +be used straight away. However, this has some drawbacks when reloading a +script, see |vim9-reload| for more info. + +When symbols are in script-local scope, sharing them across scripts is more +involved and there is no general rule: the right approach depends on the +plugin layout. + +Finally, when a script is imported without `autoload` and without path, like +the following example: > import "monthlib.vim" - +< Vim will search for the script "monthlib.vim" in the import directories of -'runtimepath'. Note that in this case adding or removing "autoload" changes -where the script is found. With a relative or absolute path the location does -not change. +'runtimepath'. + +In this case, adding or removing the `autoload` keyword changes where Vim +searches for the script. When a relative or absolute path is used, then the +location does not change. ============================================================================== *52.3* Autoloading without import/export