Commit: runtime(doc): clarify vim9 script autoload mechanism

[Christian Brabandt]

runtime(doc): clarify vim9 script autoload mechanism

Commit: https://github.com/vim/vim/commit/935fa240ea276f7bf361be87a1b0aa3ea15fd33a
Author: Ubaldo Tiberi <ubaldo...@volvo.com>
Date: Mon Jul 27 18:40:49 2026 +0000

runtime(doc): clarify vim9 script autoload mechanism

closes: https://github.com/vim/vim/issues/20833

Signed-off-by: Ubaldo Tiberi <ubaldo...@volvo.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/usr_52.txt b/runtime/doc/usr_52.txt
index f59e74b4e..b34a80d49 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