API level is disconnected from NVIM version. The API metadata holds the
current API level, and the lowest backwards-compatible level supported
by this instance.
Release 0.1.6 is the first release that reports the Nvim version and API
level.
metadata['version'] = {
major: 0,
minor: 1,
patch: 6,
api_level: 1,
api_compatible: 0,
api_prerelease: false,
}
The API level may remain unchanged across Nvim releases if the API has
not changed.
When changing the API,
- set NVIM_API_PRERELEASE to true
- increment NVIM_API_LEVEL (at most once per Nvim version)
- adjust NVIM_API_LEVEL_COMPAT if backwards-compatibility was broken
api_level_0.mpack was generated from Nvim 0.1.5 with:
nvim --api-info
The API level is disconnected from the NVIM version. The API metadata
holds the current API level, and the lowest backwards-compatible level
supported by this instance.
Release 0.1.6 will be the first release reporting the Nvim version and
API level.
metadata['version'] = {
major: 0,
minor: 1,
patch: 6,
prerelease: true,
api_level: 1,
api_compatible: 0,
}
The API level may remain unchanged across Neovim releases if the API has
not changed.
When changing the API the CMake variable NVIM_API_PRERELEASE is set to
true, and NVIM_API_CURRENT/NVIM_API_COMPATIBILITY are incremented
accordingly.
The functional tests check the API table against fixtures of past
versions of Neovim. It compares all the functions in the old table with
the new one, it does ignore some metadata attributes that do not alter
the function signature or were removed since 0.1.5. Currently the only
fixture is 0.mpack, generated from Neovim 0.1.5 with nvim --api-info.
If nvim is built from a non-tagged commit, the truncated commit hash is
already appended to the main version string (e.g., "NVIM v0.1.0-83-g959f260 ..."),
making the "Commit:" field redundant.
Regarding the truncated hash length: we don't have nearly enough commits
to worry about collisions, and probably won't ever, so the default
length should be fine.
When building in a git repo:
- If HEAD corresponds to an annotated tag, (i.e. git_get_exact_tag()
returns truthy) the current build is considered a "release" build:
NVIM_VERSION_MEDIUM is directly assigned the tagged version name,
and NVIM_VERSION_* defines are ignored.
- If HEAD is not a tagged release, then NVIM_VERSION_MEDIUM is
directly assigned the result of `git describe`.
If git (or the repo) is not available:
- The NVIM_VERSION_* defines are used to define NVIM_VERSION_MEDIUM.
Sample outputs for `nvim --version` and `nvim +version`:
Building with git @ non-tagged commit e66df14:
NVIM v0.1.0-1-ge66df14 (compiled Nov 1 2015 19:10:30)
Commit: e66df148f9401be17adab324a6e41d927aae20b3
Building with git @ v0.1.1 tag:
NVIM v0.1.1 (compiled Nov 1 2015 19:03:52)
[no "Commit:" line]
Building this commit _not_ in a git repo:
NVIM 0.1.0-dev (compiled Nov 1 2015 19:16:11)
[no "Commit:" line]
* Hide commit information from --version if we can't find any (e.g. when
building from tarball).
To define a release in CMake, set NVIM_VERSION_PRERELEASE to "".
This will modify --version output to:
* Show annotated Git tag instead of commit hash (NVIM_VERSION_COMMIT).
* Hide commit date (NVIM_VERSION_BUILD).
